org.apache.commons.pool.impl
Class GenericObjectPool

java.lang.Object
  |
  +--org.apache.commons.pool.BaseObjectPool
        |
        +--org.apache.commons.pool.impl.GenericObjectPool
All Implemented Interfaces:
ObjectPool

public class GenericObjectPool
extends BaseObjectPool
implements ObjectPool

A configurable ObjectPool implementation.

When coupled with the appropriate PoolableObjectFactory, GenericObjectPool provides robust pooling functionality for arbitrary objects.

A GenericObjectPool provides a number of configurable parameters:

Optionally, one may configure the pool to examine and possibly evict objects as they sit idle in the pool. This is performed by an "idle object eviction" thread, which runs asychronously. The idle object eviction thread may be configured using the following attributes:

GenericObjectPool is not usable without a PoolableObjectFactory. A non-null factory must be provided either as a constructor argument or via a call to setFactory(org.apache.commons.pool.PoolableObjectFactory) before the pool is used.

Version:
$Revision: 1.32 $ $Date: 2004/04/27 20:15:56 $
See Also:
GenericKeyedObjectPool

Nested Class Summary
static class GenericObjectPool.Config
          A simple "struct" encapsulating the configuration information for a GenericObjectPool.
 
Field Summary
static int DEFAULT_MAX_ACTIVE
          The default cap on the total number of active instances from the pool.
static int DEFAULT_MAX_IDLE
          The default cap on the number of "sleeping" instances in the pool.
static long DEFAULT_MAX_WAIT
          The default maximum amount of time (in millis) the borrowObject() method should block before throwing an exception when the pool is exhausted and the "when exhausted" action is WHEN_EXHAUSTED_BLOCK.
static long DEFAULT_MIN_EVICTABLE_IDLE_TIME_MILLIS
          The default value for getMinEvictableIdleTimeMillis().
static int DEFAULT_MIN_IDLE
          The default minimum number of "sleeping" instances in the pool before before the evictor thread (if active) spawns new objects.
static int DEFAULT_NUM_TESTS_PER_EVICTION_RUN
          The default number of objects to examine per run in the idle object evictor.
static boolean DEFAULT_TEST_ON_BORROW
          The default "test on borrow" value.
static boolean DEFAULT_TEST_ON_RETURN
          The default "test on return" value.
static boolean DEFAULT_TEST_WHILE_IDLE
          The default "test while idle" value.
static long DEFAULT_TIME_BETWEEN_EVICTION_RUNS_MILLIS
          The default "time between eviction runs" value.
static byte DEFAULT_WHEN_EXHAUSTED_ACTION
          The default "when exhausted action" for the pool.
static byte WHEN_EXHAUSTED_BLOCK
          A "when exhausted action" type indicating that when the pool is exhausted (i.e., the maximum number of active objects has been reached), the borrowObject() method should block until a new object is available, or the maximum wait time has been reached.
static byte WHEN_EXHAUSTED_FAIL
          A "when exhausted action" type indicating that when the pool is exhausted (i.e., the maximum number of active objects has been reached), the borrowObject() method should fail, throwing a NoSuchElementException.
static byte WHEN_EXHAUSTED_GROW
          A "when exhausted action" type indicating that when the pool is exhausted (i.e., the maximum number of active objects has been reached), the borrowObject() method should simply create a new object anyway.
 
Constructor Summary
GenericObjectPool()
          Create a new GenericObjectPool.
GenericObjectPool(org.apache.commons.pool.PoolableObjectFactory factory)
          Create a new GenericObjectPool using the specified values.
GenericObjectPool(org.apache.commons.pool.PoolableObjectFactory factory, GenericObjectPool.Config config)
          Create a new GenericObjectPool using the specified values.
GenericObjectPool(org.apache.commons.pool.PoolableObjectFactory factory, int maxActive)
          Create a new GenericObjectPool using the specified values.
GenericObjectPool(org.apache.commons.pool.PoolableObjectFactory factory, int maxActive, byte whenExhaustedAction, long maxWait)
          Create a new GenericObjectPool using the specified values.
GenericObjectPool(org.apache.commons.pool.PoolableObjectFactory factory, int maxActive, byte whenExhaustedAction, long maxWait, boolean testOnBorrow, boolean testOnReturn)
          Create a new GenericObjectPool using the specified values.
