org.apache.commons.pool2.impl

Class CommonsPoolGenericObjectPool<T>

java.lang.Object

org.apache.commons.pool2.BaseObject

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

org.apache.commons.pool2.impl.CommonsPoolGenericObjectPool<T>

Type Parameters:

T - Type of element pooled in this pool.

All Implemented Interfaces:

Closeable, AutoCloseable, org.apache.commons.pool2.impl.GenericObjectPoolMXBean, org.apache.commons.pool2.ObjectPool<T>, org.apache.commons.pool2.UsageTracking<T>

public class CommonsPoolGenericObjectPool<T>
extends org.apache.commons.pool2.impl.BaseGenericObjectPool<T>
implements org.apache.commons.pool2.ObjectPool<T>, org.apache.commons.pool2.impl.GenericObjectPoolMXBean, org.apache.commons.pool2.UsageTracking<T>

A configurable ObjectPool implementation.

When coupled with the appropriate PooledObjectFactory, GenericObjectPool provides robust pooling functionality for arbitrary objects.

Optionally, one may configure the pool to examine and possibly evict objects as they sit idle in the pool and to ensure that a minimum number of idle objects are available. This is performed by an "idle object eviction" thread, which runs asynchronously. Caution should be used when configuring this optional feature. Eviction runs contend with client threads for access to objects in the pool, so if they run too frequently performance issues may result.

The pool can also be configured to detect and remove "abandoned" objects, i.e. objects that have been checked out of the pool but neither used nor returned before the configured removeAbandonedTimeout. Abandoned object removal can be configured to happen when borrowObject is invoked and the pool is close to starvation, or it can be executed by the idle object evictor, or both. If pooled objects implement the TrackedUse interface, their last use will be queried using the getLastUsed method on that interface; otherwise abandonment is determined by how long an object has been checked out from the pool.

Implementation note: To prevent possible deadlocks, care has been taken to ensure that no call to a factory method will occur within a synchronization block. See POOL-125 and DBCP-44 for more information.

This class is intended to be thread-safe.

Since:

2.0

See Also:

GenericKeyedObjectPool

Field Summary

Fields inherited from class org.apache.commons.pool2.impl.BaseGenericObjectPool

MEAN_TIMING_STATS_CACHE_SIZE

Constructor Summary

Constructors

Constructor and Description
CommonsPoolGenericObjectPool(org.apache.commons.pool2.PooledObjectFactory<T> factory) Creates a new GenericObjectPool using defaults from GenericObjectPoolConfig.
CommonsPoolGenericObjectPool(org.apache.commons.pool2.PooledObjectFactory<T> factory, org.apache.commons.pool2.impl.GenericObjectPoolConfig<T> config) Creates a new GenericObjectPool using a specific configuration.
CommonsPoolGenericObjectPool(org.apache.commons.pool2.PooledObjectFactory<T> factory, org.apache.commons.pool2.impl.GenericObjectPoolConfig<T> config, org.apache.commons.pool2.impl.AbandonedConfig abandonedConfig) Creates a new GenericObjectPool that tracks and destroys objects that are checked out, but never returned to the pool.

Method Summary

Modifier and Type	Method and Description
void	addObject() Creates an object, and place it into the pool.
T	borrowObject() Equivalent to borrowObject(BaseGenericObjectPool.getMaxWaitMillis()).
T	borrowObject(long borrowMaxWaitMillis) Borrows an object from the pool using the specific waiting time which only applies if BaseGenericObjectPool.getBlockWhenExhausted() is true.
void	clear() Clears any objects sitting idle in the pool by removing them from the idle instance pool and then invoking the configured PooledObjectFactory.destroyObject(PooledObject) method on each idle instance.
void	close() Closes the pool.
void	evict()
org.apache.commons.pool2.PooledObjectFactory<T>	getFactory() Obtains a reference to the factory used to create, destroy and validate the objects used by this pool.
String	getFactoryType() Returns the type - including the specific type rather than the generic - of the factory.
boolean	getLogAbandoned() Gets whether this pool identifies and logs any abandoned objects.
int	getMaxIdle() Returns the cap on the number of "idle" instances in the pool.
int	getMinIdle() Returns the target for the minimum number of idle objects to maintain in the pool.
int	getNumActive()
int	getNumIdle()
int	getNumWaiters() Returns an estimate of the number of threads currently blocked waiting for an object from the pool.
boolean	getRemoveAbandonedOnBorrow() Gets whether a check is made for abandoned objects when an object is borrowed from this pool.
boolean	getRemoveAbandonedOnMaintenance() Gets whether a check is made for abandoned objects when the evictor runs.
int	getRemoveAbandonedTimeout() Obtains the timeout before which an object will be considered to be abandoned by this pool.
void	invalidateObject(T obj)
void	invalidateObject(T obj, org.apache.commons.pool2.DestroyMode mode)
boolean	isAbandonedConfig() Gets whether or not abandoned object removal is configured for this pool.
Set<org.apache.commons.pool2.impl.DefaultPooledObjectInfo>	listAllObjects() Provides information on all the objects in the pool, both idle (waiting to be borrowed) and active (currently borrowed).
void	preparePool() Tries to ensure that getMinIdle() idle instances are available in the pool.
void	returnObject(T obj)
void	setAbandonedConfig(org.apache.commons.pool2.impl.AbandonedConfig abandonedConfig) Sets the abandoned object removal configuration.
void	setConfig(org.apache.commons.pool2.impl.GenericObjectPoolConfig<T> conf) Sets the base pool configuration.
void	setMaxIdle(int maxIdle) Returns the cap on the number of "idle" instances in the pool.
void	setMinIdle(int minIdle) Sets the target for the minimum number of idle objects to maintain in the pool.
protected void	toStringAppendFields(StringBuilder builder)
void	use(T pooledObject)

