Class GenericObjectPool<T>
- java.lang.Object
-
- org.apache.commons.pool.BaseObjectPool<T>
-
- org.apache.commons.pool.impl.GenericObjectPool<T>
-
- Type Parameters:
T
- the type of objects held in this pool
- All Implemented Interfaces:
ObjectPool<T>
public class GenericObjectPool<T> extends BaseObjectPool<T> implements ObjectPool<T>
A configurableObjectPool
implementation.When coupled with the appropriate
PoolableObjectFactory
, GenericObjectPool provides robust pooling functionality for arbitrary objects.A GenericObjectPool provides a number of configurable parameters:
-
maxActive
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. WhenmaxActive
is reached, the pool is said to be exhausted. The default setting for this parameter is 8. -
maxIdle
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. -
whenExhaustedAction
specifies the behavior of theborrowObject()
method when the pool is exhausted:-
When
whenExhaustedAction
isWHEN_EXHAUSTED_FAIL
,borrowObject()
will throw aNoSuchElementException
-
When
whenExhaustedAction
isWHEN_EXHAUSTED_GROW
,borrowObject()
will create a new object and return it (essentially makingmaxActive
meaningless.) -
When
whenExhaustedAction
isWHEN_EXHAUSTED_BLOCK
,borrowObject()
will block (invokeObject.wait()
) until a new or idle object is available. If a positivemaxWait
value is supplied, thenborrowObject()
will block for at most that many milliseconds, after which aNoSuchElementException
will be thrown. IfmaxWait
is non-positive, theborrowObject()
method will block indefinitely.
whenExhaustedAction
setting isWHEN_EXHAUSTED_BLOCK
and the defaultmaxWait
setting is -1. By default, therefore,borrowObject
will block indefinitely until an idle instance becomes available. -
When
-
When
testOnBorrow
is set, the pool will attempt to validate each object before it is returned from theborrowObject()
method. (Using the provided factory'sPoolableObjectFactory.validateObject(T)
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 isfalse.
-
When
testOnReturn
is set, the pool will attempt to validate each object before it is returned to the pool in thereturnObject(T)
method. (Using the provided factory'sPoolableObjectFactory.validateObject(T)
method.) Objects that fail to validate will be dropped from the pool. The default setting for this parameter isfalse.
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 contend with client threads for access to objects in the pool, so if they run too frequently performance issues may result. 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. The default setting for this parameter is -1 (i.e., idle object eviction is disabled by default). -
minEvictableIdleTimeMillis
specifies 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 unlesstimeBetweenEvictionRunsMillis > 0.
The default setting for this parameter is 30 minutes. -
testWhileIdle
indicates whether or not idle objects should be validated using the factory'sPoolableObjectFactory.validateObject(T)
method. Objects that fail to validate will be dropped from the pool. This setting has no effect unlesstimeBetweenEvictionRunsMillis > 0.
The default setting for this parameter isfalse.
-
softMinEvictableIdleTimeMillis
specifies 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 unlesstimeBetweenEvictionRunsMillis > 0.
and it is superceded byminEvictableIdleTimeMillis
(that is, ifminEvictableIdleTimeMillis
is positive, thensoftMinEvictableIdleTimeMillis
is ignored). The default setting for this parameter is -1 (disabled). -
numTestsPerEvictionRun
determines the number of objects examined in each run of the idle object evictor. This setting has no effect unlesstimeBetweenEvictionRunsMillis > 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.
-
lifo
determines whether or not the pool returns idle objects in last-in-first-out order. The default setting for this parameter istrue.
GenericObjectPool is not usable without a
PoolableObjectFactory
. A non-null
factory must be provided either as a constructor argument or via a call tosetFactory(org.apache.commons.pool.PoolableObjectFactory<T>)
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.
- Since:
- Pool 1.0
- Version:
- $Revision: 1222396 $ $Date: 2011-12-22 14:02:25 -0500 (Thu, 22 Dec 2011) $
- See Also:
GenericKeyedObjectPool
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
GenericObjectPool.Config
A simple "struct" encapsulating the configuration information for aGenericObjectPool
.private class
GenericObjectPool.Evictor
The idle object evictorTimerTask
.private static class
GenericObjectPool.Latch<T>
Latch used to control allocation order of objects to threads to ensure fairness.
-
Field Summary
Fields Modifier and Type Field Description private java.util.LinkedList<GenericObjectPool.Latch<T>>
_allocationQueue
Used to track the order in which threads callborrowObject()
so that objects can be allocated in the order in which the threads requested them.private CursorableLinkedList.Cursor
_evictionCursor
Eviction cursor - keeps track of idle object evictor positionprivate GenericObjectPool.Evictor
_evictor
My idle object evictionTimerTask
, if any.private PoolableObjectFactory<T>
_factory
private boolean
_lifo
Whether or not the pool behaves as a LIFO queue (last in first out)private int
_maxActive
The cap on the total number of active instances from the pool.private int
_maxIdle
The cap on the number of idle instances in the pool.private long
_maxWait
The maximum amount of time (in millis) theborrowObject()
method should block before throwing an exception when the pool is exhausted and the"when exhausted" action
isWHEN_EXHAUSTED_BLOCK
.private long
_minEvictableIdleTimeMillis
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).private int
_minIdle
The cap on the minimum number of idle instances in the pool.private int
_numActive
The number of objectsborrowObject()
borrowed from the pool, but not yet returned.private int
_numInternalProcessing
The number of objects subject to some form of internal processing (usually creation or destruction) that should be included in the total number of objects but are neither active nor idle.private int
_numTestsPerEvictionRun
The max number of objects to examine during each run of the idle object evictor thread (if any).private CursorableLinkedList<GenericKeyedObjectPool.ObjectTimestampPair<T>>
_pool
My pool.private long
_softMinEvictableIdleTimeMillis
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" amount of object remain in the pool.private boolean
_testOnBorrow
When true, objects will bevalidated
before being returned by theborrowObject()
method.private boolean
_testOnReturn
When true, objects will bevalidated
before being returned to the pool within thereturnObject(T)
.private boolean
_testWhileIdle
When true, objects will bevalidated
by the idle object evictor (if any).private long
_timeBetweenEvictionRunsMillis
The number of milliseconds to sleep between runs of the idle object evictor thread.private byte
_whenExhaustedAction
The action to take when theborrowObject()
method is invoked when the pool is exhausted (the maximum number of "active" objects has been reached).static boolean
DEFAULT_LIFO
The default LIFO status.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 milliseconds) theborrowObject()
method should block before throwing an exception when the pool is exhausted and the"when exhausted" action
isWHEN_EXHAUSTED_BLOCK
.static long
DEFAULT_MIN_EVICTABLE_IDLE_TIME_MILLIS
The default value forgetMinEvictableIdleTimeMillis()
.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 long
DEFAULT_SOFT_MIN_EVICTABLE_IDLE_TIME_MILLIS
The default value forgetSoftMinEvictableIdleTimeMillis()
.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), theborrowObject()
method should block until a new object is available, or themaximum 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), theborrowObject()
method should fail, throwing aNoSuchElementException
.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), theborrowObject()
method should simply create a new object anyway.
-
Constructor Summary
Constructors Constructor Description GenericObjectPool()
Create a new GenericObjectPool with default properties.GenericObjectPool(PoolableObjectFactory<T> factory)
Create a new GenericObjectPool using the specified factory.GenericObjectPool(PoolableObjectFactory<T> factory, int maxActive)
Create a new GenericObjectPool using the specified values.GenericObjectPool(PoolableObjectFactory<T> factory, int maxActive, byte whenExhaustedAction, long maxWait)
Create a new GenericObjectPool using the specified values.GenericObjectPool(PoolableObjectFactory<T> factory, int maxActive, byte whenExhaustedAction, long maxWait, boolean testOnBorrow, boolean testOnReturn)
Create a new GenericObjectPool using the specified values.GenericObjectPool(PoolableObjectFactory<T> factory, int maxActive, byte whenExhaustedAction, long maxWait, int maxIdle)
Create a new GenericObjectPool using the specified values.GenericObjectPool(PoolableObjectFactory<T> factory, int maxActive, byte whenExhaustedAction, long maxWait, int maxIdle, boolean testOnBorrow, boolean testOnReturn)
Create a new GenericObjectPool using the specified values.GenericObjectPool(PoolableObjectFactory<T> 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(PoolableObjectFactory<T> 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.GenericObjectPool(PoolableObjectFactory<T> factory, int maxActive, byte whenExhaustedAction, long maxWait, int maxIdle, int minIdle, boolean testOnBorrow, boolean testOnReturn, long timeBetweenEvictionRunsMillis, int numTestsPerEvictionRun, long minEvictableIdleTimeMillis, boolean testWhileIdle, long softMinEvictableIdleTimeMillis)
Create a new GenericObjectPool using the specified values.GenericObjectPool(PoolableObjectFactory<T> factory, int maxActive, byte whenExhaustedAction, long maxWait, int maxIdle, int minIdle, boolean testOnBorrow, boolean testOnReturn, long timeBetweenEvictionRunsMillis, int numTestsPerEvictionRun, long minEvictableIdleTimeMillis, boolean testWhileIdle, long softMinEvictableIdleTimeMillis, boolean lifo)
Create a new GenericObjectPool using the specified values.GenericObjectPool(PoolableObjectFactory<T> factory, GenericObjectPool.Config config)
Create a new GenericObjectPool using the specified values.
-
Method Summary
All Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description void
addObject()
Create an object, and place it into the pool.private void
addObjectToPool(T obj, boolean decrementNumActive)
Adds an object to the pool.private void
allocate()
Allocate available instances to latches in the allocation queue.T
borrowObject()
Borrows an object from the pool.private int
calculateDeficit(boolean incrementInternal)
This returns the number of objects to create during the pool sustain cycle.void
clear()
Clears any objects sitting idle in the pool by removing them from the idle instance pool and then invoking the configuredPoolableObjectFactory.destroyObject(Object)
method on each idle instance.void
close()
Closes the pool.(package private) java.lang.String
debugInfo()
Returns pool info includinggetNumActive()
,getNumIdle()
and a list of objects idle in the pool with their idle times.private void
destroy(java.util.Collection<GenericKeyedObjectPool.ObjectTimestampPair<T>> c, PoolableObjectFactory<T> factory)
Private method to destroy all the objects in a collection using the supplied object factory.private void
ensureMinIdle()
Check to see if we are below our minimum number of objects if so enough to bring us back to our minimum.void
evict()
PerformnumTests
idle object eviction tests, evicting examined objects that meet the criteria for eviction.boolean
getLifo()
Whether or not the idle object pool acts as a LIFO queue.int
getMaxActive()
Returns the maximum number of objects that can be allocated by the pool (checked out to clients, or idle awaiting checkout) at a given time.int
getMaxIdle()
Returns the cap on the number of "idle" instances in the pool.long
getMaxWait()
Returns the maximum amount of time (in milliseconds) theborrowObject()
method should block before throwing an exception when the pool is exhausted and the"when exhausted" action
isWHEN_EXHAUSTED_BLOCK
.long
getMinEvictableIdleTimeMillis()
Returns 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).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 this pool.int
getNumIdle()
Return the number of instances currently idle in this pool.private int
getNumTests()
Returns the number of tests to be performed in an Evictor run, based on the current value ofnumTestsPerEvictionRun
and the number of idle instances in the pool.int
getNumTestsPerEvictionRun()
Returns the max number of objects to examine during each run of the idle object evictor thread (if any).long
getSoftMinEvictableIdleTimeMillis()
Returns 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" amount of object remain in the pool.boolean
getTestOnBorrow()
When true, objects will bevalidated
before being returned by theborrowObject()
method.boolean
getTestOnReturn()
When true, objects will bevalidated
before being returned to the pool within thereturnObject(T)
.boolean
getTestWhileIdle()
When true, objects will bevalidated
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 theborrowObject()
method is invoked when the pool is exhausted (the maximum number of "active" objects has been reached).void
invalidateObject(T obj)
Invalidates an object from the pool.void
returnObject(T obj)
Returns an object instance to the pool.void
setConfig(GenericObjectPool.Config conf)
Sets my configuration.void
setFactory(PoolableObjectFactory<T> factory)
Deprecated.to be removed in version 2.0void
setLifo(boolean lifo)
Sets the LIFO property of the pool.void
setMaxActive(int maxActive)
Sets the cap on the number of objects that can be allocated by the pool (checked out to clients, or idle awaiting checkout) at a given time.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) theborrowObject()
method should block before throwing an exception when the pool is exhausted and the"when exhausted" action
isWHEN_EXHAUSTED_BLOCK
.void
setMinEvictableIdleTimeMillis(long minEvictableIdleTimeMillis)
Sets 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).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 max number of objects to examine during each run of the idle object evictor thread (if any).void
setSoftMinEvictableIdleTimeMillis(long softMinEvictableIdleTimeMillis)
Sets 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.void
setTestOnBorrow(boolean testOnBorrow)
When true, objects will bevalidated
before being returned by theborrowObject()
method.void
setTestOnReturn(boolean testOnReturn)
When true, objects will bevalidated
before being returned to the pool within thereturnObject(T)
.void
setTestWhileIdle(boolean testWhileIdle)
When true, objects will bevalidated
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 theborrowObject()
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
-
-
-
-
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), theborrowObject()
method should fail, throwing aNoSuchElementException
.
-
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), theborrowObject()
method should block until a new object is available, or themaximum wait time
has been reached.
-
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), theborrowObject()
method should simply create a new object anyway.
-
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.
-
DEFAULT_LIFO
public static final boolean DEFAULT_LIFO
The default LIFO status. True means that borrowObject returns the most recently used ("last in") idle object in the pool (if there are idle instances available). False means that the pool behaves as a FIFO queue - objects are taken from the idle object pool in the order that they are returned to the pool.- Since:
- 1.4
- See Also:
setLifo(boolean)
, Constant Field Values
-
DEFAULT_MAX_WAIT
public static final long DEFAULT_MAX_WAIT
The default maximum amount of time (in milliseconds) theborrowObject()
method should block before throwing an exception when the pool is exhausted and the"when exhausted" action
isWHEN_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.
-
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_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_MIN_EVICTABLE_IDLE_TIME_MILLIS
public static final long DEFAULT_MIN_EVICTABLE_IDLE_TIME_MILLIS
The default value forgetMinEvictableIdleTimeMillis()
.
-
DEFAULT_SOFT_MIN_EVICTABLE_IDLE_TIME_MILLIS
public static final long DEFAULT_SOFT_MIN_EVICTABLE_IDLE_TIME_MILLIS
The default value forgetSoftMinEvictableIdleTimeMillis()
.
-
_maxIdle
private int _maxIdle
The cap on the number of idle instances in the pool.- See Also:
setMaxIdle(int)
,getMaxIdle()
-
_minIdle
private int _minIdle
The cap on the minimum number of idle instances in the pool.- See Also:
setMinIdle(int)
,getMinIdle()
-
_maxActive
private int _maxActive
The cap on the total number of active instances from the pool.- See Also:
setMaxActive(int)
,getMaxActive()
-
_maxWait
private long _maxWait
The maximum amount of time (in millis) theborrowObject()
method should block before throwing an exception when the pool is exhausted and the"when exhausted" action
isWHEN_EXHAUSTED_BLOCK
. When less than or equal to 0, theborrowObject()
method may block indefinitely.
-
_whenExhaustedAction
private byte _whenExhaustedAction
The action to take when theborrowObject()
method is invoked when the pool is exhausted (the maximum number of "active" objects has been reached).
-
_testOnBorrow
private volatile boolean _testOnBorrow
When true, objects will bevalidated
before being returned by theborrowObject()
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)
,getTestOnBorrow()
-
_testOnReturn
private volatile boolean _testOnReturn
When true, objects will bevalidated
before being returned to the pool within thereturnObject(T)
.- See Also:
getTestOnReturn()
,setTestOnReturn(boolean)
-
_testWhileIdle
private boolean _testWhileIdle
When true, objects will bevalidated
by the idle object evictor (if any). If an object fails to validate, it will be dropped from the pool.
-
_timeBetweenEvictionRunsMillis
private long _timeBetweenEvictionRunsMillis
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.
-
_numTestsPerEvictionRun
private int _numTestsPerEvictionRun
The max 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.
-
_minEvictableIdleTimeMillis
private long _minEvictableIdleTimeMillis
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). When non-positive, no objects will be evicted from the pool due to idle time alone.
-
_softMinEvictableIdleTimeMillis
private long _softMinEvictableIdleTimeMillis
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" amount of object remain in the pool. When non-positive, no objects will be evicted from the pool due to idle time alone.
-
_lifo
private boolean _lifo
Whether or not the pool behaves as a LIFO queue (last in first out)
-
_pool
private CursorableLinkedList<GenericKeyedObjectPool.ObjectTimestampPair<T>> _pool
My pool.
-
_evictionCursor
private CursorableLinkedList.Cursor _evictionCursor
Eviction cursor - keeps track of idle object evictor position
-
_factory
private PoolableObjectFactory<T> _factory
-
_numActive
private int _numActive
The number of objectsborrowObject()
borrowed from the pool, but not yet returned.
-
_evictor
private GenericObjectPool.Evictor _evictor
My idle object evictionTimerTask
, if any.
-
_numInternalProcessing
private int _numInternalProcessing
The number of objects subject to some form of internal processing (usually creation or destruction) that should be included in the total number of objects but are neither active nor idle.
-
_allocationQueue
private final java.util.LinkedList<GenericObjectPool.Latch<T>> _allocationQueue
Used to track the order in which threads callborrowObject()
so that objects can be allocated in the order in which the threads requested them.
-
-
Constructor Detail
-
GenericObjectPool
public GenericObjectPool()
Create a new GenericObjectPool with default properties.
-
GenericObjectPool
public GenericObjectPool(PoolableObjectFactory<T> factory)
Create a new GenericObjectPool using the specified factory.- Parameters:
factory
- the (possibly null)PoolableObjectFactory to use to create, validate and destroy objects
-
GenericObjectPool
public GenericObjectPool(PoolableObjectFactory<T> 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 objectsconfig
- a non-nullGenericObjectPool.Config
describing my configuration
-
GenericObjectPool
public GenericObjectPool(PoolableObjectFactory<T> factory, int maxActive)
Create a new GenericObjectPool using the specified values.- Parameters:
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 (seesetMaxActive(int)
)
-
GenericObjectPool
public GenericObjectPool(PoolableObjectFactory<T> 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 objectsmaxActive
- the maximum number of objects that can be borrowed from me at one time (seesetMaxActive(int)
)whenExhaustedAction
- the action to take when the pool is exhausted (seegetWhenExhaustedAction()
)maxWait
- the maximum amount of time to wait for an idle object when the pool is exhausted an and whenExhaustedAction isWHEN_EXHAUSTED_BLOCK
(otherwise ignored) (seegetMaxWait()
)
-
GenericObjectPool
public GenericObjectPool(PoolableObjectFactory<T> 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 objectsmaxActive
- the maximum number of objects that can be borrowed at one time (seesetMaxActive(int)
)whenExhaustedAction
- the action to take when the pool is exhausted (seegetWhenExhaustedAction()
)maxWait
- the maximum amount of time to wait for an idle object when the pool is exhausted an and whenExhaustedAction isWHEN_EXHAUSTED_BLOCK
(otherwise ignored) (seegetMaxWait()
)testOnBorrow
- whether or not to validate objects before they are returned by theborrowObject()
method (seegetTestOnBorrow()
)testOnReturn
- whether or not to validate objects after they are returned to thereturnObject(T)
method (seegetTestOnReturn()
)
-
GenericObjectPool
public GenericObjectPool(PoolableObjectFactory<T> 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 objectsmaxActive
- the maximum number of objects that can be borrowed at one time (seesetMaxActive(int)
)whenExhaustedAction
- the action to take when the pool is exhausted (seegetWhenExhaustedAction()
)maxWait
- the maximum amount of time to wait for an idle object when the pool is exhausted and whenExhaustedAction isWHEN_EXHAUSTED_BLOCK
(otherwise ignored) (seegetMaxWait()
)maxIdle
- the maximum number of idle objects in my pool (seegetMaxIdle()
)
-
GenericObjectPool
public GenericObjectPool(PoolableObjectFactory<T> 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 objectsmaxActive
- the maximum number of objects that can be borrowed at one time (seesetMaxActive(int)
)whenExhaustedAction
- the action to take when the pool is exhausted (seegetWhenExhaustedAction()
)maxWait
- the maximum amount of time to wait for an idle object when the pool is exhausted and whenExhaustedAction isWHEN_EXHAUSTED_BLOCK
(otherwise ignored) (seegetMaxWait()
)maxIdle
- the maximum number of idle objects in my pool (seegetMaxIdle()
)testOnBorrow
- whether or not to validate objects before they are returned by theborrowObject()
method (seegetTestOnBorrow()
)testOnReturn
- whether or not to validate objects after they are returned to thereturnObject(T)
method (seegetTestOnReturn()
)
-
GenericObjectPool
public GenericObjectPool(PoolableObjectFactory<T> 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 objectsmaxActive
- the maximum number of objects that can be borrowed at one time (seesetMaxActive(int)
)whenExhaustedAction
- the action to take when the pool is exhausted (seesetWhenExhaustedAction(byte)
)maxWait
- the maximum amount of time to wait for an idle object when the pool is exhausted and whenExhaustedAction isWHEN_EXHAUSTED_BLOCK
(otherwise ignored) (seesetMaxWait(long)
)maxIdle
- the maximum number of idle objects in my pool (seesetMaxIdle(int)
)testOnBorrow
- whether or not to validate objects before they are returned by theborrowObject()
method (seesetTestOnBorrow(boolean)
)testOnReturn
- whether or not to validate objects after they are returned to thereturnObject(T)
method (seesetTestOnReturn(boolean)
)timeBetweenEvictionRunsMillis
- the amount of time (in milliseconds) to sleep between examining idle objects for eviction (seesetTimeBetweenEvictionRunsMillis(long)
)numTestsPerEvictionRun
- the number of idle objects to examine per run within the idle object eviction thread (if any) (seesetNumTestsPerEvictionRun(int)
)minEvictableIdleTimeMillis
- the minimum number of milliseconds an object can sit idle in the pool before it is eligible for eviction (seesetMinEvictableIdleTimeMillis(long)
)testWhileIdle
- whether or not to validate objects in the idle object eviction thread, if any (seesetTestWhileIdle(boolean)
)
-
GenericObjectPool
public GenericObjectPool(PoolableObjectFactory<T> 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 objectsmaxActive
- the maximum number of objects that can be borrowed at one time (seesetMaxActive(int)
)whenExhaustedAction
- the action to take when the pool is exhausted (seesetWhenExhaustedAction(byte)
)maxWait
- the maximum amount of time to wait for an idle object when the pool is exhausted and whenExhaustedAction isWHEN_EXHAUSTED_BLOCK
(otherwise ignored) (seesetMaxWait(long)
)maxIdle
- the maximum number of idle objects in my pool (seesetMaxIdle(int)
)minIdle
- the minimum number of idle objects in my pool (seesetMinIdle(int)
)testOnBorrow
- whether or not to validate objects before they are returned by theborrowObject()
method (seesetTestOnBorrow(boolean)
)testOnReturn
- whether or not to validate objects after they are returned to thereturnObject(T)
method (seesetTestOnReturn(boolean)
)timeBetweenEvictionRunsMillis
- the amount of time (in milliseconds) to sleep between examining idle objects for eviction (seesetTimeBetweenEvictionRunsMillis(long)
)numTestsPerEvictionRun
- the number of idle objects to examine per run within the idle object eviction thread (if any) (seesetNumTestsPerEvictionRun(int)
)minEvictableIdleTimeMillis
- the minimum number of milliseconds an object can sit idle in the pool before it is eligible for eviction (seesetMinEvictableIdleTimeMillis(long)
)testWhileIdle
- whether or not to validate objects in the idle object eviction thread, if any (seesetTestWhileIdle(boolean)
)
-
GenericObjectPool
public GenericObjectPool(PoolableObjectFactory<T> factory, int maxActive, byte whenExhaustedAction, long maxWait, int maxIdle, int minIdle, boolean testOnBorrow, boolean testOnReturn, long timeBetweenEvictionRunsMillis, int numTestsPerEvictionRun, long minEvictableIdleTimeMillis, boolean testWhileIdle, long softMinEvictableIdleTimeMillis)
Create a new GenericObjectPool using the specified values.- Parameters:
factory
- the (possibly null)PoolableObjectFactory to use to create, validate and destroy objectsmaxActive
- the maximum number of objects that can be borrowed at one time (seesetMaxActive(int)
)whenExhaustedAction
- the action to take when the pool is exhausted (seesetWhenExhaustedAction(byte)
)maxWait
- the maximum amount of time to wait for an idle object when the pool is exhausted and whenExhaustedAction isWHEN_EXHAUSTED_BLOCK
(otherwise ignored) (seesetMaxWait(long)
)maxIdle
- the maximum number of idle objects in my pool (seesetMaxIdle(int)
)minIdle
- the minimum number of idle objects in my pool (seesetMinIdle(int)
)testOnBorrow
- whether or not to validate objects before they are returned by theborrowObject()
method (seesetTestOnBorrow(boolean)
)testOnReturn
- whether or not to validate objects after they are returned to thereturnObject(T)
method (seesetTestOnReturn(boolean)
)timeBetweenEvictionRunsMillis
- the amount of time (in milliseconds) to sleep between examining idle objects for eviction (seesetTimeBetweenEvictionRunsMillis(long)
)numTestsPerEvictionRun
- the number of idle objects to examine per run within the idle object eviction thread (if any) (seesetNumTestsPerEvictionRun(int)
)minEvictableIdleTimeMillis
- the minimum number of milliseconds an object can sit idle in the pool before it is eligible for eviction (seesetMinEvictableIdleTimeMillis(long)
)testWhileIdle
- whether or not to validate objects in the idle object eviction thread, if any (seesetTestWhileIdle(boolean)
)softMinEvictableIdleTimeMillis
- the minimum number of milliseconds an object can sit idle in the pool before it is eligible for eviction with the extra condition that at least "minIdle" amount of object remain in the pool. (seesetSoftMinEvictableIdleTimeMillis(long)
)- Since:
- Pool 1.3
-
GenericObjectPool
public GenericObjectPool(PoolableObjectFactory<T> factory, int maxActive, byte whenExhaustedAction, long maxWait, int maxIdle, int minIdle, boolean testOnBorrow, boolean testOnReturn, long timeBetweenEvictionRunsMillis, int numTestsPerEvictionRun, long minEvictableIdleTimeMillis, boolean testWhileIdle, long softMinEvictableIdleTimeMillis, boolean lifo)
Create a new GenericObjectPool using the specified values.- Parameters:
factory
- the (possibly null)PoolableObjectFactory to use to create, validate and destroy objectsmaxActive
- the maximum number of objects that can be borrowed at one time (seesetMaxActive(int)
)whenExhaustedAction
- the action to take when the pool is exhausted (seesetWhenExhaustedAction(byte)
)maxWait
- the maximum amount of time to wait for an idle object when the pool is exhausted and whenExhaustedAction isWHEN_EXHAUSTED_BLOCK
(otherwise ignored) (seesetMaxWait(long)
)maxIdle
- the maximum number of idle objects in my pool (seesetMaxIdle(int)
)minIdle
- the minimum number of idle objects in my pool (seesetMinIdle(int)
)testOnBorrow
- whether or not to validate objects before they are returned by theborrowObject()
method (seesetTestOnBorrow(boolean)
)testOnReturn
- whether or not to validate objects after they are returned to thereturnObject(T)
method (seesetTestOnReturn(boolean)
)timeBetweenEvictionRunsMillis
- the amount of time (in milliseconds) to sleep between examining idle objects for eviction (seesetTimeBetweenEvictionRunsMillis(long)
)numTestsPerEvictionRun
- the number of idle objects to examine per run within the idle object eviction thread (if any) (seesetNumTestsPerEvictionRun(int)
)minEvictableIdleTimeMillis
- the minimum number of milliseconds an object can sit idle in the pool before it is eligible for eviction (seesetMinEvictableIdleTimeMillis(long)
)testWhileIdle
- whether or not to validate objects in the idle object eviction thread, if any (seesetTestWhileIdle(boolean)
)softMinEvictableIdleTimeMillis
- the minimum number of milliseconds an object can sit idle in the pool before it is eligible for eviction with the extra condition that at least "minIdle" amount of object remain in the pool. (seesetSoftMinEvictableIdleTimeMillis(long)
)lifo
- whether or not objects are returned in last-in-first-out order from the idle object pool (seesetLifo(boolean)
)- Since:
- Pool 1.4
-
-
Method Detail
-
getMaxActive
public int getMaxActive()
Returns 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.- Returns:
- the cap on the total number of object instances managed by the pool.
- See Also:
setMaxActive(int)
-
setMaxActive
public void setMaxActive(int maxActive)
Sets the cap on the number of objects that can be allocated by the pool (checked out to clients, or idle awaiting checkout) at a given time. Use a negative value for no limit.- Parameters:
maxActive
- The cap on the total number of object instances managed by the pool. Negative values mean that there is no limit to the number of objects allocated by the pool.- See Also:
getMaxActive()
-
getWhenExhaustedAction
public byte getWhenExhaustedAction()
Returns the action to take when theborrowObject()
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
orWHEN_EXHAUSTED_GROW
- See Also:
setWhenExhaustedAction(byte)
-
setWhenExhaustedAction
public void setWhenExhaustedAction(byte whenExhaustedAction)
Sets the action to take when theborrowObject()
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 ofWHEN_EXHAUSTED_BLOCK
,WHEN_EXHAUSTED_FAIL
, orWHEN_EXHAUSTED_GROW
- See Also:
getWhenExhaustedAction()
-
getMaxWait
public long getMaxWait()
Returns the maximum amount of time (in milliseconds) theborrowObject()
method should block before throwing an exception when the pool is exhausted and the"when exhausted" action
isWHEN_EXHAUSTED_BLOCK
. When less than or equal to 0, theborrowObject()
method may block indefinitely.- Returns:
- maximum number of milliseconds to block when borrowing an object.
- See Also:
setMaxWait(long)
,setWhenExhaustedAction(byte)
,WHEN_EXHAUSTED_BLOCK
-
setMaxWait
public void setMaxWait(long maxWait)
Sets the maximum amount of time (in milliseconds) theborrowObject()
method should block before throwing an exception when the pool is exhausted and the"when exhausted" action
isWHEN_EXHAUSTED_BLOCK
. When less than or equal to 0, theborrowObject()
method may block indefinitely.- Parameters:
maxWait
- maximum number of milliseconds to block when borrowing an object.- 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. If maxIdle is set too low on heavily loaded systems it is possible you will see objects being destroyed and almost immediately new objects being created. This is a result of the active threads momentarily returning objects faster than they are requesting them them, causing the number of idle objects to rise above maxIdle. The best value for maxIdle for heavily loaded system will vary but the default is a good starting point.- 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 that no objects are created whennumActive + numIdle >= maxActive.
This setting has no effect if the idle object evictor is disabled (i.e. iftimeBetweenEvictionRunsMillis <= 0
).- Parameters:
minIdle
- The minimum number of objects.- See Also:
getMinIdle()
,getTimeBetweenEvictionRunsMillis()
-
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 bevalidated
before being returned by theborrowObject()
method. If the object fails to validate, it will be dropped from the pool, and we will attempt to borrow another.- Returns:
true
if objects are validated before being borrowed.- See Also:
setTestOnBorrow(boolean)
-
setTestOnBorrow
public void setTestOnBorrow(boolean testOnBorrow)
When true, objects will bevalidated
before being returned by theborrowObject()
method. If the object fails to validate, it will be dropped from the pool, and we will attempt to borrow another.- Parameters:
testOnBorrow
-true
if objects should be validated before being borrowed.- See Also:
getTestOnBorrow()
-
getTestOnReturn
public boolean getTestOnReturn()
When true, objects will bevalidated
before being returned to the pool within thereturnObject(T)
.- Returns:
true
when objects will be validated after returned toreturnObject(T)
.- See Also:
setTestOnReturn(boolean)
-
setTestOnReturn
public void setTestOnReturn(boolean testOnReturn)
When true, objects will bevalidated
before being returned to the pool within thereturnObject(T)
.- Parameters:
testOnReturn
-true
so objects will be validated after returned toreturnObject(T)
.- 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.- Returns:
- number of milliseconds to sleep between evictor runs.
- 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.- Parameters:
timeBetweenEvictionRunsMillis
- number of milliseconds to sleep between evictor runs.- See Also:
getTimeBetweenEvictionRunsMillis()
-
getNumTestsPerEvictionRun
public int getNumTestsPerEvictionRun()
Returns the max number of objects to examine during each run of the idle object evictor thread (if any).- Returns:
- max number of objects to examine during each evictor run.
- See Also:
setNumTestsPerEvictionRun(int)
,setTimeBetweenEvictionRunsMillis(long)
-
setNumTestsPerEvictionRun
public void setNumTestsPerEvictionRun(int numTestsPerEvictionRun)
Sets the max 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. That is, when the value is -n, roughly one nth of the idle objects will be tested per run. When the value is positive, the number of tests actually performed in each run will be the minimum of this value and the number of instances idle in the pool.- Parameters:
numTestsPerEvictionRun
- max number of objects to examine during each evictor 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 eligible for eviction by the idle object evictor (if any).- Returns:
- minimum amount of time an object may sit idle in the pool before it is eligible for eviction.
- 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 eligible 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.- Parameters:
minEvictableIdleTimeMillis
- minimum amount of time an object may sit idle in the pool before it is eligible for eviction.- See Also:
getMinEvictableIdleTimeMillis()
,setTimeBetweenEvictionRunsMillis(long)
-
getSoftMinEvictableIdleTimeMillis
public long getSoftMinEvictableIdleTimeMillis()
Returns 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" amount of object remain in the pool.- Returns:
- minimum amount of time an object may sit idle in the pool before it is eligible for eviction.
- Since:
- Pool 1.3
- See Also:
setSoftMinEvictableIdleTimeMillis(long)
-
setSoftMinEvictableIdleTimeMillis
public void setSoftMinEvictableIdleTimeMillis(long softMinEvictableIdleTimeMillis)
Sets 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.- Parameters:
softMinEvictableIdleTimeMillis
- minimum amount of time an object may sit idle in the pool before it is eligible for eviction.- Since:
- Pool 1.3
- See Also:
getSoftMinEvictableIdleTimeMillis()
-
getTestWhileIdle
public boolean getTestWhileIdle()
When true, objects will bevalidated
by the idle object evictor (if any). If an object fails to validate, it will be dropped from the pool.- Returns:
true
when objects will be validated by the evictor.- See Also:
setTestWhileIdle(boolean)
,setTimeBetweenEvictionRunsMillis(long)
-
setTestWhileIdle
public void setTestWhileIdle(boolean testWhileIdle)
When true, objects will bevalidated
by the idle object evictor (if any). If an object fails to validate, it will be dropped from the pool.- Parameters:
testWhileIdle
-true
so objects will be validated by the evictor.- See Also:
getTestWhileIdle()
,setTimeBetweenEvictionRunsMillis(long)
-
getLifo
public boolean getLifo()
Whether or not the idle object pool acts as a LIFO queue. True means that borrowObject returns the most recently used ("last in") idle object in the pool (if there are idle instances available). False means that the pool behaves as a FIFO queue - objects are taken from the idle object pool in the order that they are returned to the pool.- Returns:
true if the pool is configured to act as a LIFO queue
- Since:
- 1.4
-
setLifo
public void setLifo(boolean lifo)
Sets the LIFO property of the pool. True means that borrowObject returns the most recently used ("last in") idle object in the pool (if there are idle instances available). False means that the pool behaves as a FIFO queue - objects are taken from the idle object pool in the order that they are returned to the pool.- Parameters:
lifo
- the new value for the LIFO property- Since:
- 1.4
-
setConfig
public void setConfig(GenericObjectPool.Config conf)
Sets my configuration.- Parameters:
conf
- configuration to use.- See Also:
GenericObjectPool.Config
-
borrowObject
public T borrowObject() throws java.lang.Exception
Borrows an object from the pool.
If there is an idle instance available in the pool, then either the most-recently returned (if
lifo
== true) or "oldest" (lifo == false) instance sitting idle in the pool will be activated and returned. If activation fails, ortestOnBorrow
is set to true and validation fails, the instance is destroyed and the next available instance is examined. This continues until either a valid instance is returned or there are no more idle instances available.If there are no idle instances available in the pool, behavior depends on the
maxActive
and (if applicable)whenExhaustedAction
andmaxWait
properties. If the number of instances checked out from the pool is less thanmaxActive,
a new instance is created, activated and (if applicable) validated and returned to the caller.If the pool is exhausted (no available idle instances and no capacity to create new ones), this method will either block (
WHEN_EXHAUSTED_BLOCK
), throw aNoSuchElementException
(WHEN_EXHAUSTED_FAIL
), or grow (WHEN_EXHAUSTED_GROW
- ignoring maxActive). The length of time that this method will block whenwhenExhaustedAction == WHEN_EXHAUSTED_BLOCK
is determined by themaxWait
property.When the pool is exhausted, multiple calling threads may be simultaneously blocked waiting for instances to become available. As of pool 1.5, a "fairness" algorithm has been implemented to ensure that threads receive available instances in request arrival order.
- Specified by:
borrowObject
in interfaceObjectPool<T>
- Specified by:
borrowObject
in classBaseObjectPool<T>
- Returns:
- object instance
- Throws:
java.util.NoSuchElementException
- if an instance cannot be returnedjava.lang.Exception
- if an instance cannot be obtained from the pool
-
allocate
private void allocate()
Allocate available instances to latches in the allocation queue. Then set _mayCreate to true for as many additional latches remaining in queue as _maxActive allows. While it is safe for GOP, for consistency with GKOP this method should not be called from inside a sync block.
-
invalidateObject
public void invalidateObject(T obj) throws java.lang.Exception
Invalidates an object from the pool.
By contract,
obj
must have been obtained usingborrowObject
.This method should be used when an object that has been borrowed is determined (due to an exception or other problem) to be invalid.
Activation of this method decrements the active count and attempts to destroy the instance.
- Specified by:
invalidateObject
in interfaceObjectPool<T>
- Specified by:
invalidateObject
in classBaseObjectPool<T>
- Parameters:
obj
- aborrowed
instance to be disposed.- Throws:
java.lang.Exception
- if the configuredPoolableObjectFactory
throws an exception destroying obj
-
clear
public void clear()
Clears any objects sitting idle in the pool by removing them from the idle instance pool and then invoking the configuredPoolableObjectFactory.destroyObject(Object)
method on each idle instance.Implementation notes:
- This method does not destroy or effect in any way instances that are checked out of the pool when it is invoked.
- Invoking this method does not prevent objects being returned to the idle instance pool, even during its execution. It locks the pool only during instance removal. Additional instances may be returned while removed items are being destroyed.
- Exceptions encountered destroying idle instances are swallowed.
- Specified by:
clear
in interfaceObjectPool<T>
- Overrides:
clear
in classBaseObjectPool<T>
-
destroy
private void destroy(java.util.Collection<GenericKeyedObjectPool.ObjectTimestampPair<T>> c, PoolableObjectFactory<T> factory)
Private method to destroy all the objects in a collection using the supplied object factory. Assumes that objects in the collection are instances of ObjectTimestampPair and that the object instances that they wrap were created by the factory.- Parameters:
c
- Collection of objects to destroyfactory
- PoolableConnectionFactory used to destroy the objects
-
getNumActive
public int getNumActive()
Return the number of instances currently borrowed from this pool.- Specified by:
getNumActive
in interfaceObjectPool<T>
- Overrides:
getNumActive
in classBaseObjectPool<T>
- Returns:
- the number of instances currently borrowed from this pool
-
getNumIdle
public int getNumIdle()
Return the number of instances currently idle in this pool.- Specified by:
getNumIdle
in interfaceObjectPool<T>
- Overrides:
getNumIdle
in classBaseObjectPool<T>
- Returns:
- the number of instances currently idle in this pool
-
returnObject
public void returnObject(T obj) throws java.lang.Exception
Returns an object instance to the pool.
If
maxIdle
is set to a positive value and the number of idle instances has reached this value, the returning instance is destroyed.If
testOnReturn
== true, the returning instance is validated before being returned to the idle instance pool. In this case, if validation fails, the instance is destroyed.Note: There is no guard to prevent an object being returned to the pool multiple times. Clients are expected to discard references to returned objects and ensure that an object is not returned to the pool multiple times in sequence (i.e., without being borrowed again between returns). Violating this contract will result in the same object appearing multiple times in the pool and pool counters (numActive, numIdle) returning incorrect values.
- Specified by:
returnObject
in interfaceObjectPool<T>
- Specified by:
returnObject
in classBaseObjectPool<T>
- Parameters:
obj
- instance to return to the pool- Throws:
java.lang.Exception
-
addObjectToPool
private void addObjectToPool(T obj, boolean decrementNumActive) throws java.lang.Exception
Adds an object to the pool.
Validates the object if testOnReturn == true and passivates it before returning it to the pool. if validation or passivation fails, or maxIdle is set and there is no room in the pool, the instance is destroyed.
Calls
allocate()
on successful completion- Parameters:
obj
- instance to add to the pooldecrementNumActive
- whether or not to decrement the active count- Throws:
java.lang.Exception
-
close
public void close() throws java.lang.Exception
Closes the pool. Once the pool is closed,
borrowObject()
will fail with IllegalStateException, butreturnObject(Object)
andinvalidateObject(Object)
will continue to work, with returned objects destroyed on return.Destroys idle instances in the pool by invoking
clear()
.- Specified by:
close
in interfaceObjectPool<T>
- Overrides:
close
in classBaseObjectPool<T>
- Throws:
java.lang.Exception
-
setFactory
@Deprecated public void setFactory(PoolableObjectFactory<T> factory) throws java.lang.IllegalStateException
Deprecated.to be removed in version 2.0Sets thefactory
this pool uses to create new instances. Trying to change thefactory
while there are borrowed objects will throw anIllegalStateException
. If there are instances idle in the pool when this method is invoked, these will be destroyed using the original factory.- Specified by:
setFactory
in interfaceObjectPool<T>
- Overrides:
setFactory
in classBaseObjectPool<T>
- Parameters:
factory
- thePoolableObjectFactory
used to create new instances.- Throws:
java.lang.IllegalStateException
- when the factory cannot be set at this time
-
evict
public void evict() throws java.lang.Exception
Perform
numTests
idle object eviction tests, evicting examined objects that meet the criteria for eviction. IftestWhileIdle
is true, examined objects are validated when visited (and removed if invalid); otherwise only objects that have been idle for more thanminEvicableIdletimeMillis
are removed.Successive activations of this method examine objects in in sequence, cycling through objects in oldest-to-youngest order.
- Throws:
java.lang.Exception
- if the pool is closed or eviction fails.
-
ensureMinIdle
private void ensureMinIdle() throws java.lang.Exception
Check to see if we are below our minimum number of objects if so enough to bring us back to our minimum.- Throws:
java.lang.Exception
- whenaddObject()
fails.
-
calculateDeficit
private int calculateDeficit(boolean incrementInternal)
This returns the number of objects to create during the pool sustain cycle. This will ensure that the minimum number of idle instances is maintained without going past the maxActive value.- Parameters:
incrementInternal
- - Should the count of objects currently under some form of internal processing be incremented?- Returns:
- The number of objects to be created
-
addObject
public void addObject() throws java.lang.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 interfaceObjectPool<T>
- Overrides:
addObject
in classBaseObjectPool<T>
- Throws:
java.lang.Exception
- whenPoolableObjectFactory.makeObject()
fails.java.lang.IllegalStateException
- afterObjectPool.close()
has been called on this pool.java.lang.UnsupportedOperationException
- when this pool cannot add new idle objects.
-
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.- Parameters:
delay
- milliseconds between evictor runs.
-
debugInfo
java.lang.String debugInfo()
Returns pool info includinggetNumActive()
,getNumIdle()
and a list of objects idle in the pool with their idle times.- Returns:
- string containing debug information
-
getNumTests
private int getNumTests()
Returns the number of tests to be performed in an Evictor run, based on the current value ofnumTestsPerEvictionRun
and the number of idle instances in the pool.- Returns:
- the number of tests for the Evictor to run
- See Also:
setNumTestsPerEvictionRun(int)
-
-