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:
-
#setMaxActive controls the maximum number of
objects that can be allocated by the pool (checked out to clients, or
idle awaiting checkout) at a given time. When non-positive, there is no
limit to the number of objects that can be managed by the pool at one time.
When
#setMaxActive is reached, the pool is said
to be exhausted. The default setting for this parameter is 8.
-
#setMaxIdle controls the maximum number of objects
that can sit idle in the pool at any time. When negative, there is no
limit to the number of objects that may be idle at one time. The default
setting for this parameter is 8.
-
#setWhenExhaustedAction specifies the
behavior of the
#borrowObject method when the pool is exhausted:
-
When
#setWhenExhaustedAction is
#WHEN_EXHAUSTED_FAIL,
#borrowObject will throw
a
NoSuchElementException
-
When
#setWhenExhaustedAction is
#WHEN_EXHAUSTED_GROW,
#borrowObject will create a new
object and return it (essentially making
#setMaxActivemeaningless.)
-
When
#setWhenExhaustedActionis
#WHEN_EXHAUSTED_BLOCK,
#borrowObject will block
(invoke
Object#wait()) until a new or idle object is available.
If a positive
#setMaxWaitvalue is supplied, then
#borrowObject will block for at
most that many milliseconds, after which a
NoSuchElementExceptionwill be thrown. If
#setMaxWait is non-positive,
the
#borrowObject method will block indefinitely.
The default whenExhaustedAction setting is
#WHEN_EXHAUSTED_BLOCK and the default maxWait
setting is -1. By default, therefore, borrowObject will
block indefinitely until an idle instance becomes available.
-
When
#setTestOnBorrow 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 method.) Objects that fail
to validate will be dropped from the pool, and a different object will
be borrowed. The default setting for this parameter is
false.
-
When
#setTestOnReturn is set, the pool will
attempt to validate each object before it is returned to the pool in the
#returnObject method. (Using the provided factory's
PoolableObjectFactory#validateObjectmethod.) Objects that fail to validate will be dropped from the pool.
The default setting for this parameter is
false.
Optionally, one may configure the pool to examine and possibly evict objects
as they sit idle in the pool and to ensure that a minimum number of idle
objects are available. This is performed by an "idle object eviction"
thread, which runs asynchronously. Caution should be used when configuring
this optional feature. Eviction runs require an exclusive synchronization
lock on the pool, so if they run too frequently and / or incur excessive
latency when creating, destroying or validating object instances,
performance issues may result. The idle object eviction thread may be
configured using the following attributes:
-
#setTimeBetweenEvictionRunsMillisindicates how long the eviction thread should sleep before "runs" of examining
idle objects. When non-positive, no eviction thread will be launched. The
default setting for this parameter is -1 (i.e., idle object eviction is
disabled by default).
-
#setMinEvictableIdleTimeMillisspecifies the minimum amount of time that an object may sit idle in the pool
before it is eligible for eviction due to idle time. When non-positive, no object
will be dropped from the pool due to idle time alone. This setting has no
effect unless
timeBetweenEvictionRunsMillis > 0. The default
setting for this parameter is 30 minutes.
-
#setTestWhileIdle indicates whether or not idle
objects should be validated using the factory's
PoolableObjectFactory#validateObject method. Objects that fail to
validate will be dropped from the pool. This setting has no effect unless
timeBetweenEvictionRunsMillis > 0. The default setting for
this parameter is false.
-
#setSoftMinEvictableIdleTimeMillisspecifies the minimum amount of time an object may sit idle in the pool
before it is eligible for eviction by the idle object evictor
(if any), with the extra condition that at least "minIdle" object instances
remain in the pool. When non-positive, no objects will be evicted from the pool
due to idle time alone. This setting has no effect unless
timeBetweenEvictionRunsMillis > 0. and it is superceded by
#setMinEvictableIdleTimeMillis(that is, if minEvictableIdleTimeMillis is positive, then
softMinEvictableIdleTimeMillis is ignored). The default setting for
this parameter is -1 (disabled).
-
#setNumTestsPerEvictionRundetermines the number of objects examined in each run of the idle object
evictor. This setting has no effect unless
timeBetweenEvictionRunsMillis > 0. The default setting for
this parameter is 3.
The pool can be configured to behave as a LIFO queue with respect to idle
objects - always returning the most recently used object from the pool,
or as a FIFO queue, where borrowObject always returns the oldest object
in the idle object pool.
-
#setLifodetermines whether or not the pool returns idle objects in
last-in-first-out order. The default setting for this parameter is
true.
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 before the pool is used.
Implementation note: To prevent possible deadlocks, care has been taken to
ensure that no call to a factory method will occur within a synchronization
block. See POOL-125 and DBCP-44 for more information.