Methods inherited from class org.apache.commons.pool2.impl.BaseGenericObjectPool

getBlockWhenExhausted, getBorrowedCount, getCreatedCount, getCreationStackTrace, getDestroyedByBorrowValidationCount, getDestroyedByEvictorCount, getDestroyedCount, getEvictionPolicy, getEvictionPolicyClassName, getEvictorShutdownTimeoutMillis, getFairness, getJmxName, getLifo, getMaxBorrowWaitTimeMillis, getMaxTotal, getMaxWaitMillis, getMeanActiveTimeMillis, getMeanBorrowWaitTimeMillis, getMeanIdleTimeMillis, getMinEvictableIdleTimeMillis, getNumTestsPerEvictionRun, getReturnedCount, getSoftMinEvictableIdleTimeMillis, getSwallowedExceptionListener, getTestOnBorrow, getTestOnCreate, getTestOnReturn, getTestWhileIdle, getTimeBetweenEvictionRunsMillis, isClosed, markReturningState, setBlockWhenExhausted, setConfig, setEvictionPolicy, setEvictionPolicyClassName, setEvictionPolicyClassName, setEvictorShutdownTimeoutMillis, setLifo, setMaxTotal, setMaxWaitMillis, setMinEvictableIdleTimeMillis, setNumTestsPerEvictionRun, setSoftMinEvictableIdleTimeMillis, setSwallowedExceptionListener, setTestOnBorrow, setTestOnCreate, setTestOnReturn, setTestWhileIdle, setTimeBetweenEvictionRunsMillis

Methods inherited from class org.apache.commons.pool2.BaseObject

toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.apache.commons.pool2.ObjectPool

addObjects

Methods inherited from interface org.apache.commons.pool2.impl.GenericObjectPoolMXBean

getBlockWhenExhausted, getBorrowedCount, getCreatedCount, getCreationStackTrace, getDestroyedByBorrowValidationCount, getDestroyedByEvictorCount, getDestroyedCount, getFairness, getLifo, getMaxBorrowWaitTimeMillis, getMaxTotal, getMaxWaitMillis, getMeanActiveTimeMillis, getMeanBorrowWaitTimeMillis, getMeanIdleTimeMillis, getMinEvictableIdleTimeMillis, getNumTestsPerEvictionRun, getReturnedCount, getTestOnBorrow, getTestOnCreate, getTestOnReturn, getTestWhileIdle, getTimeBetweenEvictionRunsMillis, isClosed

Constructor Detail

CommonsPoolGenericObjectPool

public CommonsPoolGenericObjectPool(org.apache.commons.pool2.PooledObjectFactory<T> factory)

Creates a new GenericObjectPool using defaults from GenericObjectPoolConfig.

Parameters:

factory - The object factory to be used to create object instances used by this pool

CommonsPoolGenericObjectPool

public CommonsPoolGenericObjectPool(org.apache.commons.pool2.PooledObjectFactory<T> factory,
                                    org.apache.commons.pool2.impl.GenericObjectPoolConfig<T> config)

Creates a new GenericObjectPool using a specific configuration.

Parameters:

factory - The object factory to be used to create object instances used by this pool

