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.
DEFAULT_MAX_IDLE
public static final int DEFAULT_MAX_IDLE
The default cap on the number of "sleeping" instances in the pool.
DEFAULT_MAX_WAIT
public static final long DEFAULT_MAX_WAIT
DEFAULT_MIN_EVICTABLE_IDLE_TIME_MILLIS
public static final long DEFAULT_MIN_EVICTABLE_IDLE_TIME_MILLIS
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.
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.
DEFAULT_TEST_ON_BORROW
public static final boolean DEFAULT_TEST_ON_BORROW
The default "test on borrow" value.
DEFAULT_TEST_ON_RETURN
public static final boolean DEFAULT_TEST_ON_RETURN
The default "test on return" value.
DEFAULT_TEST_WHILE_IDLE
public static final boolean DEFAULT_TEST_WHILE_IDLE
The default "test while idle" value.
DEFAULT_TIME_BETWEEN_EVICTION_RUNS_MILLIS
public static final long DEFAULT_TIME_BETWEEN_EVICTION_RUNS_MILLIS
The default "time between eviction runs" value.
DEFAULT_WHEN_EXHAUSTED_ACTION
public static final byte DEFAULT_WHEN_EXHAUSTED_ACTION
The default "when exhausted action" for the pool.
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.
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
.
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.
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.
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.
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.
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.
getMaxWait
public long getMaxWait()
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).
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.
getNumTestsPerEvictionRun
public int getNumTestsPerEvictionRun()
Returns the number of objects to examine during each run of the
idle object evictor thread (if any).
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.
getTestOnReturn
public boolean getTestOnReturn()
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.
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.
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).
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.
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.
setMaxWait
public void setMaxWait(long maxWait)
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.
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.
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.
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.
setTestOnReturn
public void setTestOnReturn(boolean testOnReturn)
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.
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.
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).