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:
When testOnBorrow
is set, the pool will
attempt to validate each object before it is returned from the
borrowObject()
method. (Using the provided factory's
PoolableObjectFactory.validateObject(Object)
method.) Objects that fail
to validate will be dropped from the pool, and a different object will
be borrowed.
When testOnReturn
is set, the pool will
attempt to validate each object before it is returned to the pool in the
returnObject(Object)
method. (Using the provided factory's
PoolableObjectFactory.validateObject(Object)
method.) Objects that fail to validate will be dropped from the pool.
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:
-
timeBetweenEvictionRunsMillis
indicates how long the eviction thread should sleep before "runs" of examining
idle objects. When non-positive, no eviction thread will be launched.
-
minEvictableIdleTimeMillis
specifies the minimum amount of time that an object may sit idle in the pool
before it is eligable for eviction due to idle time. When non-positive, no object
will be dropped from the pool due to idle time alone.
-
testWhileIdle
indicates whether or not idle
objects should be validated using the factory's
PoolableObjectFactory.validateObject(Object)
method. Objects
that fail to validate will be dropped from the pool.
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(PoolableObjectFactory)
before the pool is used.
DEFAULT_MAX_ACTIVE
public static final int DEFAULT_MAX_ACTIVE
The default cap on the total number of active instances from the pool.
- 8
getMaxActive()
DEFAULT_MAX_IDLE
public static final int DEFAULT_MAX_IDLE
The default cap on the number of "sleeping" instances in the pool.
- 8
getMaxIdle()
, setMaxIdle(int)
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.
- 0
getMinIdle()
, setMinIdle(int)
GenericObjectPool
public GenericObjectPool()
Create a new GenericObjectPool.
GenericObjectPool
public GenericObjectPool(PoolableObjectFactory factory)
Create a new GenericObjectPool using the specified values.
factory
- the (possibly null)PoolableObjectFactory to use to create, validate and destroy objects
GenericObjectPool
public GenericObjectPool(PoolableObjectFactory factory,
int maxActive)
Create a new GenericObjectPool using the specified values.
factory
- the (possibly null)PoolableObjectFactory to use to create, validate and destroy objectsmaxActive
- the maximum number of objects that can be borrowed from me at one time (see setMaxActive(int)
)
GenericObjectPool
public GenericObjectPool(PoolableObjectFactory factory,
int maxActive,
byte whenExhaustedAction,
long maxWait)
Create a new GenericObjectPool using the specified values.
factory
- the (possibly null)PoolableObjectFactory to use to create, validate and destroy objectsmaxActive
- 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(PoolableObjectFactory factory,
int maxActive,
byte whenExhaustedAction,
long maxWait,
boolean testOnBorrow,
boolean testOnReturn)
Create a new GenericObjectPool using the specified values.
factory
- the (possibly null)PoolableObjectFactory to use to create, validate and destroy objectsmaxActive
- 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(Object)
method (see getTestOnReturn()
)
GenericObjectPool
public GenericObjectPool(PoolableObjectFactory factory,
int maxActive,
byte whenExhaustedAction,
long maxWait,
int maxIdle)
Create a new GenericObjectPool using the specified values.
factory
- the (possibly null)PoolableObjectFactory to use to create, validate and destroy objectsmaxActive
- 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(PoolableObjectFactory factory,
int maxActive,
byte whenExhaustedAction,
long maxWait,
int maxIdle,
boolean testOnBorrow,
boolean testOnReturn)
Create a new GenericObjectPool using the specified values.
factory
- the (possibly null)PoolableObjectFactory to use to create, validate and destroy objectsmaxActive
- 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(Object)
method (see getTestOnReturn()
)
GenericObjectPool
public GenericObjectPool(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.
factory
- the (possibly null)PoolableObjectFactory to use to create, validate and destroy objectsmaxActive
- 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(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(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.
factory
- the (possibly null)PoolableObjectFactory to use to create, validate and destroy objectsmaxActive
- 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(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)
)
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.
- addObject in interface ObjectPool
- addObject in interface BaseObjectPool
evict
public void evict()
throws Exception
getMaxActive
public int getMaxActive()
Returns the cap on the total number of active instances from my pool.
- the cap on the total number of active instances from my pool.
setMaxActive(int)
getMaxIdle
public int getMaxIdle()
Returns the cap on the number of "idle" instances in the pool.
- the cap on the number of "idle" instances in the pool.
setMaxIdle(int)
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)
- The minimum number of objects.
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.
setTestOnBorrow(boolean)
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.
setTimeBetweenEvictionRunsMillis(long)
setMaxActive
public void setMaxActive(int maxActive)
Sets the cap on the total number of active instances from my pool.
maxActive
- The cap on the total number of active instances from my pool.
Use a negative value for an infinite number of instances.
getMaxActive()
setMaxIdle
public void setMaxIdle(int maxIdle)
Sets the cap on the number of "idle" instances in the pool.
maxIdle
- The cap on the number of "idle" instances in the pool.
Use a negative value to indicate an unlimited number
of idle instances.
getMaxIdle()
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.
getMinEvictableIdleTimeMillis()
, setTimeBetweenEvictionRunsMillis(long)
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)
minIdle
- The minimum number of objects.
getMinIdle()
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.
getTestOnBorrow()
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.
getTimeBetweenEvictionRunsMillis()
setWhenExhaustedAction
public void setWhenExhaustedAction(byte whenExhaustedAction)
whenExhaustedAction
- the action code, which must be one of
getWhenExhaustedAction()