config - The configuration to use for this pool instance. The configuration is used by value. Subsequent changes to the configuration object will not be reflected in the pool.

CommonsPoolGenericObjectPool

public CommonsPoolGenericObjectPool(org.apache.commons.pool2.PooledObjectFactory<T> factory,
                                    org.apache.commons.pool2.impl.GenericObjectPoolConfig<T> config,
                                    org.apache.commons.pool2.impl.AbandonedConfig abandonedConfig)

Creates a new GenericObjectPool that tracks and destroys objects that are checked out, but never returned to the pool.

Parameters:

factory - The object factory to be used to create object instances used by this pool

config - The base pool configuration to use for this pool instance. The configuration is used by value. Subsequent changes to the configuration object will not be reflected in the pool.

abandonedConfig - Configuration for abandoned object identification and removal. The configuration is used by value.

Method Detail

getMaxIdle

public int getMaxIdle()

Returns the cap on the number of "idle" instances in the pool. If maxIdle is set too low on heavily loaded systems it is possible you will see objects being destroyed and almost immediately new objects being created. This is a result of the active threads momentarily returning objects faster than they are requesting them, causing the number of idle objects to rise above maxIdle. The best value for maxIdle for heavily loaded system will vary but the default is a good starting point.

Specified by:

getMaxIdle in interface org.apache.commons.pool2.impl.GenericObjectPoolMXBean

Returns:

the maximum number of "idle" instances that can be held in the pool or a negative value if there is no limit

See Also:

setMaxIdle(int)

setMaxIdle

public void setMaxIdle(int maxIdle)

Returns the cap on the number of "idle" instances in the pool. If maxIdle is set too low on heavily loaded systems it is possible you will see objects being destroyed and almost immediately new objects being created. This is a result of the active threads momentarily returning objects faster than they are requesting them, causing the number of idle objects to rise above maxIdle. The best value for maxIdle for heavily loaded system will vary but the default is a good starting point.

Parameters:

maxIdle - The cap on the number of "idle" instances in the pool. Use a negative value to indicate an unlimited number of idle instances

See Also:

getMaxIdle()

setMinIdle

public void setMinIdle(int minIdle)

Sets the target for the minimum number of idle objects to maintain in the pool. This setting only has an effect if it is positive and BaseGenericObjectPool.getTimeBetweenEvictionRunsMillis() is greater than zero. If this is the case, an attempt is made to ensure that the pool has the required minimum number of instances during idle object eviction runs.

If the configured value of minIdle is greater than the configured value for maxIdle then the value of maxIdle will be used instead.

Parameters:

minIdle - The minimum number of objects.

See Also:

getMinIdle(), getMaxIdle(), BaseGenericObjectPool.getTimeBetweenEvictionRunsMillis()

getMinIdle

public int getMinIdle()

Returns the target for the minimum number of idle objects to maintain in the pool. This setting only has an effect if it is positive and BaseGenericObjectPool.getTimeBetweenEvictionRunsMillis() is greater than zero. If this is the case, an attempt is made to ensure that the pool has the required minimum number of instances during idle object eviction runs.

If the configured value of minIdle is greater than the configured value for maxIdle then the value of maxIdle will be used instead.

Specified by:

getMinIdle in interface org.apache.commons.pool2.impl.GenericObjectPoolMXBean

Returns:

The minimum number of objects.

See Also:

setMinIdle(int), setMaxIdle(int), BaseGenericObjectPool.setTimeBetweenEvictionRunsMillis(long)

isAbandonedConfig

public boolean isAbandonedConfig()

Gets whether or not abandoned object removal is configured for this pool.

Specified by:

isAbandonedConfig in interface org.apache.commons.pool2.impl.GenericObjectPoolMXBean

Returns:

true if this pool is configured to detect and remove abandoned objects

getLogAbandoned

public boolean getLogAbandoned()

Gets whether this pool identifies and logs any abandoned objects.

Specified by:

getLogAbandoned in interface org.apache.commons.pool2.impl.GenericObjectPoolMXBean

Returns:

true if abandoned object removal is configured for this pool and removal events are to be logged otherwise false

See Also:

AbandonedConfig.getLogAbandoned()

getRemoveAbandonedOnBorrow

public boolean getRemoveAbandonedOnBorrow()

Gets whether a check is made for abandoned objects when an object is borrowed from this pool.

Specified by:

getRemoveAbandonedOnBorrow in interface org.apache.commons.pool2.impl.GenericObjectPoolMXBean

Returns:

true if abandoned object removal is configured to be activated by borrowObject otherwise false