GenericObjectPool(org.apache.commons.pool.PoolableObjectFactory factory, int maxActive, byte whenExhaustedAction, long maxWait, int maxIdle)
          Create a new GenericObjectPool using the specified values.
GenericObjectPool(org.apache.commons.pool.PoolableObjectFactory factory, int maxActive, byte whenExhaustedAction, long maxWait, int maxIdle, boolean testOnBorrow, boolean testOnReturn)
          Create a new GenericObjectPool using the specified values.
GenericObjectPool(org.apache.commons.pool.PoolableObjectFactory factory, int maxActive, byte whenExhaustedAction, long maxWait, int maxIdle, boolean testOnBorrow, boolean testOnReturn, long timeBetweenEvictionRunsMillis, int numTestsPerEvictionRun, long minEvictableIdleTimeMillis, boolean testWhileIdle)
          Create a new GenericObjectPool using the specified values.
GenericObjectPool(org.apache.commons.pool.PoolableObjectFactory factory, int maxActive, byte whenExhaustedAction, long maxWait, int maxIdle, int minIdle, boolean testOnBorrow, boolean testOnReturn, long timeBetweenEvictionRunsMillis, int numTestsPerEvictionRun, long minEvictableIdleTimeMillis, boolean testWhileIdle)
          Create a new GenericObjectPool using the specified values.
 
Method Summary
 void addObject()
          Create an object, and place it into the pool.
 Object borrowObject()
          Obtain an instance from my pool.
 void clear()
          Clears any objects sitting idle in the pool, releasing any associated resources (optional operation).
 void close()
          Close this pool, and free any resources associated with it.
 void evict()
           
 int getMaxActive()
          Returns the cap on the total number of active instances from my pool.
 int getMaxIdle()
          Returns the cap on the number of "idle" instances in the pool.
 long getMaxWait()
          Returns the maximum amount of time (in milliseconds) the borrowObject() method should block before throwing an exception when the pool is exhausted and the "when exhausted" action is WHEN_EXHAUSTED_BLOCK.
 long getMinEvictableIdleTimeMillis()
          Returns the minimum amount of time an object may sit idle in the pool before it is eligable for eviction by the idle object evictor (if any).
 int getMinIdle()
          Returns the minimum number of objects allowed in the pool before the evictor thread (if active) spawns new objects.
 int getNumActive()
          Return the number of instances currently borrowed from my pool (optional operation).
 int getNumIdle()
          Return the number of instances currently idle in my pool (optional operation).
 int getNumTestsPerEvictionRun()
          Returns the number of objects to examine during each run of the idle object evictor thread (if any).
 boolean getTestOnBorrow()
          When true, objects will be validated before being returned by the borrowObject() method.
 boolean getTestOnReturn()
          When true, objects will be validated before being returned to the pool within the returnObject(java.lang.Object).
 boolean getTestWhileIdle()
          When true, objects will be validated by the idle object evictor (if any).
 long getTimeBetweenEvictionRunsMillis()
          Returns the number of milliseconds to sleep between runs of the idle object evictor thread.
 byte getWhenExhaustedAction()
          Returns the action to take when the borrowObject() method is invoked when the pool is exhausted (the maximum number of "active" objects has been reached).
 void invalidateObject(Object obj)
          Invalidates an object from the pool By contract, obj MUST have been obtained using borrowObject or a related method as defined in an implementation or sub-interface.
 void returnObject(Object obj)
          Return an instance to my pool.
 void setConfig(GenericObjectPool.Config conf)
          Sets my configuration.
 void setFactory(org.apache.commons.pool.PoolableObjectFactory factory)
          Sets the factory I use to create new instances (optional operation).
 void setMaxActive(int maxActive)
          Sets the cap on the total number of active instances from my pool.
 void setMaxIdle(int maxIdle)
          Sets the cap on the number of "idle" instances in the pool.
 void setMaxWait(long maxWait)
          Sets the maximum amount of time (in milliseconds) the borrowObject() method should block before throwing an exception when the pool is exhausted and the "when exhausted" action is WHEN_EXHAUSTED_BLOCK.
 void setMinEvictableIdleTimeMillis(long minEvictableIdleTimeMillis)
          Sets the minimum amount of time an object may sit idle in the pool before it is eligable for eviction by the idle object evictor (if any).
 void setMinIdle(int minIdle)
          Sets the minimum number of objects allowed in the pool before the evictor thread (if active) spawns new objects.
 void setNumTestsPerEvictionRun(int numTestsPerEvictionRun)
          Sets the number of objects to examine during each run of the idle object evictor thread (if any).
 void setTestOnBorrow(boolean testOnBorrow)
          When true, objects will be validated before being returned by the borrowObject() method.
 void setTestOnReturn(boolean testOnReturn)
          When true, objects will be validated before being returned to the pool within the returnObject(java.lang.Object).
 void setTestWhileIdle(boolean testWhileIdle)
          When true, objects will be validated by the idle object evictor (if any).
 void setTimeBetweenEvictionRunsMillis(long timeBetweenEvictionRunsMillis)
          Sets the number of milliseconds to sleep between runs of the idle object evictor thread.
 void setWhenExhaustedAction(byte whenExhaustedAction)
          Sets the action to take when the borrowObject() method is invoked when the pool is exhausted (the maximum number of "active" objects has been reached).
