T - Type of element pooled in this pool.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>
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.
GenericKeyedObjectPool| 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. |
| Modifier and Type | Method and Description |
|---|---|
void |
addObject()
Creates an object, and place it into the pool.
|
T |
borrowObject()
Equivalent to
. |
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) |
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, setTimeBetweenEvictionRunsMillisclone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, waitgetBlockWhenExhausted, getBorrowedCount, getCreatedCount, getCreationStackTrace, getDestroyedByBorrowValidationCount, getDestroyedByEvictorCount, getDestroyedCount, getFairness, getLifo, getMaxBorrowWaitTimeMillis, getMaxTotal, getMaxWaitMillis, getMeanActiveTimeMillis, getMeanBorrowWaitTimeMillis, getMeanIdleTimeMillis, getMinEvictableIdleTimeMillis, getNumTestsPerEvictionRun, getReturnedCount, getTestOnBorrow, getTestOnCreate, getTestOnReturn, getTestWhileIdle, getTimeBetweenEvictionRunsMillis, isClosedpublic CommonsPoolGenericObjectPool(org.apache.commons.pool2.PooledObjectFactory<T> factory)
GenericObjectPool using defaults from
GenericObjectPoolConfig.factory - The object factory to be used to create object instances
used by this poolpublic CommonsPoolGenericObjectPool(org.apache.commons.pool2.PooledObjectFactory<T> factory, org.apache.commons.pool2.impl.GenericObjectPoolConfig<T> config)
GenericObjectPool using a specific
configuration.factory - The object factory to be used to create object instances
used by this poolconfig - 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.public CommonsPoolGenericObjectPool(org.apache.commons.pool2.PooledObjectFactory<T> factory, org.apache.commons.pool2.impl.GenericObjectPoolConfig<T> config, org.apache.commons.pool2.impl.AbandonedConfig abandonedConfig)
GenericObjectPool that tracks and destroys
objects that are checked out, but never returned to the pool.factory - The object factory to be used to create object instances
used by this poolconfig - 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.public int getMaxIdle()
getMaxIdle in interface org.apache.commons.pool2.impl.GenericObjectPoolMXBeansetMaxIdle(int)public void setMaxIdle(int maxIdle)
maxIdle - The cap on the number of "idle" instances in the pool. Use a
negative value to indicate an unlimited number of idle
instancesgetMaxIdle()public void setMinIdle(int minIdle)
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.
minIdle - The minimum number of objects.getMinIdle(),
getMaxIdle(),
BaseGenericObjectPool.getTimeBetweenEvictionRunsMillis()public int getMinIdle()
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.
getMinIdle in interface org.apache.commons.pool2.impl.GenericObjectPoolMXBeansetMinIdle(int),
setMaxIdle(int),
BaseGenericObjectPool.setTimeBetweenEvictionRunsMillis(long)public boolean isAbandonedConfig()
isAbandonedConfig in interface org.apache.commons.pool2.impl.GenericObjectPoolMXBeanpublic boolean getLogAbandoned()
getLogAbandoned in interface org.apache.commons.pool2.impl.GenericObjectPoolMXBeantrue if abandoned object removal is configured for this
pool and removal events are to be logged otherwise falseAbandonedConfig.getLogAbandoned()public boolean getRemoveAbandonedOnBorrow()
getRemoveAbandonedOnBorrow in interface org.apache.commons.pool2.impl.GenericObjectPoolMXBeantrue if abandoned object removal is configured to be
activated by borrowObject otherwise falseAbandonedConfig.getRemoveAbandonedOnBorrow()public boolean getRemoveAbandonedOnMaintenance()
getRemoveAbandonedOnMaintenance in interface org.apache.commons.pool2.impl.GenericObjectPoolMXBeantrue if abandoned object removal is configured to be
activated when the evictor runs otherwise falseAbandonedConfig.getRemoveAbandonedOnMaintenance()public int getRemoveAbandonedTimeout()
getRemoveAbandonedTimeout in interface org.apache.commons.pool2.impl.GenericObjectPoolMXBeanAbandonedConfig.getRemoveAbandonedTimeout()public void setConfig(org.apache.commons.pool2.impl.GenericObjectPoolConfig<T> conf)
conf - the new configuration to use. This is used by value.GenericObjectPoolConfigpublic void setAbandonedConfig(org.apache.commons.pool2.impl.AbandonedConfig abandonedConfig)
abandonedConfig - the new configuration to use. This is used by value.AbandonedConfigpublic org.apache.commons.pool2.PooledObjectFactory<T> getFactory()
public T borrowObject() throws Exception
borrowObject(BaseGenericObjectPool.getMaxWaitMillis()).
public T borrowObject(long borrowMaxWaitMillis) throws Exception
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.
borrowMaxWaitMillis - The time to wait in milliseconds for an object
to become availableNoSuchElementException - if an instance cannot be returnedException - if an object instance cannot be returned due to an
errorpublic 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.
returnObject in interface org.apache.commons.pool2.ObjectPool<T>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.
invalidateObject in interface org.apache.commons.pool2.ObjectPool<T>Exception - if an exception occurs destroying the
objectIllegalStateException - if obj does not belong to this poolpublic 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.
invalidateObject in interface org.apache.commons.pool2.ObjectPool<T>Exception - if an exception occurs destroying the
objectIllegalStateException - if obj does not belong to this poolpublic void clear()
PooledObjectFactory.destroyObject(PooledObject) method on each
idle instance.
Implementation notes:
SwallowedExceptionListener.clear in interface org.apache.commons.pool2.ObjectPool<T>public int getNumActive()
getNumActive in interface org.apache.commons.pool2.impl.GenericObjectPoolMXBeangetNumActive in interface org.apache.commons.pool2.ObjectPool<T>public int getNumIdle()
public void close()
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().
public void evict()
throws Exception
Successive activations of this method examine objects in sequence, cycling through objects in oldest-to-youngest order.
public void preparePool()
throws Exception
getMinIdle() idle instances are available
in the pool.Exception - If the associated factory throws an exceptionpublic void addObject()
throws Exception
If there is no capacity available to add to the pool, this is a no-op (no exception, no impact to the pool).
public void use(T pooledObject)
use in interface org.apache.commons.pool2.UsageTracking<T>public int getNumWaiters()
getNumWaiters in interface org.apache.commons.pool2.impl.GenericObjectPoolMXBeanpublic String getFactoryType()
getFactoryType in interface org.apache.commons.pool2.impl.GenericObjectPoolMXBeanpublic Set<org.apache.commons.pool2.impl.DefaultPooledObjectInfo> listAllObjects()
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.
listAllObjects in interface org.apache.commons.pool2.impl.GenericObjectPoolMXBeanprotected void toStringAppendFields(StringBuilder builder)
toStringAppendFields in class org.apache.commons.pool2.impl.BaseGenericObjectPool<T>