See Also:

AbandonedConfig.getRemoveAbandonedOnBorrow()

getRemoveAbandonedOnMaintenance

public boolean getRemoveAbandonedOnMaintenance()

Gets whether a check is made for abandoned objects when the evictor runs.

Specified by:

getRemoveAbandonedOnMaintenance in interface org.apache.commons.pool2.impl.GenericObjectPoolMXBean

Returns:

true if abandoned object removal is configured to be activated when the evictor runs otherwise false

See Also:

AbandonedConfig.getRemoveAbandonedOnMaintenance()

getRemoveAbandonedTimeout

public int getRemoveAbandonedTimeout()

Obtains the timeout before which an object will be considered to be abandoned by this pool.

Specified by:

getRemoveAbandonedTimeout in interface org.apache.commons.pool2.impl.GenericObjectPoolMXBean

Returns:

The abandoned object timeout in seconds if abandoned object removal is configured for this pool; Integer.MAX_VALUE otherwise.

See Also:

AbandonedConfig.getRemoveAbandonedTimeout()

setConfig

public void setConfig(org.apache.commons.pool2.impl.GenericObjectPoolConfig<T> conf)

Sets the base pool configuration.

Parameters:

conf - the new configuration to use. This is used by value.

See Also:

GenericObjectPoolConfig

setAbandonedConfig

public void setAbandonedConfig(org.apache.commons.pool2.impl.AbandonedConfig abandonedConfig)

Sets the abandoned object removal configuration.

Parameters:

abandonedConfig - the new configuration to use. This is used by value.

See Also:

AbandonedConfig

getFactory

public org.apache.commons.pool2.PooledObjectFactory<T> getFactory()

Obtains a reference to the factory used to create, destroy and validate the objects used by this pool.

Returns:

the factory

borrowObject

public T borrowObject()
               throws Exception

Equivalent to borrowObject(BaseGenericObjectPool.getMaxWaitMillis()).

Specified by:

borrowObject in interface org.apache.commons.pool2.ObjectPool<T>

Throws:

Exception

borrowObject

public T borrowObject(long borrowMaxWaitMillis)
               throws Exception

Borrows an object from the pool using the specific waiting time which only applies if BaseGenericObjectPool.getBlockWhenExhausted() is true.

If there is one or more idle instance available in the pool, then an idle instance will be selected based on the value of BaseGenericObjectPool.getLifo(), activated and returned. If activation fails, or testOnBorrow is set to true and validation fails, the instance is destroyed and the next available instance is examined. This continues until either a valid instance is returned or there are no more idle instances available.

If there are no idle instances available in the pool, behavior depends on the maxTotal, (if applicable) BaseGenericObjectPool.getBlockWhenExhausted() and the value passed in to the borrowMaxWaitMillis parameter. If the number of instances checked out from the pool is less than maxTotal, a new instance is created, activated and (if applicable) validated and returned to the caller. If validation fails, a NoSuchElementException is thrown.

If the pool is exhausted (no available idle instances and no capacity to create new ones), this method will either block (if BaseGenericObjectPool.getBlockWhenExhausted() is true) or throw a NoSuchElementException (if BaseGenericObjectPool.getBlockWhenExhausted() is false). The length of time that this method will block when BaseGenericObjectPool.getBlockWhenExhausted() is true is determined by the value passed in to the borrowMaxWaitMillis parameter.

When the pool is exhausted, multiple calling threads may be simultaneously blocked waiting for instances to become available. A "fairness" algorithm has been implemented to ensure that threads receive available instances in request arrival order.

Parameters:

borrowMaxWaitMillis - The time to wait in milliseconds for an object to become available

Returns:

object instance from the pool

Throws:

NoSuchElementException - if an instance cannot be returned

Exception - if an object instance cannot be returned due to an error

returnObject

public void returnObject(T obj)

If maxIdle is set to a positive value and the number of idle instances has reached this value, the returning instance is destroyed.

If testOnReturn == true, the returning instance is validated before being returned to the idle instance pool. In this case, if validation fails, the instance is destroyed.

Exceptions encountered destroying objects for any reason are swallowed but notified via a SwallowedExceptionListener.

Specified by:

returnObject in interface org.apache.commons.pool2.ObjectPool<T>

invalidateObject

public void invalidateObject(T obj)
                      throws Exception

Activation of this method decrements the active count and attempts to destroy the instance, using the default (NORMAL) DestroyMode.

Specified by:

invalidateObject in interface org.apache.commons.pool2.ObjectPool<T>