protected  void startEvictor(long delay)
          Start the eviction thread or service, or when delay is non-positive, stop it if it is already running.
 
Methods inherited from class org.apache.commons.pool.BaseObjectPool
assertOpen, isClosed
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

WHEN_EXHAUSTED_FAIL

public static final byte WHEN_EXHAUSTED_FAIL
A "when exhausted action" type indicating that when the pool is exhausted (i.e., the maximum number of active objects has been reached), the borrowObject() method should fail, throwing a NoSuchElementException.

See Also:
WHEN_EXHAUSTED_BLOCK, WHEN_EXHAUSTED_GROW, setWhenExhaustedAction(byte), Constant Field Values

WHEN_EXHAUSTED_BLOCK

public static final byte WHEN_EXHAUSTED_BLOCK
A "when exhausted action" type indicating that when the pool is exhausted (i.e., the maximum number of active objects has been reached), the borrowObject() method should block until a new object is available, or the maximum wait time has been reached.

See Also:
WHEN_EXHAUSTED_FAIL, WHEN_EXHAUSTED_GROW, setMaxWait(long), getMaxWait(), setWhenExhaustedAction(byte), Constant Field Values

WHEN_EXHAUSTED_GROW

public static final byte WHEN_EXHAUSTED_GROW
A "when exhausted action" type indicating that when the pool is exhausted (i.e., the maximum number of active objects has been reached), the borrowObject() method should simply create a new object anyway.

See Also:
WHEN_EXHAUSTED_FAIL, WHEN_EXHAUSTED_GROW, setWhenExhaustedAction(byte), Constant Field Values

DEFAULT_MAX_IDLE

public static final int DEFAULT_MAX_IDLE
The default cap on the number of "sleeping" instances in the pool.

See Also:
getMaxIdle(), setMaxIdle(int), Constant Field Values

DEFAULT_MIN_IDLE

public static final int DEFAULT_MIN_IDLE
The default minimum number of "sleeping" instances in the pool before before the evictor thread (if active) spawns new objects.

See Also:
getMinIdle(), setMinIdle(int), Constant Field Values

DEFAULT_MAX_ACTIVE

public static final int DEFAULT_MAX_ACTIVE
The default cap on the total number of active instances from the pool.

See Also:
getMaxActive(), Constant Field Values

DEFAULT_WHEN_EXHAUSTED_ACTION

public static final byte DEFAULT_WHEN_EXHAUSTED_ACTION
The default "when exhausted action" for the pool.

See Also:
WHEN_EXHAUSTED_BLOCK, WHEN_EXHAUSTED_FAIL, WHEN_EXHAUSTED_GROW, setWhenExhaustedAction(byte), Constant Field Values

DEFAULT_MAX_WAIT

public static final long DEFAULT_MAX_WAIT
The default maximum amount of time (in millis) the borrowObject() method should block before throwing an exception when the pool is exhausted and the "when exhausted" action is WHEN_EXHAUSTED_BLOCK.

See Also:
getMaxWait(), setMaxWait(long), Constant Field Values

DEFAULT_TEST_ON_BORROW

public static final boolean DEFAULT_TEST_ON_BORROW
The default "test on borrow" value.

