org.apache.commons.pool.impl
public class GenericKeyedObjectPool extends BaseKeyedObjectPool implements KeyedObjectPool
When coupled with the appropriate KeyedPoolableObjectFactory, GenericKeyedObjectPool provides robust pooling functionality for arbitrary objects.
A GenericKeyedObjectPool provides a number of configurable parameters:
maxActive
controls the maximum number of objects (per key)
that can be borrowed from the pool at one time. When non-positive, there
is no limit to the number of objects that may be active at one time.
When maxActive
is exceeded, the pool is said to be exhausted.
maxIdle
controls the maximum number of objects that can
sit idle in the pool (per key) at any time. When negative, there
is no limit to the number of objects that may be idle at one time.
whenExhaustedAction
specifies the
behaviour of the GenericKeyedObjectPool method when the pool is exhausted:
whenExhaustedAction
is
WHEN_EXHAUSTED_FAIL, GenericKeyedObjectPool will throw
a NoSuchElementException
whenExhaustedAction
is
WHEN_EXHAUSTED_GROW, GenericKeyedObjectPool will create a new
object and return it(essentially making maxActive
meaningless.)
whenExhaustedAction
is WHEN_EXHAUSTED_BLOCK, GenericKeyedObjectPool will block
(invoke Object#wait until a new or idle object is available.
If a positive maxWait
value is supplied, the GenericKeyedObjectPool will block for at
most that many milliseconds, after which a NoSuchElementException
will be thrown. If maxWait
is non-positive,
the GenericKeyedObjectPool method will block indefinitely.
testOnBorrow
is set, the pool will
attempt to validate each object before it is returned from the
GenericKeyedObjectPool method. (Using the provided factory's
KeyedPoolableObjectFactory method.) Objects that fail
to validate will be dropped from the pool, and a different object will
be borrowed.
testOnReturn
is set, the pool will
attempt to validate each object before it is returned to the pool in the
GenericKeyedObjectPool method. (Using the provided factory's
KeyedPoolableObjectFactory
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
KeyedPoolableObjectFactory method. Objects
that fail to validate will be dropped from the pool.
GenericKeyedObjectPool is not usable without a KeyedPoolableObjectFactory. A
non-null
factory must be provided either as a constructor argument
or via a call to GenericKeyedObjectPool before the pool is used.
Version: $Revision: 386116 $ $Date: 2006-03-15 12:15:58 -0500 (Wed, 15 Mar 2006) $
See Also: GenericObjectPool
Nested Class Summary | |
---|---|
static class | GenericKeyedObjectPool.Config
A simple "struct" encapsulating the
configuration information for a GenericKeyedObjectPool. |
Field Summary | |
---|---|
static int | DEFAULT_MAX_ACTIVE
The default cap on the total number of active instances from the pool
(per key). |
static int | DEFAULT_MAX_IDLE
The default cap on the number of idle instances in the pool
(per key). |
static int | DEFAULT_MAX_TOTAL
The default cap on the the maximum number of objects that can exists at one time. |
static long | DEFAULT_MAX_WAIT
The default maximum amount of time (in millis) the
GenericKeyedObjectPool 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 GenericKeyedObjectPool. |
static int | DEFAULT_MIN_IDLE
The default minimum level of idle objects in the pool. |
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 GenericKeyedObjectPool
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 GenericKeyedObjectPool
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 GenericKeyedObjectPool
method should simply create a new object anyway. |
Constructor Summary | |
---|---|
GenericKeyedObjectPool()
Create a new GenericKeyedObjectPool.. | |
GenericKeyedObjectPool(KeyedPoolableObjectFactory factory)
Create a new GenericKeyedObjectPool using the specified values. | |
GenericKeyedObjectPool(KeyedPoolableObjectFactory factory, GenericKeyedObjectPool.Config config)
Create a new GenericKeyedObjectPool using the specified values. | |
GenericKeyedObjectPool(KeyedPoolableObjectFactory factory, int maxActive)
Create a new GenericKeyedObjectPool using the specified values. | |
GenericKeyedObjectPool(KeyedPoolableObjectFactory factory, int maxActive, byte whenExhaustedAction, long maxWait)
Create a new GenericKeyedObjectPool using the specified values. | |
GenericKeyedObjectPool(KeyedPoolableObjectFactory factory, int maxActive, byte whenExhaustedAction, long maxWait, boolean testOnBorrow, boolean testOnReturn)
Create a new GenericKeyedObjectPool using the specified values. | |
GenericKeyedObjectPool(KeyedPoolableObjectFactory factory, int maxActive, byte whenExhaustedAction, long maxWait, int maxIdle)
Create a new GenericKeyedObjectPool using the specified values. | |
GenericKeyedObjectPool(KeyedPoolableObjectFactory factory, int maxActive, byte whenExhaustedAction, long maxWait, int maxIdle, boolean testOnBorrow, boolean testOnReturn)
Create a new GenericKeyedObjectPool using the specified values. | |
GenericKeyedObjectPool(KeyedPoolableObjectFactory factory, int maxActive, byte whenExhaustedAction, long maxWait, int maxIdle, boolean testOnBorrow, boolean testOnReturn, long timeBetweenEvictionRunsMillis, int numTestsPerEvictionRun, long minEvictableIdleTimeMillis, boolean testWhileIdle)
Create a new GenericKeyedObjectPool using the specified values. | |
GenericKeyedObjectPool(KeyedPoolableObjectFactory factory, int maxActive, byte whenExhaustedAction, long maxWait, int maxIdle, int maxTotal, boolean testOnBorrow, boolean testOnReturn, long timeBetweenEvictionRunsMillis, int numTestsPerEvictionRun, long minEvictableIdleTimeMillis, boolean testWhileIdle)
Create a new GenericKeyedObjectPool using the specified values. | |
GenericKeyedObjectPool(KeyedPoolableObjectFactory factory, int maxActive, byte whenExhaustedAction, long maxWait, int maxIdle, int maxTotal, int minIdle, boolean testOnBorrow, boolean testOnReturn, long timeBetweenEvictionRunsMillis, int numTestsPerEvictionRun, long minEvictableIdleTimeMillis, boolean testWhileIdle)
Create a new GenericKeyedObjectPool using the specified values. |
Method Summary | |
---|---|
void | addObject(Object key) |
Object | borrowObject(Object key) |
void | clear() |
void | clear(Object key) |
void | clearOldest()
Method clears oldest 15% of objects in pool. |
void | close() |
void | evict() |
int | getMaxActive()
Returns the cap on the number of active instances from my pool (per key). |
int | getMaxIdle()
Returns the cap on the number of "idle" instances in the pool. |
int | getMaxTotal()
Returns the cap on the total number of instances from my pool if non-positive. |
long | getMaxWait()
Returns the maximum amount of time (in milliseconds) the
GenericKeyedObjectPool 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 idle objects in pool to maintain (per key) |
int | getNumActive() |
int | getNumActive(Object key) |
int | getNumIdle() |
int | getNumIdle(Object key) |
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 GenericKeyedObjectPool
method. |
boolean | getTestOnReturn()
When true, objects will be
validated
before being returned to the pool within the
GenericKeyedObjectPool.
|
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 GenericKeyedObjectPool method
is invoked when the pool is exhausted (the maximum number
of "active" objects has been reached).
|
void | invalidateObject(Object key, Object obj) |
void | preparePool(Object key, boolean populateImmediately)
Registers a key for pool control.
|
void | returnObject(Object key, Object obj) |
void | setConfig(GenericKeyedObjectPool.Config conf)
Sets my configuration. |
void | setFactory(KeyedPoolableObjectFactory factory) |
void | setMaxActive(int maxActive)
Sets the cap on the number of active instances from my pool (per key). |
void | setMaxIdle(int maxIdle)
Sets the cap on the number of "idle" instances in the pool. |
void | setMaxTotal(int maxTotal)
Sets the cap on the total number of instances from my pool if non-positive. |
void | setMaxWait(long maxWait)
Sets the maximum amount of time (in milliseconds) the
GenericKeyedObjectPool 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 poolSize)
Sets the minimum number of idle objects in pool to maintain (per key) |
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 GenericKeyedObjectPool
method. |
void | setTestOnReturn(boolean testOnReturn)
When true, objects will be
validated
before being returned to the pool within the
GenericKeyedObjectPool.
|
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 GenericKeyedObjectPool method
is invoked when the pool is exhausted (the maximum number
of "active" objects has been reached).
|
See Also: GenericKeyedObjectPool GenericKeyedObjectPool
See Also: GenericKeyedObjectPool GenericKeyedObjectPool
See Also: GenericKeyedObjectPool GenericKeyedObjectPool
"when exhausted" action
is
WHEN_EXHAUSTED_BLOCK.See Also: GenericKeyedObjectPool GenericKeyedObjectPool
See Also: GenericKeyedObjectPool GenericKeyedObjectPool
See Also: GenericKeyedObjectPool GenericKeyedObjectPool
See Also: GenericKeyedObjectPool GenericKeyedObjectPool GenericKeyedObjectPool GenericKeyedObjectPool
See Also: GenericKeyedObjectPool GenericKeyedObjectPool
See Also: GenericKeyedObjectPool GenericKeyedObjectPool
See Also: GenericKeyedObjectPool GenericKeyedObjectPool GenericKeyedObjectPool GenericKeyedObjectPool
See Also: GenericKeyedObjectPool GenericKeyedObjectPool
See Also: WHEN_EXHAUSTED_BLOCK WHEN_EXHAUSTED_FAIL WHEN_EXHAUSTED_GROW GenericKeyedObjectPool
maximum wait time
has been reached.See Also: WHEN_EXHAUSTED_FAIL WHEN_EXHAUSTED_GROW GenericKeyedObjectPool GenericKeyedObjectPool GenericKeyedObjectPool
See Also: WHEN_EXHAUSTED_BLOCK WHEN_EXHAUSTED_GROW GenericKeyedObjectPool
See Also: WHEN_EXHAUSTED_FAIL WHEN_EXHAUSTED_GROW GenericKeyedObjectPool
Parameters: factory the (possibly null)KeyedPoolableObjectFactory to use to create, validate and destroy objects
Parameters: factory the (possibly null)KeyedPoolableObjectFactory to use to create, validate and destroy objects config a non-null Config describing my configuration
Parameters: factory the (possibly null)KeyedPoolableObjectFactory to use to create, validate and destroy objects maxActive the maximum number of objects that can be borrowed from me at one time (per key) (see GenericKeyedObjectPool)
Parameters: factory the (possibly null)KeyedPoolableObjectFactory to use to create, validate and destroy objects maxActive the maximum number of objects that can be borrowed from me at one time (per key) (see GenericKeyedObjectPool) whenExhaustedAction the action to take when the pool is exhausted (see GenericKeyedObjectPool) 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 GenericKeyedObjectPool)
Parameters: factory the (possibly null)KeyedPoolableObjectFactory to use to create, validate and destroy objects maxActive the maximum number of objects that can be borrowed from me at one time (per key) (see GenericKeyedObjectPool) 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 GenericKeyedObjectPool) whenExhaustedAction the action to take when the pool is exhausted (see GenericKeyedObjectPool) testOnBorrow whether or not to validate objects before they are returned by the GenericKeyedObjectPool method (see GenericKeyedObjectPool) testOnReturn whether or not to validate objects after they are returned to the GenericKeyedObjectPool method (see GenericKeyedObjectPool)
Parameters: factory the (possibly null)KeyedPoolableObjectFactory to use to create, validate and destroy objects maxActive the maximum number of objects that can be borrowed from me at one time (per key) (see GenericKeyedObjectPool) whenExhaustedAction the action to take when the pool is exhausted (see GenericKeyedObjectPool) 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 GenericKeyedObjectPool) maxIdle the maximum number of idle objects in my pool (per key) (see GenericKeyedObjectPool)
Parameters: factory the (possibly null)KeyedPoolableObjectFactory to use to create, validate and destroy objects maxActive the maximum number of objects that can be borrowed from me at one time (per key) (see GenericKeyedObjectPool) whenExhaustedAction the action to take when the pool is exhausted (see GenericKeyedObjectPool) 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 GenericKeyedObjectPool) maxIdle the maximum number of idle objects in my pool (see GenericKeyedObjectPool) testOnBorrow whether or not to validate objects before they are returned by the GenericKeyedObjectPool method (see GenericKeyedObjectPool) testOnReturn whether or not to validate objects after they are returned to the GenericKeyedObjectPool method (see GenericKeyedObjectPool)
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 (per key) (see GenericKeyedObjectPool) whenExhaustedAction the action to take when the pool is exhausted (see GenericKeyedObjectPool) 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 GenericKeyedObjectPool) maxIdle the maximum number of idle objects in my pool (see GenericKeyedObjectPool) testOnBorrow whether or not to validate objects before they are returned by the GenericKeyedObjectPool method (see GenericKeyedObjectPool) testOnReturn whether or not to validate objects after they are returned to the GenericKeyedObjectPool method (see GenericKeyedObjectPool) timeBetweenEvictionRunsMillis the amount of time (in milliseconds) to sleep between examining idle objects for eviction (see GenericKeyedObjectPool) numTestsPerEvictionRun the number of idle objects to examine per run within the idle object eviction thread (if any) (see GenericKeyedObjectPool) minEvictableIdleTimeMillis the minimum number of milliseconds an object can sit idle in the pool before it is eligable for evcition (see GenericKeyedObjectPool) testWhileIdle whether or not to validate objects in the idle object eviction thread, if any (see GenericKeyedObjectPool)
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 (per key) (see GenericKeyedObjectPool) whenExhaustedAction the action to take when the pool is exhausted (see GenericKeyedObjectPool) 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 GenericKeyedObjectPool) maxIdle the maximum number of idle objects in my pool (see GenericKeyedObjectPool) maxTotal the maximum number of objects that can exists at one time (see GenericKeyedObjectPool) testOnBorrow whether or not to validate objects before they are returned by the GenericKeyedObjectPool method (see GenericKeyedObjectPool) testOnReturn whether or not to validate objects after they are returned to the GenericKeyedObjectPool method (see GenericKeyedObjectPool) timeBetweenEvictionRunsMillis the amount of time (in milliseconds) to sleep between examining idle objects for eviction (see GenericKeyedObjectPool) numTestsPerEvictionRun the number of idle objects to examine per run within the idle object eviction thread (if any) (see GenericKeyedObjectPool) minEvictableIdleTimeMillis the minimum number of milliseconds an object can sit idle in the pool before it is eligable for evcition (see GenericKeyedObjectPool) testWhileIdle whether or not to validate objects in the idle object eviction thread, if any (see GenericKeyedObjectPool)
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 (per key) (see GenericKeyedObjectPool) whenExhaustedAction the action to take when the pool is exhausted (see GenericKeyedObjectPool) 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 GenericKeyedObjectPool) maxIdle the maximum number of idle objects in my pool (see GenericKeyedObjectPool) maxTotal the maximum number of objects that can exists at one time (see GenericKeyedObjectPool) minIdle the minimum number of idle objects to have in the pool at any one time (see GenericKeyedObjectPool) testOnBorrow whether or not to validate objects before they are returned by the GenericKeyedObjectPool method (see GenericKeyedObjectPool) testOnReturn whether or not to validate objects after they are returned to the GenericKeyedObjectPool method (see GenericKeyedObjectPool) timeBetweenEvictionRunsMillis the amount of time (in milliseconds) to sleep between examining idle objects for eviction (see GenericKeyedObjectPool) numTestsPerEvictionRun the number of idle objects to examine per run within the idle object eviction thread (if any) (see GenericKeyedObjectPool) minEvictableIdleTimeMillis the minimum number of milliseconds an object can sit idle in the pool before it is eligable for evcition (see GenericKeyedObjectPool) testWhileIdle whether or not to validate objects in the idle object eviction thread, if any (see GenericKeyedObjectPool)
Returns: the cap on the number of active instances from my pool (per key).
See Also: GenericKeyedObjectPool
Returns: the cap on the number of "idle" instances in the pool.
See Also: GenericKeyedObjectPool
Returns: the cap on the total number of instances from my pool if non-positive.
See Also: GenericKeyedObjectPool
"when exhausted" action
is
WHEN_EXHAUSTED_BLOCK.
When less than 0, the GenericKeyedObjectPool method
may block indefinitely.
See Also: GenericKeyedObjectPool GenericKeyedObjectPool WHEN_EXHAUSTED_BLOCK
See Also: GenericKeyedObjectPool GenericKeyedObjectPool
Returns: the minimum number of idle objects in pool to maintain (per key)
See Also: GenericKeyedObjectPool
See Also: GenericKeyedObjectPool GenericKeyedObjectPool
validated
before being returned by the GenericKeyedObjectPool
method. If the object fails to validate,
it will be dropped from the pool, and we will attempt
to borrow another.
See Also: GenericKeyedObjectPool
validated
before being returned to the pool within the
GenericKeyedObjectPool.
See Also: GenericKeyedObjectPool
validated
by the idle object evictor (if any). If an object
fails to validate, it will be dropped from the pool.
See Also: GenericKeyedObjectPool GenericKeyedObjectPool
See Also: GenericKeyedObjectPool
Returns: one of WHEN_EXHAUSTED_BLOCK, WHEN_EXHAUSTED_FAIL or WHEN_EXHAUSTED_GROW
See Also: GenericKeyedObjectPool
true
, the pool will immediately commence
a sustain cycle. If populateImmediately is false
, the pool will be
populated when the next schedules sustain task is run.
Parameters: key - The key to register for pool control. populateImmediately - If this is true
, the pool
will start a sustain cycle immediately.
See Also: Config
Parameters: maxActive The cap on the number of active instances from my pool (per key). Use a negative value for an infinite number of instances.
See Also: GenericKeyedObjectPool
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: GenericKeyedObjectPool
Parameters: maxTotal The cap on the total number of instances from my pool. Use a non-positive value for an infinite number of instances.
See Also: GenericKeyedObjectPool
"when exhausted" action
is
WHEN_EXHAUSTED_BLOCK.
When less than 0, the GenericKeyedObjectPool method
may block indefinitely.
See Also: GenericKeyedObjectPool GenericKeyedObjectPool WHEN_EXHAUSTED_BLOCK
See Also: GenericKeyedObjectPool GenericKeyedObjectPool
Parameters: poolSize - The minimum size of the pool
See Also: GenericKeyedObjectPool
When a negative value is supplied, ceil(GenericKeyedObjectPool)/abs(GenericKeyedObjectPool) 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: GenericKeyedObjectPool GenericKeyedObjectPool
validated
before being returned by the GenericKeyedObjectPool
method. If the object fails to validate,
it will be dropped from the pool, and we will attempt
to borrow another.
See Also: GenericKeyedObjectPool
validated
before being returned to the pool within the
GenericKeyedObjectPool.
See Also: GenericKeyedObjectPool
validated
by the idle object evictor (if any). If an object
fails to validate, it will be dropped from the pool.
See Also: GenericKeyedObjectPool GenericKeyedObjectPool
See Also: GenericKeyedObjectPool
Parameters: whenExhaustedAction the action code, which must be one of WHEN_EXHAUSTED_BLOCK, WHEN_EXHAUSTED_FAIL, or WHEN_EXHAUSTED_GROW
See Also: GenericKeyedObjectPool