Throws:

Exception - if an exception occurs destroying the object

IllegalStateException - if obj does not belong to this pool

invalidateObject

public void invalidateObject(T obj,
                             org.apache.commons.pool2.DestroyMode mode)
                      throws Exception

Activation of this method decrements the active count and attempts to destroy the instance, using the provided DestroyMode.

Specified by:

invalidateObject in interface org.apache.commons.pool2.ObjectPool<T>

Throws:

Exception - if an exception occurs destroying the object

IllegalStateException - if obj does not belong to this pool

Since:

2.9.0

clear

public void clear()

Clears any objects sitting idle in the pool by removing them from the idle instance pool and then invoking the configured PooledObjectFactory.destroyObject(PooledObject) method on each idle instance.

Implementation notes:

• This method does not destroy or effect in any way instances that are checked out of the pool when it is invoked.
• Invoking this method does not prevent objects being returned to the idle instance pool, even during its execution. Additional instances may be returned while removed items are being destroyed.
• Exceptions encountered destroying idle instances are swallowed but notified via a SwallowedExceptionListener.

Specified by:

clear in interface org.apache.commons.pool2.ObjectPool<T>

getNumActive

public int getNumActive()

Specified by:

getNumActive in interface org.apache.commons.pool2.impl.GenericObjectPoolMXBean

Specified by:

getNumActive in interface org.apache.commons.pool2.ObjectPool<T>

getNumIdle

public int getNumIdle()

Specified by:

getNumIdle in interface org.apache.commons.pool2.impl.GenericObjectPoolMXBean

Specified by:

getNumIdle in interface org.apache.commons.pool2.ObjectPool<T>

Specified by:

getNumIdle in class org.apache.commons.pool2.impl.BaseGenericObjectPool<T>

close

public void close()

Closes the pool. Once the pool is closed, borrowObject() will fail with IllegalStateException, but returnObject(Object) and invalidateObject(Object) will continue to work, with returned objects destroyed on return.

Destroys idle instances in the pool by invoking clear().

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable

Specified by:

close in interface org.apache.commons.pool2.ObjectPool<T>

Specified by:

close in class org.apache.commons.pool2.impl.BaseGenericObjectPool<T>

evict

public void evict()
           throws Exception

Successive activations of this method examine objects in sequence, cycling through objects in oldest-to-youngest order.

Specified by:

evict in class org.apache.commons.pool2.impl.BaseGenericObjectPool<T>

Throws:

Exception

preparePool

public void preparePool()
                 throws Exception

Tries to ensure that getMinIdle() idle instances are available in the pool.

Throws:

Exception - If the associated factory throws an exception

Since:

2.4

addObject

public void addObject()
               throws Exception

Creates an object, and place it into the pool. addObject() is useful for "pre-loading" a pool with idle objects.

If there is no capacity available to add to the pool, this is a no-op (no exception, no impact to the pool).

Specified by:

addObject in interface org.apache.commons.pool2.ObjectPool<T>

Throws:

Exception

use

public void use(T pooledObject)

Specified by:

use in interface org.apache.commons.pool2.UsageTracking<T>

getNumWaiters

public int getNumWaiters()

Returns an estimate of the number of threads currently blocked waiting for an object from the pool. This is intended for monitoring only, not for synchronization control.

Specified by:

getNumWaiters in interface org.apache.commons.pool2.impl.GenericObjectPoolMXBean

Returns:

The estimate of the number of threads currently blocked waiting for an object from the pool

getFactoryType

public String getFactoryType()

Returns the type - including the specific type rather than the generic - of the factory.

Specified by:

getFactoryType in interface org.apache.commons.pool2.impl.GenericObjectPoolMXBean

Returns:

A string representation of the factory type

listAllObjects

public Set<org.apache.commons.pool2.impl.DefaultPooledObjectInfo> listAllObjects()

Provides information on all the objects in the pool, both idle (waiting to be borrowed) and active (currently borrowed).

Note: This is named listAllObjects so it is presented as an operation via JMX. That means it won't be invoked unless the explicitly requested whereas all attributes will be automatically requested when viewing the attributes for an object in a tool like JConsole.

Specified by:

listAllObjects in interface org.apache.commons.pool2.impl.GenericObjectPoolMXBean

Returns:

Information grouped on all the objects in the pool

toStringAppendFields

protected void toStringAppendFields(StringBuilder builder)

Overrides:

toStringAppendFields in class org.apache.commons.pool2.impl.BaseGenericObjectPool<T>