See Also:
getTestOnBorrow(), setTestOnBorrow(boolean), Constant Field Values

DEFAULT_TEST_ON_RETURN

public static final boolean DEFAULT_TEST_ON_RETURN
The default "test on return" value.

See Also:
getTestOnReturn(), setTestOnReturn(boolean), Constant Field Values

DEFAULT_TEST_WHILE_IDLE

public static final boolean DEFAULT_TEST_WHILE_IDLE
The default "test while idle" value.

See Also:
getTestWhileIdle(), setTestWhileIdle(boolean), getTimeBetweenEvictionRunsMillis(), setTimeBetweenEvictionRunsMillis(long), Constant Field Values

DEFAULT_TIME_BETWEEN_EVICTION_RUNS_MILLIS

public static final long DEFAULT_TIME_BETWEEN_EVICTION_RUNS_MILLIS
The default "time between eviction runs" value.

See Also:
getTimeBetweenEvictionRunsMillis(), setTimeBetweenEvictionRunsMillis(long), Constant Field Values

DEFAULT_NUM_TESTS_PER_EVICTION_RUN

public static final int DEFAULT_NUM_TESTS_PER_EVICTION_RUN
The default number of objects to examine per run in the idle object evictor.

See Also:
getNumTestsPerEvictionRun(), setNumTestsPerEvictionRun(int), getTimeBetweenEvictionRunsMillis(), setTimeBetweenEvictionRunsMillis(long), Constant Field Values

DEFAULT_MIN_EVICTABLE_IDLE_TIME_MILLIS

public static final long DEFAULT_MIN_EVICTABLE_IDLE_TIME_MILLIS
The default value for getMinEvictableIdleTimeMillis().

See Also:
getMinEvictableIdleTimeMillis(), setMinEvictableIdleTimeMillis(long), Constant Field Values
Constructor Detail

GenericObjectPool

public GenericObjectPool()
Create a new GenericObjectPool.


GenericObjectPool

public GenericObjectPool(org.apache.commons.pool.PoolableObjectFactory factory)
Create a new GenericObjectPool using the specified values.

Parameters:
factory - the (possibly null)PoolableObjectFactory to use to create, validate and destroy objects

GenericObjectPool

public GenericObjectPool(org.apache.commons.pool.PoolableObjectFactory factory,
                         GenericObjectPool.Config config)
Create a new GenericObjectPool using the specified values.

Parameters:
factory - the (possibly null)PoolableObjectFactory to use to create, validate and destroy objects
config - a non-null GenericObjectPool.Config describing my configuration

GenericObjectPool

public GenericObjectPool(org.apache.commons.pool.PoolableObjectFactory factory,
                         int maxActive)
Create a new GenericObjectPool using the specified values.

Parameters:
factory - the (possibly null)PoolableObjectFactory to use to create, validate and destroy objects
maxActive - the maximum number of objects that can be borrowed from me at one time (see setMaxActive(int))

GenericObjectPool

public GenericObjectPool(org.apache.commons.pool.PoolableObjectFactory factory,
                         int maxActive,
                         byte whenExhaustedAction,
                         long maxWait)
Create a new GenericObjectPool using the specified values.

Parameters:
factory - the (possibly null)PoolableObjectFactory to use to create, validate and destroy objects
maxActive - the maximum number of objects that can be borrowed from me at one time (see setMaxActive(int))
whenExhaustedAction - the action to take when the pool is exhausted (see getWhenExhaustedAction())
maxWait - the maximum amount of time to wait for an idle object when the pool is exhausted an and whenExhaustedAction is WHEN_EXHAUSTED_BLOCK (otherwise ignored) (see getMaxWait())

GenericObjectPool

public GenericObjectPool(org.apache.commons.pool.PoolableObjectFactory factory,
                         int maxActive,
                         byte whenExhaustedAction,
                         long maxWait,
                         boolean testOnBorrow,
                         boolean testOnReturn)
Create a new GenericObjectPool using the specified values.

