T
- Type of element pooled in this pool.
This class is intended to be thread-safe.public abstract class BaseGenericObjectPool<T> extends Object
GenericObjectPool
and GenericKeyedObjectPool
. The primary reason this class exists is
reduce code duplication between the two pool implementations.Modifier and Type | Field and Description |
---|---|
static int |
MEAN_TIMING_STATS_CACHE_SIZE
The size of the caches used to store historical data for some attributes
so that rolling means may be calculated.
|
Constructor and Description |
---|
BaseGenericObjectPool(BaseObjectPoolConfig config,
String jmxNameBase,
String jmxNamePrefix)
Handles JMX registration (if required) and the initialization required for
monitoring.
|
Modifier and Type | Method and Description |
---|---|
abstract void |
close()
Closes the pool, destroys the remaining idle objects and, if registered
in JMX, deregisters it.
|
abstract void |
evict()
Perform
numTests idle object eviction tests, evicting
examined objects that meet the criteria for eviction. |
boolean |
getBlockWhenExhausted()
Returns whether to block when the
borrowObject() method is
invoked when the pool is exhausted (the maximum number of "active"
objects has been reached). |
long |
getBorrowedCount()
The total number of objects successfully borrowed from this pool over the
lifetime of the pool.
|
long |
getCreatedCount()
The total number of objects created for this pool over the lifetime of
the pool.
|
String |
getCreationStackTrace()
Provides the stack trace for the call that created this pool.
|
long |
getDestroyedByBorrowValidationCount()
The total number of objects destroyed by this pool as a result of failing
validation during
borrowObject() over the lifetime of the
pool. |
long |
getDestroyedByEvictorCount()
The total number of objects destroyed by the evictor associated with this
pool over the lifetime of the pool.
|
long |
getDestroyedCount()
The total number of objects destroyed by this pool over the lifetime of
the pool.
|
String |
getEvictionPolicyClassName()
Returns the name of the
EvictionPolicy implementation that is
used by this pool. |
boolean |
getFairness()
Returns whether or not the pool serves threads waiting to borrow objects fairly.
|
ObjectName |
getJmxName()
Provides the name under which the pool has been registered with the
platform MBean server or
null if the pool has not been
registered. |
boolean |
getLifo()
Returns whether the pool has LIFO (last in, first out) behaviour with
respect to idle objects - always returning the most recently used object
from the pool, or as a FIFO (first in, first out) queue, where the pool
always returns the oldest object in the idle object pool.
|
long |
getMaxBorrowWaitTimeMillis()
The maximum time a thread has waited to borrow objects from the pool.
|
int |
getMaxTotal()
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.
|
long |
getMaxWaitMillis()
Returns the maximum amount of time (in milliseconds) the
borrowObject() method should block before throwing an
exception when the pool is exhausted and
getBlockWhenExhausted() is true. |
long |
getMeanActiveTimeMillis()
The mean time objects are active for based on the last
MEAN_TIMING_STATS_CACHE_SIZE objects returned to the pool. |
long |
getMeanBorrowWaitTimeMillis()
The mean time threads wait to borrow an object based on the last
MEAN_TIMING_STATS_CACHE_SIZE objects borrowed from the pool. |
long |
getMeanIdleTimeMillis()
The mean time objects are idle for based on the last
MEAN_TIMING_STATS_CACHE_SIZE objects borrowed from the pool. |
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 -
see
setTimeBetweenEvictionRunsMillis(long) ). |
abstract int |
getNumIdle()
The number of instances currently idle in this pool.
|
int |
getNumTestsPerEvictionRun()
Returns the maximum number of objects to examine during each run (if any)
of the idle object evictor thread.
|
long |
getReturnedCount()
The total number of objects returned to this pool over the lifetime of
the pool.
|
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 -
see
setTimeBetweenEvictionRunsMillis(long) ),
with the extra condition that at least minIdle object
instances remain in the pool. |
SwallowedExceptionListener |
getSwallowedExceptionListener()
The listener used (if any) to receive notifications of exceptions
unavoidably swallowed by the pool.
|
boolean |
getTestOnBorrow()
Returns whether objects borrowed from the pool will be validated before
being returned from the
borrowObject() method. |
boolean |
getTestOnCreate()
Returns whether objects created for the pool will be validated before
being returned from the
borrowObject() method. |
boolean |
getTestOnReturn()
Returns whether objects borrowed from the pool will be validated when
they are returned to the pool via the
returnObject() method. |
boolean |
getTestWhileIdle()
Returns whether objects sitting idle in the pool will be validated by the
idle object evictor (if any - see
setTimeBetweenEvictionRunsMillis(long) ). |
long |
getTimeBetweenEvictionRunsMillis()
Returns the number of milliseconds to sleep between runs of the idle
object evictor thread.
|
boolean |
isClosed()
Has this pool instance been closed.
|
void |
setBlockWhenExhausted(boolean blockWhenExhausted)
Sets whether to block when the
borrowObject() method is
invoked when the pool is exhausted (the maximum number of "active"
objects has been reached). |
void |
setEvictionPolicyClassName(String evictionPolicyClassName)
Sets the name of the
EvictionPolicy implementation that is
used by this pool. |
void |
setLifo(boolean lifo)
Sets whether the pool has LIFO (last in, first out) behaviour with
respect to idle objects - always returning the most recently used object
from the pool, or as a FIFO (first in, first out) queue, where the pool
always returns the oldest object in the idle object pool.
|
void |
setMaxTotal(int maxTotal)
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 |
setMaxWaitMillis(long maxWaitMillis)
Sets the maximum amount of time (in milliseconds) the
borrowObject() method should block before throwing an
exception when the pool is exhausted and
getBlockWhenExhausted() is true. |
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 -
see
setTimeBetweenEvictionRunsMillis(long) ). |
void |
setNumTestsPerEvictionRun(int numTestsPerEvictionRun)
Sets the maximum number of objects to examine during each run (if any)
of the idle object evictor thread.
|
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 -
see
setTimeBetweenEvictionRunsMillis(long) ),
with the extra condition that at least minIdle object
instances remain in the pool. |
void |
setSwallowedExceptionListener(SwallowedExceptionListener swallowedExceptionListener)
The listener used (if any) to receive notifications of exceptions
unavoidably swallowed by the pool.
|
void |
setTestOnBorrow(boolean testOnBorrow)
Sets whether objects borrowed from the pool will be validated before
being returned from the
borrowObject() method. |
void |
setTestOnCreate(boolean testOnCreate)
Sets whether objects created for the pool will be validated before
being returned from the
borrowObject() method. |
void |
setTestOnReturn(boolean testOnReturn)
Sets whether objects borrowed from the pool will be validated when
they are returned to the pool via the
returnObject() method. |
void |
setTestWhileIdle(boolean testWhileIdle)
Returns whether objects sitting idle in the pool will be validated by the
idle object evictor (if any - see
setTimeBetweenEvictionRunsMillis(long) ). |
void |
setTimeBetweenEvictionRunsMillis(long timeBetweenEvictionRunsMillis)
Sets the number of milliseconds to sleep between runs of the idle
object evictor thread.
|
public static final int MEAN_TIMING_STATS_CACHE_SIZE
public BaseGenericObjectPool(BaseObjectPoolConfig config, String jmxNameBase, String jmxNamePrefix)
config
- Pool configurationjmxNameBase
- The default base JMX name for the new pool unless
overridden by the configjmxNamePrefix
- Prefix to be used for JMX name for the new poolpublic final int getMaxTotal()
setMaxTotal(int)
public final void setMaxTotal(int maxTotal)
maxTotal
- 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.getMaxTotal()
public final boolean getBlockWhenExhausted()
borrowObject()
method is
invoked when the pool is exhausted (the maximum number of "active"
objects has been reached).true
if borrowObject()
should block
when the pool is exhaustedsetBlockWhenExhausted(boolean)
public final void setBlockWhenExhausted(boolean blockWhenExhausted)
borrowObject()
method is
invoked when the pool is exhausted (the maximum number of "active"
objects has been reached).blockWhenExhausted
- true
if
borrowObject()
should block
when the pool is exhaustedgetBlockWhenExhausted()
public final long getMaxWaitMillis()
borrowObject()
method should block before throwing an
exception when the pool is exhausted and
getBlockWhenExhausted()
is true. When less than 0, the
borrowObject()
method may block indefinitely.borrowObject()
will block.setMaxWaitMillis(long)
,
setBlockWhenExhausted(boolean)
public final void setMaxWaitMillis(long maxWaitMillis)
borrowObject()
method should block before throwing an
exception when the pool is exhausted and
getBlockWhenExhausted()
is true. When less than 0, the
borrowObject()
method may block indefinitely.maxWaitMillis
- the maximum number of milliseconds
borrowObject()
will block or negative
for indefinitely.getMaxWaitMillis()
,
setBlockWhenExhausted(boolean)
public final boolean getLifo()
true
if the pool is configured with LIFO behaviour
or false
if the pool is configured with FIFO
behavioursetLifo(boolean)
public final boolean getFairness()
true
if waiting threads are to be served
by the pool in arrival orderpublic final void setLifo(boolean lifo)
lifo
- true
if the pool is to be configured with LIFO
behaviour or false
if the pool is to be
configured with FIFO behaviourgetLifo()
public final boolean getTestOnCreate()
borrowObject()
method. Validation is
performed by the validateObject()
method of the factory
associated with the pool. If the object fails to validate, then
borrowObject()
will fail.true
if newly created objects are validated before
being returned from the borrowObject()
methodsetTestOnCreate(boolean)
public final void setTestOnCreate(boolean testOnCreate)
borrowObject()
method. Validation is
performed by the validateObject()
method of the factory
associated with the pool. If the object fails to validate, then
borrowObject()
will fail.testOnCreate
- true
if newly created objects should be
validated before being returned from the
borrowObject()
methodgetTestOnCreate()
public final boolean getTestOnBorrow()
borrowObject()
method. Validation is
performed by the validateObject()
method of the factory
associated with the pool. If the object fails to validate, it will be
removed from the pool and destroyed, and a new attempt will be made to
borrow an object from the pool.true
if objects are validated before being returned
from the borrowObject()
methodsetTestOnBorrow(boolean)
public final void setTestOnBorrow(boolean testOnBorrow)
borrowObject()
method. Validation is
performed by the validateObject()
method of the factory
associated with the pool. If the object fails to validate, it will be
removed from the pool and destroyed, and a new attempt will be made to
borrow an object from the pool.testOnBorrow
- true
if objects should be validated
before being returned from the
borrowObject()
methodgetTestOnBorrow()
public final boolean getTestOnReturn()
returnObject()
method.
Validation is performed by the validateObject()
method of
the factory associated with the pool. Returning objects that fail validation
are destroyed rather then being returned the pool.true
if objects are validated on return to
the pool via the returnObject()
methodsetTestOnReturn(boolean)
public final void setTestOnReturn(boolean testOnReturn)
returnObject()
method.
Validation is performed by the validateObject()
method of
the factory associated with the pool. Returning objects that fail validation
are destroyed rather then being returned the pool.testOnReturn
- true
if objects are validated on
return to the pool via the
returnObject()
methodgetTestOnReturn()
public final boolean getTestWhileIdle()
setTimeBetweenEvictionRunsMillis(long)
). Validation is performed
by the validateObject()
method of the factory associated
with the pool. If the object fails to validate, it will be removed from
the pool and destroyed.true
if objects will be validated by the evictorsetTestWhileIdle(boolean)
,
setTimeBetweenEvictionRunsMillis(long)
public final void setTestWhileIdle(boolean testWhileIdle)
setTimeBetweenEvictionRunsMillis(long)
). Validation is performed
by the validateObject()
method of the factory associated
with the pool. If the object fails to validate, it will be removed from
the pool and destroyed. Note that setting this property has no effect
unless the idle object evictor is enabled by setting
timeBetweenEvictionRunsMillis
to a positive value.testWhileIdle
- true
so objects will be validated by the evictorgetTestWhileIdle()
,
setTimeBetweenEvictionRunsMillis(long)
public final long getTimeBetweenEvictionRunsMillis()
setTimeBetweenEvictionRunsMillis(long)
public final void setTimeBetweenEvictionRunsMillis(long timeBetweenEvictionRunsMillis)
timeBetweenEvictionRunsMillis
- number of milliseconds to sleep between evictor runsgetTimeBetweenEvictionRunsMillis()
public final int getNumTestsPerEvictionRun()
ceil(getNumIdle()
/
abs(getNumTestsPerEvictionRun()
))
which means that when the
value is -n
roughly one nth of the idle objects will be
tested per run.setNumTestsPerEvictionRun(int)
,
setTimeBetweenEvictionRunsMillis(long)
public final void setNumTestsPerEvictionRun(int numTestsPerEvictionRun)
ceil(getNumIdle()
/
abs(getNumTestsPerEvictionRun()
))
which means that when the
value is -n
roughly one nth of the idle objects will be
tested per run.numTestsPerEvictionRun
- max number of objects to examine during each evictor rungetNumTestsPerEvictionRun()
,
setTimeBetweenEvictionRunsMillis(long)
public final long getMinEvictableIdleTimeMillis()
setTimeBetweenEvictionRunsMillis(long)
). When non-positive,
no objects will be evicted from the pool due to idle time alone.setMinEvictableIdleTimeMillis(long)
,
setTimeBetweenEvictionRunsMillis(long)
public final void setMinEvictableIdleTimeMillis(long minEvictableIdleTimeMillis)
setTimeBetweenEvictionRunsMillis(long)
). When non-positive,
no objects will be evicted from the pool due to idle time alone.minEvictableIdleTimeMillis
- minimum amount of time an object may sit idle in the pool
before it is eligible for evictiongetMinEvictableIdleTimeMillis()
,
setTimeBetweenEvictionRunsMillis(long)
public final long getSoftMinEvictableIdleTimeMillis()
setTimeBetweenEvictionRunsMillis(long)
),
with the extra condition that at least minIdle
object
instances remain in the pool. This setting is overridden by
getMinEvictableIdleTimeMillis()
(that is, if
getMinEvictableIdleTimeMillis()
is positive, then
getSoftMinEvictableIdleTimeMillis()
is ignored).setSoftMinEvictableIdleTimeMillis(long)
public final void setSoftMinEvictableIdleTimeMillis(long softMinEvictableIdleTimeMillis)
setTimeBetweenEvictionRunsMillis(long)
),
with the extra condition that at least minIdle
object
instances remain in the pool. This setting is overridden by
getMinEvictableIdleTimeMillis()
(that is, if
getMinEvictableIdleTimeMillis()
is positive, then
getSoftMinEvictableIdleTimeMillis()
is ignored).softMinEvictableIdleTimeMillis
- minimum amount of time an object may sit idle in the pool
before it is eligible for eviction if minIdle instances are
availablegetSoftMinEvictableIdleTimeMillis()
public final String getEvictionPolicyClassName()
EvictionPolicy
implementation that is
used by this pool.EvictionPolicy
setEvictionPolicyClassName(String)
public final void setEvictionPolicyClassName(String evictionPolicyClassName)
EvictionPolicy
implementation that is
used by this pool.evictionPolicyClassName
- the fully qualified class name of the
new eviction policygetEvictionPolicyClassName()
public abstract void close()
public final boolean isClosed()
true
when this pool has been closed.public abstract void evict() throws 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.
Exception
- when there is a problem evicting idle objects.public final ObjectName getJmxName()
null
if the pool has not been
registered.public final String getCreationStackTrace()
close()
method.
This method is provided to assist with identifying code that creates but
does not close it thereby creating a memory leak.public final long getBorrowedCount()
public final long getReturnedCount()
public final long getCreatedCount()
public final long getDestroyedCount()
public final long getDestroyedByEvictorCount()
public final long getDestroyedByBorrowValidationCount()
borrowObject()
over the lifetime of the
pool.public final long getMeanActiveTimeMillis()
MEAN_TIMING_STATS_CACHE_SIZE
objects returned to the pool.public final long getMeanIdleTimeMillis()
MEAN_TIMING_STATS_CACHE_SIZE
objects borrowed from the pool.public final long getMeanBorrowWaitTimeMillis()
MEAN_TIMING_STATS_CACHE_SIZE
objects borrowed from the pool.public final long getMaxBorrowWaitTimeMillis()
public abstract int getNumIdle()
public final SwallowedExceptionListener getSwallowedExceptionListener()
null
for no listenerpublic final void setSwallowedExceptionListener(SwallowedExceptionListener swallowedExceptionListener)
swallowedExceptionListener
- The listener or null
for no listenerCopyright © 2000-2014 Apache Software Foundation. All Rights Reserved.