Package org.apache.commons.pool2.impl
Class BaseGenericObjectPool<T>
- java.lang.Object
-
- org.apache.commons.pool2.impl.BaseGenericObjectPool<T>
-
- Type Parameters:
T
- Type of element pooled in this pool. This class is intended to be thread-safe.
- Direct Known Subclasses:
GenericKeyedObjectPool
,GenericObjectPool
public abstract class BaseGenericObjectPool<T> extends java.lang.Object
Base class that provides common functionality forGenericObjectPool
andGenericKeyedObjectPool
. The primary reason this class exists is reduce code duplication between the two pool implementations.- Since:
- 2.0
- Version:
- $Revision: $
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description (package private) class
BaseGenericObjectPool.EvictionIterator
The idle object eviction iterator.(package private) class
BaseGenericObjectPool.Evictor
The idle object evictorTimerTask
.(package private) static class
BaseGenericObjectPool.IdentityWrapper<T>
Wrapper for objects under management by the pool.private class
BaseGenericObjectPool.StatsStore
Maintains a cache of values for a single metric and reports statistics on the cached values.
-
Field Summary
Fields Modifier and Type Field Description private BaseGenericObjectPool.StatsStore
activeTimes
private boolean
blockWhenExhausted
private java.util.concurrent.atomic.AtomicLong
borrowedCount
(package private) boolean
closed
(package private) java.lang.Object
closeLock
(package private) java.util.concurrent.atomic.AtomicLong
createdCount
private java.lang.String
creationStackTrace
(package private) java.util.concurrent.atomic.AtomicLong
destroyedByBorrowValidationCount
(package private) java.util.concurrent.atomic.AtomicLong
destroyedByEvictorCount
(package private) java.util.concurrent.atomic.AtomicLong
destroyedCount
(package private) BaseGenericObjectPool.EvictionIterator
evictionIterator
(package private) java.lang.Object
evictionLock
private EvictionPolicy<T>
evictionPolicy
private BaseGenericObjectPool.Evictor
evictor
private java.lang.ref.WeakReference<java.lang.ClassLoader>
factoryClassLoader
private boolean
fairness
private BaseGenericObjectPool.StatsStore
idleTimes
private boolean
lifo
private java.util.concurrent.atomic.AtomicLong
maxBorrowWaitTimeMillis
private int
maxTotal
private long
maxWaitMillis
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.private long
minEvictableIdleTimeMillis
private int
numTestsPerEvictionRun
private javax.management.ObjectName
oname
private java.util.concurrent.atomic.AtomicLong
returnedCount
private long
softMinEvictableIdleTimeMillis
private SwallowedExceptionListener
swallowedExceptionListener
private boolean
testOnBorrow
private boolean
testOnCreate
private boolean
testOnReturn
private boolean
testWhileIdle
private long
timeBetweenEvictionRunsMillis
private BaseGenericObjectPool.StatsStore
waitTimes
-
Constructor Summary
Constructors Constructor Description BaseGenericObjectPool(BaseObjectPoolConfig config, java.lang.String jmxNameBase, java.lang.String jmxNamePrefix)
Handles JMX registration (if required) and the initialization required for monitoring.
-
Method Summary
All Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description (package private) void
assertOpen()
Verifies that the pool is open.abstract void
close()
Closes the pool, destroys the remaining idle objects and, if registered in JMX, deregisters it.(package private) abstract void
ensureMinIdle()
Tries to ensure that the configured minimum number of idle instances are available in the pool.abstract void
evict()
PerformnumTests
idle object eviction tests, evicting examined objects that meet the criteria for eviction.boolean
getBlockWhenExhausted()
Returns whether to block when theborrowObject()
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.java.lang.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 duringborrowObject()
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.protected EvictionPolicy<T>
getEvictionPolicy()
Returns theEvictionPolicy
defined for this pool.java.lang.String
getEvictionPolicyClassName()
Returns the name of theEvictionPolicy
implementation that is used by this pool.boolean
getFairness()
Returns whether or not the pool serves threads waiting to borrow objects fairly.javax.management.ObjectName
getJmxName()
Provides the name under which the pool has been registered with the platform MBean server ornull
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) theborrowObject()
method should block before throwing an exception when the pool is exhausted andgetBlockWhenExhausted()
is true.long
getMeanActiveTimeMillis()
The mean time objects are active for based on the lastMEAN_TIMING_STATS_CACHE_SIZE
objects returned to the pool.long
getMeanBorrowWaitTimeMillis()
The mean time threads wait to borrow an object based on the lastMEAN_TIMING_STATS_CACHE_SIZE
objects borrowed from the pool.long
getMeanIdleTimeMillis()
The mean time objects are idle for based on the lastMEAN_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 - seesetTimeBetweenEvictionRunsMillis(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 - seesetTimeBetweenEvictionRunsMillis(long)
), with the extra condition that at leastminIdle
object instances remain in the pool.private java.lang.String
getStackTrace(java.lang.Exception e)
Gets the stack trace of an exception as a string.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 theborrowObject()
method.boolean
getTestOnCreate()
Returns whether objects created for the pool will be validated before being returned from theborrowObject()
method.boolean
getTestOnReturn()
Returns whether objects borrowed from the pool will be validated when they are returned to the pool via thereturnObject()
method.boolean
getTestWhileIdle()
Returns whether objects sitting idle in the pool will be validated by the idle object evictor (if any - seesetTimeBetweenEvictionRunsMillis(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.private javax.management.ObjectName
jmxRegister(BaseObjectPoolConfig config, java.lang.String jmxNameBase, java.lang.String jmxNamePrefix)
Registers the pool with the platform MBean server.(package private) void
jmxUnregister()
Unregisters this pool's MBean.void
setBlockWhenExhausted(boolean blockWhenExhausted)
Sets whether to block when theborrowObject()
method is invoked when the pool is exhausted (the maximum number of "active" objects has been reached).void
setEvictionPolicyClassName(java.lang.String evictionPolicyClassName)
Sets the name of theEvictionPolicy
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) theborrowObject()
method should block before throwing an exception when the pool is exhausted andgetBlockWhenExhausted()
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 - seesetTimeBetweenEvictionRunsMillis(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 - seesetTimeBetweenEvictionRunsMillis(long)
), with the extra condition that at leastminIdle
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 theborrowObject()
method.void
setTestOnCreate(boolean testOnCreate)
Sets whether objects created for the pool will be validated before being returned from theborrowObject()
method.void
setTestOnReturn(boolean testOnReturn)
Sets whether objects borrowed from the pool will be validated when they are returned to the pool via thereturnObject()
method.void
setTestWhileIdle(boolean testWhileIdle)
Returns whether objects sitting idle in the pool will be validated by the idle object evictor (if any - seesetTimeBetweenEvictionRunsMillis(long)
).void
setTimeBetweenEvictionRunsMillis(long timeBetweenEvictionRunsMillis)
Sets the number of milliseconds to sleep between runs of the idle object evictor thread.(package private) void
startEvictor(long delay)
Starts the evictor with the given delay.(package private) void
swallowException(java.lang.Exception e)
Swallows an exception and notifies the configured listener for swallowed exceptions queue.(package private) void
updateStatsBorrow(PooledObject<T> p, long waitTime)
Updates statistics after an object is borrowed from the pool.(package private) void
updateStatsReturn(long activeTime)
Updates statistics after an object is returned to the pool.
-
-
-
Field Detail
-
MEAN_TIMING_STATS_CACHE_SIZE
public static final 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.- See Also:
- Constant Field Values
-
maxTotal
private volatile int maxTotal
-
blockWhenExhausted
private volatile boolean blockWhenExhausted
-
maxWaitMillis
private volatile long maxWaitMillis
-
lifo
private volatile boolean lifo
-
fairness
private final boolean fairness
-
testOnCreate
private volatile boolean testOnCreate
-
testOnBorrow
private volatile boolean testOnBorrow
-
testOnReturn
private volatile boolean testOnReturn
-
testWhileIdle
private volatile boolean testWhileIdle
-
timeBetweenEvictionRunsMillis
private volatile long timeBetweenEvictionRunsMillis
-
numTestsPerEvictionRun
private volatile int numTestsPerEvictionRun
-
minEvictableIdleTimeMillis
private volatile long minEvictableIdleTimeMillis
-
softMinEvictableIdleTimeMillis
private volatile long softMinEvictableIdleTimeMillis
-
evictionPolicy
private volatile EvictionPolicy<T> evictionPolicy
-
closeLock
final java.lang.Object closeLock
-
closed
volatile boolean closed
-
evictionLock
final java.lang.Object evictionLock
-
evictor
private BaseGenericObjectPool.Evictor evictor
-
evictionIterator
BaseGenericObjectPool.EvictionIterator evictionIterator
-
factoryClassLoader
private final java.lang.ref.WeakReference<java.lang.ClassLoader> factoryClassLoader
-
oname
private final javax.management.ObjectName oname
-
creationStackTrace
private final java.lang.String creationStackTrace
-
borrowedCount
private final java.util.concurrent.atomic.AtomicLong borrowedCount
-
returnedCount
private final java.util.concurrent.atomic.AtomicLong returnedCount
-
createdCount
final java.util.concurrent.atomic.AtomicLong createdCount
-
destroyedCount
final java.util.concurrent.atomic.AtomicLong destroyedCount
-
destroyedByEvictorCount
final java.util.concurrent.atomic.AtomicLong destroyedByEvictorCount
-
destroyedByBorrowValidationCount
final java.util.concurrent.atomic.AtomicLong destroyedByBorrowValidationCount
-
activeTimes
private final BaseGenericObjectPool.StatsStore activeTimes
-
idleTimes
private final BaseGenericObjectPool.StatsStore idleTimes
-
waitTimes
private final BaseGenericObjectPool.StatsStore waitTimes
-
maxBorrowWaitTimeMillis
private final java.util.concurrent.atomic.AtomicLong maxBorrowWaitTimeMillis
-
swallowedExceptionListener
private volatile SwallowedExceptionListener swallowedExceptionListener
-
-
Constructor Detail
-
BaseGenericObjectPool
public BaseGenericObjectPool(BaseObjectPoolConfig config, java.lang.String jmxNameBase, java.lang.String jmxNamePrefix)
Handles JMX registration (if required) and the initialization required for monitoring.- Parameters:
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 pool
-
-
Method Detail
-
getMaxTotal
public final 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. When negative, 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:
setMaxTotal(int)
-
setMaxTotal
public final 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. Use a negative value for no limit.- Parameters:
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.- See Also:
getMaxTotal()
-
getBlockWhenExhausted
public final boolean getBlockWhenExhausted()
Returns whether to block when theborrowObject()
method is invoked when the pool is exhausted (the maximum number of "active" objects has been reached).- Returns:
true
ifborrowObject()
should block when the pool is exhausted- See Also:
setBlockWhenExhausted(boolean)
-
setBlockWhenExhausted
public final void setBlockWhenExhausted(boolean blockWhenExhausted)
Sets whether to block when theborrowObject()
method is invoked when the pool is exhausted (the maximum number of "active" objects has been reached).- Parameters:
blockWhenExhausted
-true
ifborrowObject()
should block when the pool is exhausted- See Also:
getBlockWhenExhausted()
-
getMaxWaitMillis
public final long getMaxWaitMillis()
Returns the maximum amount of time (in milliseconds) theborrowObject()
method should block before throwing an exception when the pool is exhausted andgetBlockWhenExhausted()
is true. When less than 0, theborrowObject()
method may block indefinitely.- Returns:
- the maximum number of milliseconds
borrowObject()
will block. - See Also:
setMaxWaitMillis(long)
,setBlockWhenExhausted(boolean)
-
setMaxWaitMillis
public final void setMaxWaitMillis(long maxWaitMillis)
Sets the maximum amount of time (in milliseconds) theborrowObject()
method should block before throwing an exception when the pool is exhausted andgetBlockWhenExhausted()
is true. When less than 0, theborrowObject()
method may block indefinitely.- Parameters:
maxWaitMillis
- the maximum number of millisecondsborrowObject()
will block or negative for indefinitely.- See Also:
getMaxWaitMillis()
,setBlockWhenExhausted(boolean)
-
getLifo
public final 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.- Returns:
true
if the pool is configured with LIFO behaviour orfalse
if the pool is configured with FIFO behaviour- See Also:
setLifo(boolean)
-
getFairness
public final boolean getFairness()
Returns whether or not the pool serves threads waiting to borrow objects fairly. True means that waiting threads are served as if waiting in a FIFO queue.- Returns:
true
if waiting threads are to be served by the pool in arrival order
-
setLifo
public final 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.- Parameters:
lifo
-true
if the pool is to be configured with LIFO behaviour orfalse
if the pool is to be configured with FIFO behaviour- See Also:
getLifo()
-
getTestOnCreate
public final boolean getTestOnCreate()
Returns whether objects created for the pool will be validated before being returned from theborrowObject()
method. Validation is performed by thevalidateObject()
method of the factory associated with the pool. If the object fails to validate, thenborrowObject()
will fail.- Returns:
true
if newly created objects are validated before being returned from theborrowObject()
method- Since:
- 2.2
- See Also:
setTestOnCreate(boolean)
-
setTestOnCreate
public final void setTestOnCreate(boolean testOnCreate)
Sets whether objects created for the pool will be validated before being returned from theborrowObject()
method. Validation is performed by thevalidateObject()
method of the factory associated with the pool. If the object fails to validate, thenborrowObject()
will fail.- Parameters:
testOnCreate
-true
if newly created objects should be validated before being returned from theborrowObject()
method- Since:
- 2.2
- See Also:
getTestOnCreate()
-
getTestOnBorrow
public final boolean getTestOnBorrow()
Returns whether objects borrowed from the pool will be validated before being returned from theborrowObject()
method. Validation is performed by thevalidateObject()
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.- Returns:
true
if objects are validated before being returned from theborrowObject()
method- See Also:
setTestOnBorrow(boolean)
-
setTestOnBorrow
public final void setTestOnBorrow(boolean testOnBorrow)
Sets whether objects borrowed from the pool will be validated before being returned from theborrowObject()
method. Validation is performed by thevalidateObject()
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.- Parameters:
testOnBorrow
-true
if objects should be validated before being returned from theborrowObject()
method- See Also:
getTestOnBorrow()
-
getTestOnReturn
public final boolean getTestOnReturn()
Returns whether objects borrowed from the pool will be validated when they are returned to the pool via thereturnObject()
method. Validation is performed by thevalidateObject()
method of the factory associated with the pool. Returning objects that fail validation are destroyed rather then being returned the pool.- Returns:
true
if objects are validated on return to the pool via thereturnObject()
method- See Also:
setTestOnReturn(boolean)
-
setTestOnReturn
public final void setTestOnReturn(boolean testOnReturn)
Sets whether objects borrowed from the pool will be validated when they are returned to the pool via thereturnObject()
method. Validation is performed by thevalidateObject()
method of the factory associated with the pool. Returning objects that fail validation are destroyed rather then being returned the pool.- Parameters:
testOnReturn
-true
if objects are validated on return to the pool via thereturnObject()
method- See Also:
getTestOnReturn()
-
getTestWhileIdle
public final boolean getTestWhileIdle()
Returns whether objects sitting idle in the pool will be validated by the idle object evictor (if any - seesetTimeBetweenEvictionRunsMillis(long)
). Validation is performed by thevalidateObject()
method of the factory associated with the pool. If the object fails to validate, it will be removed from the pool and destroyed.- Returns:
true
if objects will be validated by the evictor- See Also:
setTestWhileIdle(boolean)
,setTimeBetweenEvictionRunsMillis(long)
-
setTestWhileIdle
public final void setTestWhileIdle(boolean testWhileIdle)
Returns whether objects sitting idle in the pool will be validated by the idle object evictor (if any - seesetTimeBetweenEvictionRunsMillis(long)
). Validation is performed by thevalidateObject()
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 settingtimeBetweenEvictionRunsMillis
to a positive value.- Parameters:
testWhileIdle
-true
so objects will be validated by the evictor- See Also:
getTestWhileIdle()
,setTimeBetweenEvictionRunsMillis(long)
-
getTimeBetweenEvictionRunsMillis
public final 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 final 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 final int getNumTestsPerEvictionRun()
Returns the maximum number of objects to examine during each run (if any) of the idle object evictor thread. When positive, the number of tests performed for a run will be the minimum of the configured value and the number of idle instances in the pool. When negative, the number of tests performed will beceil(
which means that when the value isgetNumIdle()
/ abs(getNumTestsPerEvictionRun()
))-n
roughly one nth of the idle objects will be tested per run.- Returns:
- max number of objects to examine during each evictor run
- See Also:
setNumTestsPerEvictionRun(int)
,setTimeBetweenEvictionRunsMillis(long)
-
setNumTestsPerEvictionRun
public final void setNumTestsPerEvictionRun(int numTestsPerEvictionRun)
Sets the maximum number of objects to examine during each run (if any) of the idle object evictor thread. When positive, the number of tests performed for a run will be the minimum of the configured value and the number of idle instances in the pool. When negative, the number of tests performed will beceil(
which means that when the value isgetNumIdle()
/ abs(getNumTestsPerEvictionRun()
))-n
roughly one nth of the idle objects will be tested per run.- Parameters:
numTestsPerEvictionRun
- max number of objects to examine during each evictor run- See Also:
getNumTestsPerEvictionRun()
,setTimeBetweenEvictionRunsMillis(long)
-
getMinEvictableIdleTimeMillis
public final 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 - seesetTimeBetweenEvictionRunsMillis(long)
). When non-positive, no objects will be evicted from the pool due to idle time alone.- 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 final 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 - seesetTimeBetweenEvictionRunsMillis(long)
). 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 final 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 - seesetTimeBetweenEvictionRunsMillis(long)
), with the extra condition that at leastminIdle
object instances remain in the pool. This setting is overridden bygetMinEvictableIdleTimeMillis()
(that is, ifgetMinEvictableIdleTimeMillis()
is positive, thengetSoftMinEvictableIdleTimeMillis()
is ignored).- Returns:
- minimum amount of time an object may sit idle in the pool before it is eligible for eviction if minIdle instances are available
- See Also:
setSoftMinEvictableIdleTimeMillis(long)
-
setSoftMinEvictableIdleTimeMillis
public final 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 - seesetTimeBetweenEvictionRunsMillis(long)
), with the extra condition that at leastminIdle
object instances remain in the pool. This setting is overridden bygetMinEvictableIdleTimeMillis()
(that is, ifgetMinEvictableIdleTimeMillis()
is positive, thengetSoftMinEvictableIdleTimeMillis()
is ignored).- Parameters:
softMinEvictableIdleTimeMillis
- minimum amount of time an object may sit idle in the pool before it is eligible for eviction if minIdle instances are available- See Also:
getSoftMinEvictableIdleTimeMillis()
-
getEvictionPolicyClassName
public final java.lang.String getEvictionPolicyClassName()
Returns the name of theEvictionPolicy
implementation that is used by this pool.- Returns:
- The fully qualified class name of the
EvictionPolicy
- See Also:
setEvictionPolicyClassName(String)
-
setEvictionPolicyClassName
public final void setEvictionPolicyClassName(java.lang.String evictionPolicyClassName)
Sets the name of theEvictionPolicy
implementation that is used by this pool. The Pool will attempt to load the class using the thread context class loader. If that fails, the Pool will attempt to load the class using the class loader that loaded this class.- Parameters:
evictionPolicyClassName
- the fully qualified class name of the new eviction policy- See Also:
getEvictionPolicyClassName()
-
close
public abstract void close()
Closes the pool, destroys the remaining idle objects and, if registered in JMX, deregisters it.
-
isClosed
public final boolean isClosed()
Has this pool instance been closed.- Returns:
true
when this pool has been closed.
-
evict
public abstract 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.- Throws:
java.lang.Exception
- when there is a problem evicting idle objects.
-
getEvictionPolicy
protected EvictionPolicy<T> getEvictionPolicy()
Returns theEvictionPolicy
defined for this pool.- Returns:
- the eviction policy
- Since:
- 2.4
-
assertOpen
final void assertOpen() throws java.lang.IllegalStateException
Verifies that the pool is open.- Throws:
java.lang.IllegalStateException
- if the pool is closed.
-
startEvictor
final void startEvictor(long delay)
Starts the evictor with the given delay. If there is an evictor running when this method is called, it is stopped and replaced with a new evictor with the specified delay.
This method needs to be final, since it is called from a constructor. See POOL-195.
- Parameters:
delay
- time in milliseconds before start and between eviction runs
-
ensureMinIdle
abstract void ensureMinIdle() throws java.lang.Exception
Tries to ensure that the configured minimum number of idle instances are available in the pool.- Throws:
java.lang.Exception
- if an error occurs creating idle instances
-
getJmxName
public final javax.management.ObjectName getJmxName()
Provides the name under which the pool has been registered with the platform MBean server ornull
if the pool has not been registered.- Returns:
- the JMX name
-
getCreationStackTrace
public final java.lang.String getCreationStackTrace()
Provides the stack trace for the call that created this pool. JMX registration may trigger a memory leak so it is important that pools are deregistered when no longer used by calling theclose()
method. This method is provided to assist with identifying code that creates but does not close it thereby creating a memory leak.- Returns:
- pool creation stack trace
-
getBorrowedCount
public final long getBorrowedCount()
The total number of objects successfully borrowed from this pool over the lifetime of the pool.- Returns:
- the borrowed object count
-
getReturnedCount
public final long getReturnedCount()
The total number of objects returned to this pool over the lifetime of the pool. This excludes attempts to return the same object multiple times.- Returns:
- the returned object count
-
getCreatedCount
public final long getCreatedCount()
The total number of objects created for this pool over the lifetime of the pool.- Returns:
- the created object count
-
getDestroyedCount
public final long getDestroyedCount()
The total number of objects destroyed by this pool over the lifetime of the pool.- Returns:
- the destroyed object count
-
getDestroyedByEvictorCount
public final long getDestroyedByEvictorCount()
The total number of objects destroyed by the evictor associated with this pool over the lifetime of the pool.- Returns:
- the evictor destroyed object count
-
getDestroyedByBorrowValidationCount
public final long getDestroyedByBorrowValidationCount()
The total number of objects destroyed by this pool as a result of failing validation duringborrowObject()
over the lifetime of the pool.- Returns:
- validation destroyed object count
-
getMeanActiveTimeMillis
public final long getMeanActiveTimeMillis()
The mean time objects are active for based on the lastMEAN_TIMING_STATS_CACHE_SIZE
objects returned to the pool.- Returns:
- mean time an object has been checked out from the pool among recently returned objects
-
getMeanIdleTimeMillis
public final long getMeanIdleTimeMillis()
The mean time objects are idle for based on the lastMEAN_TIMING_STATS_CACHE_SIZE
objects borrowed from the pool.- Returns:
- mean time an object has been idle in the pool among recently borrowed objects
-
getMeanBorrowWaitTimeMillis
public final long getMeanBorrowWaitTimeMillis()
The mean time threads wait to borrow an object based on the lastMEAN_TIMING_STATS_CACHE_SIZE
objects borrowed from the pool.- Returns:
- mean time in milliseconds that a recently served thread has had to wait to borrow an object from the pool
-
getMaxBorrowWaitTimeMillis
public final long getMaxBorrowWaitTimeMillis()
The maximum time a thread has waited to borrow objects from the pool.- Returns:
- maximum wait time in milliseconds since the pool was created
-
getNumIdle
public abstract int getNumIdle()
The number of instances currently idle in this pool.- Returns:
- count of instances available for checkout from the pool
-
getSwallowedExceptionListener
public final SwallowedExceptionListener getSwallowedExceptionListener()
The listener used (if any) to receive notifications of exceptions unavoidably swallowed by the pool.- Returns:
- The listener or
null
for no listener
-
setSwallowedExceptionListener
public final void setSwallowedExceptionListener(SwallowedExceptionListener swallowedExceptionListener)
The listener used (if any) to receive notifications of exceptions unavoidably swallowed by the pool.- Parameters:
swallowedExceptionListener
- The listener ornull
for no listener
-
swallowException
final void swallowException(java.lang.Exception e)
Swallows an exception and notifies the configured listener for swallowed exceptions queue.- Parameters:
e
- exception to be swallowed
-
updateStatsBorrow
final void updateStatsBorrow(PooledObject<T> p, long waitTime)
Updates statistics after an object is borrowed from the pool.- Parameters:
p
- object borrowed from the poolwaitTime
- time (in milliseconds) that the borrowing thread had to wait
-
updateStatsReturn
final void updateStatsReturn(long activeTime)
Updates statistics after an object is returned to the pool.- Parameters:
activeTime
- the amount of time (in milliseconds) that the returning object was checked out
-
jmxUnregister
final void jmxUnregister()
Unregisters this pool's MBean.
-
jmxRegister
private javax.management.ObjectName jmxRegister(BaseObjectPoolConfig config, java.lang.String jmxNameBase, java.lang.String jmxNamePrefix)
Registers the pool with the platform MBean server. The registered name will bejmxNameBase + jmxNamePrefix + i
where i is the least integer greater than or equal to 1 such that the name is not already registered. Swallows MBeanRegistrationException, NotCompliantMBeanException returning null.- Parameters:
config
- Pool configurationjmxNameBase
- default base JMX name for this pooljmxNamePrefix
- name prefix- Returns:
- registered ObjectName, null if registration fails
-
getStackTrace
private java.lang.String getStackTrace(java.lang.Exception e)
Gets the stack trace of an exception as a string.- Parameters:
e
- exception to trace- Returns:
- exception stack trace as a string
-
-