Parameters:
factory - the (possibly null)PoolableObjectFactory to use to create, validate and destroy objects
maxActive - the maximum number of objects that can be borrowed from me at one time (see setMaxActive(int))
whenExhaustedAction - the action to take when the pool is exhausted (see getWhenExhaustedAction())
maxWait - the maximum amount of time to wait for an idle object when the pool is exhausted an and whenExhaustedAction is WHEN_EXHAUSTED_BLOCK (otherwise ignored) (see getMaxWait())
testOnBorrow - whether or not to validate objects before they are returned by the borrowObject() method (see getTestOnBorrow())
testOnReturn - whether or not to validate objects after they are returned to the returnObject(java.lang.Object) method (see getTestOnReturn())

GenericObjectPool

public GenericObjectPool(org.apache.commons.pool.PoolableObjectFactory factory,
                         int maxActive,
                         byte whenExhaustedAction,
                         long maxWait,
                         int maxIdle)
Create a new GenericObjectPool using the specified values.

Parameters:
factory - the (possibly null)PoolableObjectFactory to use to create, validate and destroy objects
maxActive - the maximum number of objects that can be borrowed from me at one time (see setMaxActive(int))
whenExhaustedAction - the action to take when the pool is exhausted (see getWhenExhaustedAction())
maxWait - the maximum amount of time to wait for an idle object when the pool is exhausted an and whenExhaustedAction is WHEN_EXHAUSTED_BLOCK (otherwise ignored) (see getMaxWait())
maxIdle - the maximum number of idle objects in my pool (see getMaxIdle())

GenericObjectPool

public GenericObjectPool(org.apache.commons.pool.PoolableObjectFactory factory,
                         int maxActive,
                         byte whenExhaustedAction,
                         long maxWait,
                         int maxIdle,
                         boolean testOnBorrow,
                         boolean testOnReturn)
Create a new GenericObjectPool using the specified values.

Parameters:
factory - the (possibly null)PoolableObjectFactory to use to create, validate and destroy objects
maxActive - the maximum number of objects that can be borrowed from me at one time (see setMaxActive(int))
whenExhaustedAction - the action to take when the pool is exhausted (see getWhenExhaustedAction())
maxWait - the maximum amount of time to wait for an idle object when the pool is exhausted an and whenExhaustedAction is WHEN_EXHAUSTED_BLOCK (otherwise ignored) (see getMaxWait())
maxIdle - the maximum number of idle objects in my pool (see getMaxIdle())
testOnBorrow - whether or not to validate objects before they are returned by the borrowObject() method (see getTestOnBorrow())
testOnReturn - whether or not to validate objects after they are returned to the returnObject(java.lang.Object) method (see getTestOnReturn())

GenericObjectPool

public GenericObjectPool(org.apache.commons.pool.PoolableObjectFactory factory,
                         int maxActive,
                         byte whenExhaustedAction,
                         long maxWait,
                         int maxIdle,
                         boolean testOnBorrow,
                         boolean testOnReturn,
                         long timeBetweenEvictionRunsMillis,
                         int numTestsPerEvictionRun,
                         long minEvictableIdleTimeMillis,
                         boolean testWhileIdle)
Create a new GenericObjectPool using the specified values.

Parameters:
factory - the (possibly null)PoolableObjectFactory to use to create, validate and destroy objects
maxActive - the maximum number of objects that can be borrowed from me at one time (see setMaxActive(int))
whenExhaustedAction - the action to take when the pool is exhausted (see setWhenExhaustedAction(byte))
maxWait - the maximum amount of time to wait for an idle object when the pool is exhausted an and whenExhaustedAction is WHEN_EXHAUSTED_BLOCK (otherwise ignored) (see setMaxWait(long))
maxIdle - the maximum number of idle objects in my pool (see setMaxIdle(int))
testOnBorrow - whether or not to validate objects before they are returned by the borrowObject() method (see setTestOnBorrow(boolean))
testOnReturn - whether or not to validate objects after they are returned to the returnObject(java.lang.Object) method (see setTestOnReturn(boolean))
timeBetweenEvictionRunsMillis - the amount of time (in milliseconds) to sleep between examining idle objects for eviction (see setTimeBetweenEvictionRunsMillis(long))
numTestsPerEvictionRun - the number of idle objects to examine per run within the idle object eviction thread (if any) (see setNumTestsPerEvictionRun(int))
minEvictableIdleTimeMillis - the minimum number of milliseconds an object can sit idle in the pool before it is eligable for evcition (see setMinEvictableIdleTimeMillis(long))
testWhileIdle - whether or not to validate objects in the idle object eviction thread, if any (see setTestWhileIdle(boolean))

