|
||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.apache.commons.pool.BaseKeyedObjectPool
org.apache.commons.pool.impl.GenericKeyedObjectPool
public class GenericKeyedObjectPool
A configurable KeyedObjectPool
implementation.
When coupled with the appropriate KeyedPoolableObjectFactory
,
GenericKeyedObjectPool
provides robust pooling functionality for
keyed objects. A GenericKeyedObjectPool
can be viewed as a map
of pools, keyed on the (unique) key values provided to the
preparePool
, addObject
or
borrowObject
methods. Each time a new key value is
provided to one of these methods, a new pool is created under the given key
to be managed by the containing GenericKeyedObjectPool.
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 per key.
When maxActive
is exceeded, the keyed pool is said
to be exhausted. The default setting for this parameter is 8.
maxTotal
sets a global limit on the number of objects
that can be in circulation (active or idle) within the combined set of
pools. When non-positive, there is no limit to the total number of
objects in circulation. When maxTotal
is exceeded,
all keyed pools are exhausted. When maxTotal
is set to a
positive value and borrowObject
is invoked
when at the limit with no idle instances available, an attempt is made to
create room by clearing the oldest 15% of the elements from the keyed
pools. The default setting for this parameter is -1 (no limit).
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 per key. The
default setting for this parameter is 8.
whenExhaustedAction
specifies the
behavior of the borrowObject
method when a keyed
pool is exhausted:
whenExhaustedAction
is
WHEN_EXHAUSTED_FAIL
, borrowObject
will throw
a NoSuchElementException
whenExhaustedAction
is
WHEN_EXHAUSTED_GROW
, borrowObject
will create a new
object and return it (essentially making maxActive
meaningless.)
whenExhaustedAction
is WHEN_EXHAUSTED_BLOCK
, borrowObject
will block
(invoke wait
until a new or idle object is available.
If a positive maxWait
value is supplied, the borrowObject
will block for at
most that many milliseconds, after which a NoSuchElementException
will be thrown. If maxWait
is non-positive,
the borrowObject
method will block indefinitely.
whenExhaustedAction
setting is
WHEN_EXHAUSTED_BLOCK
.
testOnBorrow
is set, the pool will
attempt to validate each object before it is returned from the
borrowObject
method. (Using the provided factory's
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.
testOnReturn
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
validateObject
method.) 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 is maintained for each key. 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:
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., by default, idle object
eviction is disabled).
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 unless
timeBetweenEvictionRunsMillis > 0.
The default setting
for this parameter is 30 minutes.
testWhileIdle
indicates whether or not idle
objects should be validated using the factory's
validateObject
method
during idle object eviction runs. 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.
minIdle
sets a target value for the minimum number of
idle objects (per key) that should always be available. If this parameter
is set to a positive number and
timeBetweenEvictionRunsMillis > 0,
each time the idle object
eviction thread runs, it will try to create enough idle instances so that
there will be minIdle
idle instances available under each
key. This parameter is also used by preparePool
if true
is provided as that method's
populateImmediately
parameter. The default setting for this
parameter is 0.
The pools can be configured to behave as LIFO queues with respect to idle objects - always returning the most recently used object from the pool, or as FIFO queues, where borrowObject always returns the oldest object in the idle object pool.
Lifo
determines whether or not the pools return idle objects in
last-in-first-out order. The default setting for this parameter is
true.
GenericKeyedObjectPool is not usable without a KeyedPoolableObjectFactory
. A
non-null
factory must be provided either as a constructor argument
or via a call to setFactory
before the pool is used.
GenericObjectPool
Nested Class Summary | |
---|---|
static class |
GenericKeyedObjectPool.Config
A simple "struct" encapsulating the configuration information for a GenericKeyedObjectPool . |
Field Summary | |
---|---|
static boolean |
DEFAULT_LIFO
The default LIFO status. |
static int |
DEFAULT_MAX_ACTIVE
The default cap on the total number of active instances (per key) from the pool. |
static int |
DEFAULT_MAX_IDLE
The default cap on the number of idle instances (per key) in the pool. |
static int |
DEFAULT_MAX_TOTAL
The default cap on the the overall maximum number of objects that can exist at one time. |
static long |
DEFAULT_MAX_WAIT
The default maximum amount of time (in milliseconds) the borrowObject(java.lang.Object) 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 getMinEvictableIdleTimeMillis() . |
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 borrowObject(java.lang.Object)
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 borrowObject(java.lang.Object)
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 borrowObject(java.lang.Object)
method should simply create a new object anyway. |
Constructor Summary | |
---|---|
GenericKeyedObjectPool()
Create a new GenericKeyedObjectPool with no factory. |
|
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. |
|
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,
boolean lifo)
Create a new GenericKeyedObjectPool using the specified values. |
Method Summary | |
---|---|
void |
addObject(java.lang.Object key)
Create an object using the factory ,
passivate it, and then place it in the idle object pool. |
java.lang.Object |
borrowObject(java.lang.Object key)
Obtains an instance from this pool for the specified key . |
void |
clear()
Clears the pool, removing all pooled instances. |
void |
clear(java.lang.Object key)
Clears the specified pool, removing all pooled instances corresponding to the given key . |
void |
clearOldest()
Method clears oldest 15% of objects in pool. |
void |
close()
Close this pool. |
void |
evict()
Perform numTests idle object eviction tests, evicting
examined objects that meet the criteria for eviction. |
boolean |
getLifo()
Whether or not the idle object pools act as LIFO queues. |
int |
getMaxActive()
Returns the cap on the number of active instances per key. |
int |
getMaxIdle()
Returns the cap on the number of "idle" instances per key. |
int |
getMaxTotal()
Returns the overall maximum number of objects (across pools) that can exist at one time. |
long |
getMaxWait()
Returns the maximum amount of time (in milliseconds) the borrowObject(java.lang.Object) 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 eligible for eviction by the idle object evictor (if any). |
int |
getMinIdle()
Returns the minimum number of idle objects to maintain in each of the keyed pools. |
int |
getNumActive()
Returns the total number of instances current borrowed from this pool but not yet returned. |
int |
getNumActive(java.lang.Object key)
Returns the number of instances currently borrowed from but not yet returned to the pool corresponding to the given key . |
int |
getNumIdle()
Returns the total number of instances currently idle in this pool. |
int |
getNumIdle(java.lang.Object key)
Returns the number of instances corresponding to the given key currently idle in this pool. |
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 borrowObject(java.lang.Object)
method. |
boolean |
getTestOnReturn()
When true , objects will be
validated
before being returned to the pool within the
returnObject(java.lang.Object, java.lang.Object) . |
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 borrowObject(java.lang.Object) method
is invoked when the pool is exhausted (the maximum number
of "active" objects has been reached). |
void |
invalidateObject(java.lang.Object key,
java.lang.Object obj)
Invalidates an object from the pool By contract, obj must have been obtained
using borrowObject
or a related method as defined in an implementation
or sub-interface
using a key that is equivalent to the one used to
borrow the Object in the first place. |
void |
preparePool(java.lang.Object key,
boolean populateImmediately)
Registers a key for pool control. |
void |
returnObject(java.lang.Object key,
java.lang.Object obj)
Return an instance to the pool. |
void |
setConfig(GenericKeyedObjectPool.Config conf)
Sets the configuration. |
void |
setFactory(KeyedPoolableObjectFactory factory)
Not supported in this base implementation. |
void |
setLifo(boolean lifo)
Sets the LIFO property of the pools. |
void |
setMaxActive(int maxActive)
Sets the cap on the number of active instances 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 all pools combined. |
void |
setMaxWait(long maxWait)
Sets the maximum amount of time (in milliseconds) the borrowObject(java.lang.Object) 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 eligible for eviction by the idle object evictor (if any). |
void |
setMinIdle(int poolSize)
Sets the minimum number of idle objects to maintain in each of the keyed pools. |
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 borrowObject(java.lang.Object)
method. |
void |
setTestOnReturn(boolean testOnReturn)
When true , objects will be
validated
before being returned to the pool within the
returnObject(java.lang.Object, java.lang.Object) . |
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 borrowObject(java.lang.Object) method
is invoked when the pool is exhausted (the maximum number
of "active" objects has been reached). |
Methods inherited from class java.lang.Object |
---|
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
---|
public static final boolean DEFAULT_LIFO
setLifo(boolean)
,
Constant Field Valuespublic static final int DEFAULT_MAX_ACTIVE
getMaxActive()
,
setMaxActive(int)
,
Constant Field Valuespublic static final int DEFAULT_MAX_IDLE
getMaxIdle()
,
setMaxIdle(int)
,
Constant Field Valuespublic static final int DEFAULT_MAX_TOTAL
getMaxTotal()
,
setMaxTotal(int)
,
Constant Field Valuespublic static final long DEFAULT_MAX_WAIT
borrowObject(java.lang.Object)
method should block before throwing
an exception when the pool is exhausted and the
"when exhausted" action
is
WHEN_EXHAUSTED_BLOCK
.
getMaxWait()
,
setMaxWait(long)
,
Constant Field Valuespublic static final long DEFAULT_MIN_EVICTABLE_IDLE_TIME_MILLIS
getMinEvictableIdleTimeMillis()
.
getMinEvictableIdleTimeMillis()
,
setMinEvictableIdleTimeMillis(long)
,
Constant Field Valuespublic static final int DEFAULT_MIN_IDLE
setMinIdle(int)
,
getMinIdle()
,
Constant Field Valuespublic static final int DEFAULT_NUM_TESTS_PER_EVICTION_RUN
getNumTestsPerEvictionRun()
,
setNumTestsPerEvictionRun(int)
,
getTimeBetweenEvictionRunsMillis()
,
setTimeBetweenEvictionRunsMillis(long)
,
Constant Field Valuespublic static final boolean DEFAULT_TEST_ON_BORROW
getTestOnBorrow()
,
setTestOnBorrow(boolean)
,
Constant Field Valuespublic static final boolean DEFAULT_TEST_ON_RETURN
getTestOnReturn()
,
setTestOnReturn(boolean)
,
Constant Field Valuespublic static final boolean DEFAULT_TEST_WHILE_IDLE
getTestWhileIdle()
,
setTestWhileIdle(boolean)
,
getTimeBetweenEvictionRunsMillis()
,
setTimeBetweenEvictionRunsMillis(long)
,
Constant Field Valuespublic static final long DEFAULT_TIME_BETWEEN_EVICTION_RUNS_MILLIS
getTimeBetweenEvictionRunsMillis()
,
setTimeBetweenEvictionRunsMillis(long)
,
Constant Field Valuespublic static final byte DEFAULT_WHEN_EXHAUSTED_ACTION
WHEN_EXHAUSTED_BLOCK
,
WHEN_EXHAUSTED_FAIL
,
WHEN_EXHAUSTED_GROW
,
setWhenExhaustedAction(byte)
,
Constant Field Valuespublic static final byte WHEN_EXHAUSTED_BLOCK
borrowObject(java.lang.Object)
method should block until a new object is available, or the
maximum wait time
has been reached.
WHEN_EXHAUSTED_FAIL
,
WHEN_EXHAUSTED_GROW
,
setMaxWait(long)
,
getMaxWait()
,
setWhenExhaustedAction(byte)
,
Constant Field Valuespublic static final byte WHEN_EXHAUSTED_FAIL
borrowObject(java.lang.Object)
method should fail, throwing a NoSuchElementException
.
WHEN_EXHAUSTED_BLOCK
,
WHEN_EXHAUSTED_GROW
,
setWhenExhaustedAction(byte)
,
Constant Field Valuespublic static final byte WHEN_EXHAUSTED_GROW
borrowObject(java.lang.Object)
method should simply create a new object anyway.
WHEN_EXHAUSTED_FAIL
,
WHEN_EXHAUSTED_GROW
,
setWhenExhaustedAction(byte)
,
Constant Field ValuesConstructor Detail |
---|
public GenericKeyedObjectPool()
GenericKeyedObjectPool
with no factory.
GenericKeyedObjectPool(KeyedPoolableObjectFactory)
,
setFactory(KeyedPoolableObjectFactory)
public GenericKeyedObjectPool(KeyedPoolableObjectFactory factory)
GenericKeyedObjectPool
using the specified values.
factory
- the KeyedPoolableObjectFactory
to use to create, validate, and destroy objects if not null
public GenericKeyedObjectPool(KeyedPoolableObjectFactory factory, GenericKeyedObjectPool.Config config)
GenericKeyedObjectPool
using the specified values.
factory
- the KeyedPoolableObjectFactory
to use to create, validate, and destroy objects if not null
config
- a non-null
GenericKeyedObjectPool.Config
describing the configurationpublic GenericKeyedObjectPool(KeyedPoolableObjectFactory factory, int maxActive)
GenericKeyedObjectPool
using the specified values.
factory
- the KeyedPoolableObjectFactory
to use to create, validate, and destroy objects if not null
maxActive
- the maximum number of objects that can be borrowed from me at one time (see setMaxActive(int)
)public GenericKeyedObjectPool(KeyedPoolableObjectFactory factory, int maxActive, byte whenExhaustedAction, long maxWait)
GenericKeyedObjectPool
using the specified values.
factory
- the KeyedPoolableObjectFactory
to use to create, validate, and destroy objects if not null
maxActive
- the maximum number of objects that can be borrowed from me at one time (see setMaxActive(int)
)whenExhaustedAction
- the action to take when the pool is exhausted (see setWhenExhaustedAction(byte)
)maxWait
- the maximum amount of time to wait for an idle object when the pool is exhausted and whenExhaustedAction
is WHEN_EXHAUSTED_BLOCK
(otherwise ignored) (see setMaxWait(long)
)public GenericKeyedObjectPool(KeyedPoolableObjectFactory factory, int maxActive, byte whenExhaustedAction, long maxWait, boolean testOnBorrow, boolean testOnReturn)
GenericKeyedObjectPool
using the specified values.
factory
- the KeyedPoolableObjectFactory
to use to create, validate, and destroy objects if not null
maxActive
- the maximum number of objects that can be borrowed from me at one time (see setMaxActive(int)
)maxWait
- the maximum amount of time to wait for an idle object when the pool is exhausted and whenExhaustedAction
is WHEN_EXHAUSTED_BLOCK
(otherwise ignored) (see setMaxWait(long)
)whenExhaustedAction
- the action to take when the pool is exhausted (see setWhenExhaustedAction(byte)
)testOnBorrow
- whether or not to validate objects before they are returned by the borrowObject(java.lang.Object)
method (see setTestOnBorrow(boolean)
)testOnReturn
- whether or not to validate objects after they are returned to the returnObject(java.lang.Object, java.lang.Object)
method (see setTestOnReturn(boolean)
)public GenericKeyedObjectPool(KeyedPoolableObjectFactory factory, int maxActive, byte whenExhaustedAction, long maxWait, int maxIdle)
GenericKeyedObjectPool
using the specified values.
factory
- the KeyedPoolableObjectFactory
to use to create, validate, and destroy objects if not null
maxActive
- the maximum number of objects that can be borrowed from me at one time (see setMaxActive(int)
)whenExhaustedAction
- the action to take when the pool is exhausted (see setWhenExhaustedAction(byte)
)maxWait
- the maximum amount of time to wait for an idle object when the pool is exhausted and whenExhaustedAction
is WHEN_EXHAUSTED_BLOCK
(otherwise ignored) (see setMaxWait(long)
)maxIdle
- the maximum number of idle objects in my pool (see setMaxIdle(int)
)public GenericKeyedObjectPool(KeyedPoolableObjectFactory factory, int maxActive, byte whenExhaustedAction, long maxWait, int maxIdle, boolean testOnBorrow, boolean testOnReturn)
GenericKeyedObjectPool
using the specified values.
factory
- the KeyedPoolableObjectFactory
to use to create, validate, and destroy objects if not null
maxActive
- the maximum number of objects that can be borrowed from me at one time (see setMaxActive(int)
)whenExhaustedAction
- the action to take when the pool is exhausted (see setWhenExhaustedAction(byte)
)maxWait
- the maximum amount of time to wait for an idle object when the pool is exhausted and whenExhaustedAction
is WHEN_EXHAUSTED_BLOCK
(otherwise ignored) (see getMaxWait()
)maxIdle
- the maximum number of idle objects in my pool (see setMaxIdle(int)
)testOnBorrow
- whether or not to validate objects before they are returned by the borrowObject(java.lang.Object)
method (see setTestOnBorrow(boolean)
)testOnReturn
- whether or not to validate objects after they are returned to the returnObject(java.lang.Object, java.lang.Object)
method (see setTestOnReturn(boolean)
)public GenericKeyedObjectPool(KeyedPoolableObjectFactory factory, int maxActive, byte whenExhaustedAction, long maxWait, int maxIdle, boolean testOnBorrow, boolean testOnReturn, long timeBetweenEvictionRunsMillis, int numTestsPerEvictionRun, long minEvictableIdleTimeMillis, boolean testWhileIdle)
GenericKeyedObjectPool
using the specified values.
factory
- the KeyedPoolableObjectFactory
to use to create, validate, and destroy objects if not null
maxActive
- the maximum number of objects that can be borrowed from me at one time (see setMaxActive(int)
)whenExhaustedAction
- the action to take when the pool is exhausted (see setWhenExhaustedAction(byte)
)maxWait
- the maximum amount of time to wait for an idle object when the pool is exhausted and whenExhaustedAction
is WHEN_EXHAUSTED_BLOCK
(otherwise ignored) (see setMaxWait(long)
)maxIdle
- the maximum number of idle objects in my pool (see setMaxIdle(int)
)testOnBorrow
- whether or not to validate objects before they are returned by the borrowObject(java.lang.Object)
method (see setTestOnBorrow(boolean)
)testOnReturn
- whether or not to validate objects after they are returned to the returnObject(java.lang.Object, java.lang.Object)
method (see setTestOnReturn(boolean)
)timeBetweenEvictionRunsMillis
- the amount of time (in milliseconds) to sleep between examining idle objects for eviction (see setTimeBetweenEvictionRunsMillis(long)
)numTestsPerEvictionRun
- the number of idle objects to examine per run within the idle object eviction thread (if any) (see setNumTestsPerEvictionRun(int)
)minEvictableIdleTimeMillis
- the minimum number of milliseconds an object can sit idle in the pool before it is eligible for eviction (see setMinEvictableIdleTimeMillis(long)
)testWhileIdle
- whether or not to validate objects in the idle object eviction thread, if any (see setTestWhileIdle(boolean)
)public 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)
GenericKeyedObjectPool
using the specified values.
factory
- the KeyedPoolableObjectFactory
to use to create, validate, and destroy objects if not null
maxActive
- the maximum number of objects that can be borrowed from me at one time (see setMaxActive(int)
)whenExhaustedAction
- the action to take when the pool is exhausted (see setWhenExhaustedAction(byte)
)maxWait
- the maximum amount of time to wait for an idle object when the pool is exhausted and whenExhaustedAction
is WHEN_EXHAUSTED_BLOCK
(otherwise ignored) (see setMaxWait(long)
)maxIdle
- the maximum number of idle objects in my pool (see setMaxIdle(int)
)maxTotal
- the maximum number of objects that can exists at one time (see setMaxTotal(int)
)testOnBorrow
- whether or not to validate objects before they are returned by the borrowObject(java.lang.Object)
method (see setTestOnBorrow(boolean)
)testOnReturn
- whether or not to validate objects after they are returned to the returnObject(java.lang.Object, java.lang.Object)
method (see setTestOnReturn(boolean)
)timeBetweenEvictionRunsMillis
- the amount of time (in milliseconds) to sleep between examining idle objects for eviction (see setTimeBetweenEvictionRunsMillis(long)
)numTestsPerEvictionRun
- the number of idle objects to examine per run within the idle object eviction thread (if any) (see setNumTestsPerEvictionRun(int)
)minEvictableIdleTimeMillis
- the minimum number of milliseconds an object can sit idle in the pool before it is eligible for eviction (see setMinEvictableIdleTimeMillis(long)
)testWhileIdle
- whether or not to validate objects in the idle object eviction thread, if any (see setTestWhileIdle(boolean)
)public 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)
GenericKeyedObjectPool
using the specified values.
factory
- the KeyedPoolableObjectFactory
to use to create, validate, and destroy objects if not null
maxActive
- the maximum number of objects that can be borrowed from me at one time (see setMaxActive(int)
)whenExhaustedAction
- the action to take when the pool is exhausted (see setWhenExhaustedAction(byte)
)maxWait
- the maximum amount of time to wait for an idle object when the pool is exhausted and whenExhaustedAction
is WHEN_EXHAUSTED_BLOCK
(otherwise ignored) (see setMaxWait(long)
)maxIdle
- the maximum number of idle objects in my pool (see setMaxIdle(int)
)maxTotal
- the maximum number of objects that can exists at one time (see setMaxTotal(int)
)minIdle
- the minimum number of idle objects to have in the pool at any one time (see setMinIdle(int)
)testOnBorrow
- whether or not to validate objects before they are returned by the borrowObject(java.lang.Object)
method (see setTestOnBorrow(boolean)
)testOnReturn
- whether or not to validate objects after they are returned to the returnObject(java.lang.Object, java.lang.Object)
method (see setTestOnReturn(boolean)
)timeBetweenEvictionRunsMillis
- the amount of time (in milliseconds) to sleep between examining idle objects for eviction (see setTimeBetweenEvictionRunsMillis(long)
)numTestsPerEvictionRun
- the number of idle objects to examine per run within the idle object eviction thread (if any) (see setNumTestsPerEvictionRun(int)
)minEvictableIdleTimeMillis
- the minimum number of milliseconds an object can sit idle in the pool before it is eligible for eviction (see setMinEvictableIdleTimeMillis(long)
)testWhileIdle
- whether or not to validate objects in the idle object eviction thread, if any (see setTestWhileIdle(boolean)
)public 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, boolean lifo)
GenericKeyedObjectPool
using the specified values.
factory
- the KeyedPoolableObjectFactory
to use to create, validate, and destroy objects if not null
maxActive
- the maximum number of objects that can be borrowed from me at one time (see setMaxActive(int)
)whenExhaustedAction
- the action to take when the pool is exhausted (see setWhenExhaustedAction(byte)
)maxWait
- the maximum amount of time to wait for an idle object when the pool is exhausted and whenExhaustedAction
is WHEN_EXHAUSTED_BLOCK
(otherwise ignored) (see setMaxWait(long)
)maxIdle
- the maximum number of idle objects in my pool (see setMaxIdle(int)
)maxTotal
- the maximum number of objects that can exists at one time (see setMaxTotal(int)
)minIdle
- the minimum number of idle objects to have in the pool at any one time (see setMinIdle(int)
)testOnBorrow
- whether or not to validate objects before they are returned by the borrowObject(java.lang.Object)
method (see setTestOnBorrow(boolean)
)testOnReturn
- whether or not to validate objects after they are returned to the returnObject(java.lang.Object, java.lang.Object)
method (see setTestOnReturn(boolean)
)timeBetweenEvictionRunsMillis
- the amount of time (in milliseconds) to sleep between examining idle objects for eviction (see setTimeBetweenEvictionRunsMillis(long)
)numTestsPerEvictionRun
- the number of idle objects to examine per run within the idle object eviction thread (if any) (see setNumTestsPerEvictionRun(int)
)minEvictableIdleTimeMillis
- the minimum number of milliseconds an object can sit idle in the pool before it is eligible for eviction (see setMinEvictableIdleTimeMillis(long)
)testWhileIdle
- whether or not to validate objects in the idle object eviction thread, if any (see setTestWhileIdle(boolean)
)lifo
- whether or not the pools behave as LIFO (last in first out) queues (see setLifo(boolean)
)Method Detail |
---|
public void addObject(java.lang.Object key) throws java.lang.Exception
factory
,
passivate it, and then place it in the idle object pool.
addObject
is useful for "pre-loading" a pool with idle objects.
addObject
in interface KeyedObjectPool
addObject
in class BaseKeyedObjectPool
key
- the key a new instance should be added to
java.lang.Exception
- when KeyedPoolableObjectFactory.makeObject(java.lang.Object)
fails.
java.lang.IllegalStateException
- when no factory
has been set or after close()
has been called on this pool.public java.lang.Object borrowObject(java.lang.Object key) throws java.lang.Exception
KeyedObjectPool
key
.
Instances returned from this method will have been either newly created with
makeObject
or will be a previously idle object and
have been activated with activateObject
and
then validated with validateObject
.
By contract, clients must return the borrowed object using
returnObject
, invalidateObject
, or a related method
as defined in an implementation or sub-interface,
using a key
that is equivalent
to the one used to
borrow the instance in the first place.
The behaviour of this method when the pool has been exhausted
is not strictly specified (although it may be specified by implementations).
Older versions of this method would return null
to indicate exhaustion,
newer versions are encouraged to throw a NoSuchElementException
.
borrowObject
in interface KeyedObjectPool
borrowObject
in class BaseKeyedObjectPool
key
- the key used to obtain the object
java.lang.IllegalStateException
- after close
has been called on this pool
java.lang.Exception
- when makeObject
throws an exception
java.util.NoSuchElementException
- when the pool is exhausted and cannot or will not return another instancepublic void clear()
clear
in interface KeyedObjectPool
clear
in class BaseKeyedObjectPool
public void clear(java.lang.Object key)
key
.
clear
in interface KeyedObjectPool
clear
in class BaseKeyedObjectPool
key
- the key to clearpublic void clearOldest()
public void close() throws java.lang.Exception
BaseKeyedObjectPool
isClosed
and assertOpen
.
close
in interface KeyedObjectPool
close
in class BaseKeyedObjectPool
java.lang.Exception
- deprecated: implementations should silently fail if not all resources can be freed.public void evict() throws java.lang.Exception
Perform numTests
idle object eviction tests, evicting
examined objects that meet the criteria for eviction. If
testWhileIdle
is true, examined objects are validated
when visited (and removed if invalid); otherwise only objects that
have been idle for more than minEvicableIdletimeMillis
are removed.
Successive activations of this method examine objects in keyed pools in sequence, cycling through the keys and examining objects in oldest-to-youngest order within the keyed pools.
java.lang.Exception
- when there is a problem evicting idle objects.public boolean getLifo()
true
if the pools are configured to act as LIFO queuespublic int getMaxActive()
setMaxActive(int)
public int getMaxIdle()
setMaxIdle(int)
public int getMaxTotal()
setMaxTotal(int)
public long getMaxWait()
borrowObject(java.lang.Object)
method should block before throwing
an exception when the pool is exhausted and the
"when exhausted" action
is
WHEN_EXHAUSTED_BLOCK
.
When less than or equal to 0, the borrowObject(java.lang.Object)
method
may block indefinitely.
setMaxWait(long)
,
setWhenExhaustedAction(byte)
,
WHEN_EXHAUSTED_BLOCK
public long getMinEvictableIdleTimeMillis()
setMinEvictableIdleTimeMillis(long)
,
setTimeBetweenEvictionRunsMillis(long)
public int getMinIdle()
timeBetweenEvictionRunsMillis > 0
and attempts to ensure
that each pool has the required minimum number of instances are only
made during idle object eviction runs.
setTimeBetweenEvictionRunsMillis(long)
public int getNumActive()
getNumActive
in interface KeyedObjectPool
getNumActive
in class BaseKeyedObjectPool
public int getNumActive(java.lang.Object key)
key
.
getNumActive
in interface KeyedObjectPool
getNumActive
in class BaseKeyedObjectPool
key
- the key to query
key
currently borrowed in this poolpublic int getNumIdle()
getNumIdle
in interface KeyedObjectPool
getNumIdle
in class BaseKeyedObjectPool
public int getNumIdle(java.lang.Object key)
key
currently idle in this pool.
getNumIdle
in interface KeyedObjectPool
getNumIdle
in class BaseKeyedObjectPool
key
- the key to query
key
currently idle in this poolpublic int getNumTestsPerEvictionRun()
setNumTestsPerEvictionRun(int)
,
setTimeBetweenEvictionRunsMillis(long)
public boolean getTestOnBorrow()
true
, objects will be
validated
before being returned by the borrowObject(java.lang.Object)
method. If the object fails to validate,
it will be dropped from the pool, and we will attempt
to borrow another.
true
if objects are validated before being borrowed.setTestOnBorrow(boolean)
public boolean getTestOnReturn()
true
, objects will be
validated
before being returned to the pool within the
returnObject(java.lang.Object, java.lang.Object)
.
true
when objects will be validated before being returned.setTestOnReturn(boolean)
public boolean getTestWhileIdle()
true
, objects will be
validated
by the idle object evictor (if any). If an object
fails to validate, it will be dropped from the pool.
true
when objects are validated when borrowed.setTestWhileIdle(boolean)
,
setTimeBetweenEvictionRunsMillis(long)
public long getTimeBetweenEvictionRunsMillis()
setTimeBetweenEvictionRunsMillis(long)
public byte getWhenExhaustedAction()
borrowObject(java.lang.Object)
method
is invoked when the pool is exhausted (the maximum number
of "active" objects has been reached).
WHEN_EXHAUSTED_BLOCK
,
WHEN_EXHAUSTED_FAIL
or WHEN_EXHAUSTED_GROW
setWhenExhaustedAction(byte)
public void invalidateObject(java.lang.Object key, java.lang.Object obj) throws java.lang.Exception
KeyedObjectPool
obj
must have been obtained
using borrowObject
or a related method as defined in an implementation
or sub-interface
using a key
that is equivalent to the one used to
borrow the Object
in the first place.
This method should be used when an object that has been borrowed is determined (due to an exception or other problem) to be invalid.
invalidateObject
in interface KeyedObjectPool
invalidateObject
in class BaseKeyedObjectPool
key
- the key used to obtain the objectobj
- a borrowed
instance to be returned.
java.lang.Exception
- deprecated: as of Pool 2.0 pool implementations should swallow
exceptions that occur when a poolable object is returned. For future source compatability
implementations of this method should not even declare that they throw any exception.public void preparePool(java.lang.Object key, boolean populateImmediately)
populateImmediately
is true
and
minIdle > 0,
the pool under the given key will be
populated immediately with minIdle
idle instances.
key
- - The key to register for pool control.populateImmediately
- - If this is true
, the pool
will be populated immediately.public void returnObject(java.lang.Object key, java.lang.Object obj) throws java.lang.Exception
KeyedObjectPool
obj
must have been obtained
using borrowObject
or a related method as defined in an implementation
or sub-interface
using a key
that is equivalent to the one used to
borrow the instance in the first place.
returnObject
in interface KeyedObjectPool
returnObject
in class BaseKeyedObjectPool
key
- the key used to obtain the objectobj
- a borrowed
instance to be returned.
java.lang.Exception
- deprecated: as of Pool 2.0 pool implementations should swallow
exceptions that occur when a poolable object is returned. For future source compatability
implementations of this method should not even declare that they throw any exception.public void setConfig(GenericKeyedObjectPool.Config conf)
conf
- the new configuration to use.GenericKeyedObjectPool.Config
public void setFactory(KeyedPoolableObjectFactory factory) throws java.lang.IllegalStateException
BaseKeyedObjectPool
UnsupportedOperationException
,
subclasses should override this behavior.
setFactory
in interface KeyedObjectPool
setFactory
in class BaseKeyedObjectPool
factory
- the KeyedPoolableObjectFactory
used to create new instances.
java.lang.IllegalStateException
- when the factory cannot be set at this timepublic void setLifo(boolean lifo)
lifo
- the new value for the lifo propertypublic void setMaxActive(int maxActive)
maxActive
- The cap on the number of active instances per key.
Use a negative value for no limit.getMaxActive()
public void setMaxIdle(int maxIdle)
maxIdle
- the maximum number of "idle" instances that can be held
in a given keyed pool. Use a negative value for no limit.getMaxIdle()
,
DEFAULT_MAX_IDLE
public void setMaxTotal(int maxTotal)
maxTotal
is set to a
positive value and borrowObject
is invoked
when at the limit with no idle instances available, an attempt is made to
create room by clearing the oldest 15% of the elements from the keyed
pools.
maxTotal
- The cap on the total number of instances across pools.
Use a negative value for no limit.getMaxTotal()
public void setMaxWait(long maxWait)
borrowObject(java.lang.Object)
method should block before throwing
an exception when the pool is exhausted and the
"when exhausted" action
is
WHEN_EXHAUSTED_BLOCK
.
When less than or equal to 0, the borrowObject(java.lang.Object)
method
may block indefinitely.
maxWait
- the maximum number of milliseconds borrowObject will block or negative for indefinitely.getMaxWait()
,
setWhenExhaustedAction(byte)
,
WHEN_EXHAUSTED_BLOCK
public void setMinEvictableIdleTimeMillis(long minEvictableIdleTimeMillis)
minEvictableIdleTimeMillis
- minimum amount of time an object may sit idle in the pool before it is eligible for eviction.getMinEvictableIdleTimeMillis()
,
setTimeBetweenEvictionRunsMillis(long)
public void setMinIdle(int poolSize)
timeBetweenEvictionRunsMillis > 0
and attempts to ensure
that each pool has the required minimum number of instances are only
made during idle object eviction runs.
poolSize
- - The minimum size of the each keyed poolgetMinIdle()
,
setTimeBetweenEvictionRunsMillis(long)
public void setNumTestsPerEvictionRun(int numTestsPerEvictionRun)
When a negative value is supplied, ceil(
tests will be run. I.e., when the value is getNumIdle()
)/abs(getNumTestsPerEvictionRun()
)-n
, roughly one n
th of the
idle objects will be tested per run.
numTestsPerEvictionRun
- number of objects to examine each eviction run.getNumTestsPerEvictionRun()
,
setTimeBetweenEvictionRunsMillis(long)
public void setTestOnBorrow(boolean testOnBorrow)
true
, objects will be
validated
before being returned by the borrowObject(java.lang.Object)
method. If the object fails to validate,
it will be dropped from the pool, and we will attempt
to borrow another.
testOnBorrow
- whether object should be validated before being returned by borrowObject.getTestOnBorrow()
public void setTestOnReturn(boolean testOnReturn)
true
, objects will be
validated
before being returned to the pool within the
returnObject(java.lang.Object, java.lang.Object)
.
testOnReturn
- true
so objects will be validated before being returned.getTestOnReturn()
public void setTestWhileIdle(boolean testWhileIdle)
true
, objects will be
validated
by the idle object evictor (if any). If an object
fails to validate, it will be dropped from the pool.
testWhileIdle
- true
so objects are validated when borrowed.getTestWhileIdle()
,
setTimeBetweenEvictionRunsMillis(long)
public void setTimeBetweenEvictionRunsMillis(long timeBetweenEvictionRunsMillis)
timeBetweenEvictionRunsMillis
- milliseconds to sleep between evictor runs.getTimeBetweenEvictionRunsMillis()
public void setWhenExhaustedAction(byte whenExhaustedAction)
borrowObject(java.lang.Object)
method
is invoked when the pool is exhausted (the maximum number
of "active" objects has been reached).
whenExhaustedAction
- the action code, which must be one of
WHEN_EXHAUSTED_BLOCK
, WHEN_EXHAUSTED_FAIL
,
or WHEN_EXHAUSTED_GROW
getWhenExhaustedAction()
|
||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |