org.apache.commons.pool2.impl
Class BaseGenericObjectPool<T>

java.lang.Object
  extended by 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 Object

Base class that provides common functionality for GenericObjectPool and GenericKeyedObjectPool. The primary reason this class exists is reduce code duplication between the two pool implementations.

Since:
2.0
Version:
$Revision: $

Field Summary
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 Summary
BaseGenericObjectPool(BaseObjectPoolConfig config, String jmxNameBase, String jmxNamePrefix)
          Handles JMX registration (if required) and the initialization required for monitoring.
 
Method Summary
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.
 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 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 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.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

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
Constructor Detail

BaseGenericObjectPool

public BaseGenericObjectPool(BaseObjectPoolConfig config,
                             String jmxNameBase,
                             String jmxNamePrefix)
Handles JMX registration (if required) and the initialization required for monitoring.

Parameters:
config - Pool configuration
jmxNameBase - Base JMX name for the new pool
jmxNamePrefix - Prefix tobe 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 non-positive, there is no limit to the number of objects that can be managed by the pool at one time.

Returns:
the cap on the total number of object instances managed by the pool.
See Also:
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 the borrowObject() method is invoked when the pool is exhausted (the maximum number of "active" objects has been reached).

Returns:
true if borrowObject() should block when the pool is exhausted
See Also:
setBlockWhenExhausted(boolean)

setBlockWhenExhausted

public final 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).

Parameters:
blockWhenExhausted - true if borrowObject() should block when the pool is exhausted
See Also:
getBlockWhenExhausted()

getMaxWaitMillis

public final 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. When less than 0, the borrowObject() 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) the 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.

Parameters:
maxWaitMillis - the maximum number of milliseconds borrowObject() 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 or false if the pool is configured with FIFO behaviour
See Also:
setLifo(boolean)

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 or false if the pool is to be configured with FIFO behaviour
See Also:
getLifo()

getTestOnBorrow

public final boolean getTestOnBorrow()
Returns whether objects borrowed from the pool will be validated before being returned from the 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.

Returns:
true if objects are validated before being returned from the borrowObject() 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 the 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.

Parameters:
testOnBorrow - true if objects should be validated before being returned from the borrowObject() 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 the returnObject() method. Validation is performed by the validateObject() method of the factory associated with the pool. If the object fails to it will be destroyed rather then returned the pool.

Returns:
true if objects are validated on being returned to the pool via the returnObject() 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 the returnObject() method. Validation is performed by the validateObject() method of the factory associated with the pool. If the object fails to it will be destroyed rather then returned the pool.

Parameters:
testOnReturn - true if objects are validated on being returned to the pool via the returnObject() 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 - see 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.

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 - see 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.

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 be ceil(getNumIdle()/ abs(getNumTestsPerEvictionRun())) whch means that when the value is -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 be ceil(getNumIdle()/ abs(getNumTestsPerEvictionRun())) whch means that when the value is -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 - see setTimeBetweenEvictionRunsMillis(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 - see setTimeBetweenEvictionRunsMillis(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 - see 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).

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 - see 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).

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 String getEvictionPolicyClassName()
Returns the name of the EvictionPolicy 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(String evictionPolicyClassName)
Sets the name of the EvictionPolicy implementation that is used by this pool.

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 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.

Throws:
Exception - when there is a problem evicting idle objects.

getJmxName

public final 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.

Returns:
the JMX name

getCreationStackTrace

public final 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 the close() 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 during borrowObject() 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 last MEAN_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 last MEAN_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 last MEAN_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 or null for no listener


Copyright © 2001-2013 The Apache Software Foundation. All Rights Reserved.