GenericObjectPool

public GenericObjectPool(org.apache.commons.pool.PoolableObjectFactory factory,
                         int maxActive,
                         byte whenExhaustedAction,
                         long maxWait,
                         int maxIdle,
                         int minIdle,
                         boolean testOnBorrow,
                         boolean testOnReturn,
                         long timeBetweenEvictionRunsMillis,
                         int numTestsPerEvictionRun,
                         long minEvictableIdleTimeMillis,
                         boolean testWhileIdle)
Create a new GenericObjectPool using the specified values.

Parameters:
factory - the (possibly null)PoolableObjectFactory to use to create, validate and destroy objects
maxActive - the maximum number of objects that can be borrowed from me at one time (see setMaxActive(int))
whenExhaustedAction - the action to take when the pool is exhausted (see setWhenExhaustedAction(byte))
maxWait - the maximum amount of time to wait for an idle object when the pool is exhausted an and whenExhaustedAction is WHEN_EXHAUSTED_BLOCK (otherwise ignored) (see setMaxWait(long))
maxIdle - the maximum number of idle objects in my pool (see setMaxIdle(int))
minIdle - the minimum number of idle objects in my pool (see setMinIdle(int))
testOnBorrow - whether or not to validate objects before they are returned by the borrowObject() method (see setTestOnBorrow(boolean))
testOnReturn - whether or not to validate objects after they are returned to the returnObject(java.lang.Object) method (see setTestOnReturn(boolean))
timeBetweenEvictionRunsMillis - the amount of time (in milliseconds) to sleep between examining idle objects for eviction (see setTimeBetweenEvictionRunsMillis(long))
numTestsPerEvictionRun - the number of idle objects to examine per run within the idle object eviction thread (if any) (see setNumTestsPerEvictionRun(int))
minEvictableIdleTimeMillis - the minimum number of milliseconds an object can sit idle in the pool before it is eligable for evcition (see setMinEvictableIdleTimeMillis(long))
testWhileIdle - whether or not to validate objects in the idle object eviction thread, if any (see setTestWhileIdle(boolean))
Method Detail

getMaxActive

public int getMaxActive()
Returns the cap on the total number of active instances from my pool.

Returns:
the cap on the total number of active instances from my pool.
See Also:
setMaxActive(int)

setMaxActive

public void setMaxActive(int maxActive)
Sets the cap on the total number of active instances from my pool.

Parameters:
maxActive - The cap on the total number of active instances from my pool. Use a negative value for an infinite number of instances.
See Also:
getMaxActive()

getWhenExhaustedAction

public byte getWhenExhaustedAction()
Returns the action to take when the borrowObject() method is invoked when the pool is exhausted (the maximum number of "active" objects has been reached).

Returns:
one of WHEN_EXHAUSTED_BLOCK, WHEN_EXHAUSTED_FAIL or WHEN_EXHAUSTED_GROW
See Also:
setWhenExhaustedAction(byte)

setWhenExhaustedAction

public void setWhenExhaustedAction(byte whenExhaustedAction)
Sets the action to take when the borrowObject() method is invoked when the pool is exhausted (the maximum number of "active" objects has been reached).

Parameters:
whenExhaustedAction - the action code, which must be one of WHEN_EXHAUSTED_BLOCK, WHEN_EXHAUSTED_FAIL, or WHEN_EXHAUSTED_GROW
See Also:
getWhenExhaustedAction()

getMaxWait

public long getMaxWait()
Returns the maximum amount of time (in milliseconds) the borrowObject() method should block before throwing an exception when the pool is exhausted and the "when exhausted" action is WHEN_EXHAUSTED_BLOCK. When less than 0, the borrowObject() method may block indefinitely.

See Also:
setMaxWait(long), setWhenExhaustedAction(byte), WHEN_EXHAUSTED_BLOCK

setMaxWait

public void setMaxWait(long maxWait)
Sets the maximum amount of time (in milliseconds) the borrowObject() method should block before throwing an exception when the pool is exhausted and the "when exhausted" action is WHEN_EXHAUSTED_BLOCK. When less than 0, the borrowObject() method may block indefinitely.

See Also:
getMaxWait(), setWhenExhaustedAction(byte), WHEN_EXHAUSTED_BLOCK

getMaxIdle

public int getMaxIdle()
Returns the cap on the number of "idle" instances in the pool.

Returns:
the cap on the number of "idle" instances in the pool.
See Also:
setMaxIdle(int)

setMaxIdle

public void setMaxIdle(int maxIdle)
Sets the cap on the number of "idle" instances in the pool.

Parameters:
maxIdle - The cap on the number of "idle" instances in the pool. Use a negative value to indicate an unlimited number of idle instances.
See Also:
getMaxIdle()

setMinIdle

public void setMinIdle(int minIdle)
Sets the minimum number of objects allowed in the pool before the evictor thread (if active) spawns new objects. (Note no objects are created when: numActive + numIdle >= maxActive)

Parameters:
minIdle - The minimum number of objects.
See Also:
getMinIdle()

getMinIdle

public int getMinIdle()
Returns the minimum number of objects allowed in the pool before the evictor thread (if active) spawns new objects. (Note no objects are created when: numActive + numIdle >= maxActive)

Returns:
The minimum number of objects.
See Also:
setMinIdle(int)

getTestOnBorrow

public boolean getTestOnBorrow()
When true, objects will be validated before being returned by the borrowObject() method. If the object fails to validate, it will be dropped from the pool, and we will attempt to borrow another.

See Also:
setTestOnBorrow(boolean)

setTestOnBorrow

public void setTestOnBorrow(boolean testOnBorrow)
When true, objects will be validated before being returned by the borrowObject() method. If the object fails to validate, it will be dropped from the pool, and we will attempt to borrow another.

See Also:
getTestOnBorrow()

getTestOnReturn

public boolean getTestOnReturn()
When true, objects will be validated before being returned to the pool within the returnObject(java.lang.Object).

See Also:
setTestOnReturn(boolean)

setTestOnReturn

public void setTestOnReturn(boolean testOnReturn)
When true, objects will be validated before being returned to the pool within the returnObject(java.lang.Object).

See Also:
getTestOnReturn()

getTimeBetweenEvictionRunsMillis

public long getTimeBetweenEvictionRunsMillis()
Returns the number of milliseconds to sleep between runs of the idle object evictor thread. When non-positive, no idle object evictor thread will be run.

See Also:
setTimeBetweenEvictionRunsMillis(long)

setTimeBetweenEvictionRunsMillis

public void setTimeBetweenEvictionRunsMillis(long timeBetweenEvictionRunsMillis)
Sets the number of milliseconds to sleep between runs of the idle object evictor thread. When non-positive, no idle object evictor thread will be run.

See Also:
getTimeBetweenEvictionRunsMillis()

getNumTestsPerEvictionRun

public int getNumTestsPerEvictionRun()
Returns the number of objects to examine during each run of the idle object evictor thread (if any).

See Also:
setNumTestsPerEvictionRun(int), setTimeBetweenEvictionRunsMillis(long)

setNumTestsPerEvictionRun

public void setNumTestsPerEvictionRun(int numTestsPerEvictionRun)
Sets the number of objects to examine during each run of the idle object evictor thread (if any).

When a negative value is supplied, ceil(getNumIdle())/abs(getNumTestsPerEvictionRun()) tests will be run. I.e., when the value is -n, roughly one nth of the idle objects will be tested per run.

See Also:
getNumTestsPerEvictionRun(), setTimeBetweenEvictionRunsMillis(long)

getMinEvictableIdleTimeMillis

public long getMinEvictableIdleTimeMillis()
Returns the minimum amount of time an object may sit idle in the pool before it is eligable for eviction by the idle object evictor (if any).

See Also:
setMinEvictableIdleTimeMillis(long), setTimeBetweenEvictionRunsMillis(long)

setMinEvictableIdleTimeMillis

public void setMinEvictableIdleTimeMillis(long minEvictableIdleTimeMillis)
Sets the minimum amount of time an object may sit idle in the pool before it is eligable for eviction by the idle object evictor (if any). When non-positive, no objects will be evicted from the pool due to idle time alone.

See Also:
getMinEvictableIdleTimeMillis(), setTimeBetweenEvictionRunsMillis(long)

getTestWhileIdle

public boolean getTestWhileIdle()
When true, objects will be validated by the idle object evictor (if any). If an object fails to validate, it will be dropped from the pool.

See Also:
setTestWhileIdle(boolean), setTimeBetweenEvictionRunsMillis(long)

setTestWhileIdle

public void setTestWhileIdle(boolean testWhileIdle)
When true, objects will be validated by the idle object evictor (if any). If an object fails to validate, it will be dropped from the pool.

See Also:
getTestWhileIdle(), setTimeBetweenEvictionRunsMillis(long)

setConfig

public void setConfig(GenericObjectPool.Config conf)
Sets my configuration.

See Also:
GenericObjectPool.Config

borrowObject

public Object borrowObject()
                    throws Exception
Description copied from interface: ObjectPool
Obtain an instance from my pool. By contract, clients MUST return the borrowed instance using returnObject or a related method as defined in an implementation or sub-interface.

The behaviour of this method when the pool has been exhausted is not specified (although it may be specified by implementations).

Specified by:
borrowObject in interface ObjectPool
Specified by:
borrowObject in class BaseObjectPool
Returns:
an instance from my pool.
Exception

invalidateObject

public void invalidateObject(Object obj)
                      throws Exception
Description copied from interface: ObjectPool
Invalidates an object from the pool By contract, obj MUST have been obtained using borrowObject or a related method as defined in an implementation or sub-interface.

This method should be used when an object that has been borrowed is determined (due to an exception or other problem) to be invalid. If the connection should be validated before or after borrowing, then the PoolableObjectFactory.validateObject(java.lang.Object) method should be used instead.

Specified by:
invalidateObject in interface ObjectPool
Specified by:
invalidateObject in class BaseObjectPool
Parameters:
obj - a borrowed instance to be returned.
Exception

clear

public void clear()
Description copied from interface: ObjectPool
Clears any objects sitting idle in the pool, releasing any associated resources (optional operation).

Specified by:
clear in interface ObjectPool
Overrides:
clear in class BaseObjectPool

getNumActive

public int getNumActive()
Description copied from interface: ObjectPool
Return the number of instances currently borrowed from my pool (optional operation).

Specified by:
getNumActive in interface ObjectPool
Overrides:
getNumActive in class BaseObjectPool
Returns:
the number of instances currently borrowed in my pool

getNumIdle

public int getNumIdle()
Description copied from interface: ObjectPool
Return the number of instances currently idle in my pool (optional operation). This may be considered an approximation of the number of objects that can be borrowed without creating any new instances.

Specified by:
getNumIdle in interface ObjectPool
Overrides:
getNumIdle in class BaseObjectPool
Returns:
the number of instances currently idle in my pool

returnObject

public void returnObject(Object obj)
                  throws Exception
Description copied from interface: ObjectPool
Return an instance to my pool. By contract, obj MUST have been obtained using borrowObject or a related method as defined in an implementation or sub-interface.

Specified by:
returnObject in interface ObjectPool
Specified by:
returnObject in class BaseObjectPool
Parameters:
obj - a borrowed instance to be returned.
Exception

close

public void close()
           throws Exception
Description copied from interface: ObjectPool
Close this pool, and free any resources associated with it.

Specified by:
close in interface ObjectPool
Overrides:
close in class BaseObjectPool
Exception

setFactory

public void setFactory(org.apache.commons.pool.PoolableObjectFactory factory)
                throws IllegalStateException
Description copied from interface: ObjectPool
Sets the factory I use to create new instances (optional operation).

Specified by:
setFactory in interface ObjectPool
Overrides:
setFactory in class BaseObjectPool
Parameters:
factory - the PoolableObjectFactory I use to create new instances.
Throws:
IllegalStateException - when the factory cannot be set at this time

evict

public void evict()
           throws Exception
Exception

addObject

public void addObject()
               throws Exception
Create an object, and place it into the pool. addObject() is useful for "pre-loading" a pool with idle objects.

Specified by:
addObject in interface ObjectPool
Overrides:
addObject in class BaseObjectPool
Exception

startEvictor

protected void startEvictor(long delay)
Start the eviction thread or service, or when delay is non-positive, stop it if it is already running.



Copyright © 2001-2004 The Apache Software Foundation. All Rights Reserved.