T - Type of element pooled in this pool.public class GenericObjectPool<T> extends BaseGenericObjectPool<T> implements ObjectPool<T>, GenericObjectPoolMXBean, 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.
GenericKeyedObjectPoolabandonedConfig, MEAN_TIMING_STATS_CACHE_SIZE| Constructor and Description |
|---|
GenericObjectPool(PooledObjectFactory<T> factory)
Creates a new
GenericObjectPool using defaults from
GenericObjectPoolConfig. |
GenericObjectPool(PooledObjectFactory<T> factory,
GenericObjectPoolConfig<T> config)
Creates a new
GenericObjectPool using a specific
configuration. |
GenericObjectPool(PooledObjectFactory<T> factory,
GenericObjectPoolConfig<T> config,
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. addObject() is useful for
"pre-loading" a pool with idle objects.
|
T |
borrowObject()
Equivalent to
|
T |
borrowObject(java.time.Duration borrowMaxWaitDuration)
Borrows an object from the pool using the specific waiting time which only
applies if
BaseGenericObjectPool.getBlockWhenExhausted() is true. |
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()
Perform
numTests idle object eviction tests, evicting
examined objects that meet the criteria for eviction. |
PooledObjectFactory<T> |
getFactory()
Gets a reference to the factory used to create, destroy and validate
the objects used by this pool.
|
java.lang.String |
getFactoryType()
Gets the type - including the specific type rather than the generic -
of the factory.
|
int |
getMaxIdle()
Gets the cap on the number of "idle" instances in the pool.
|
int |
getMinIdle()
Gets the target for the minimum number of idle objects to maintain in
the pool.
|
int |
getNumActive()
Gets the number of instances currently borrowed from this pool.
|
int |
getNumIdle()
The number of instances currently idle in this pool.
|
int |
getNumWaiters()
Gets an estimate of the number of threads currently blocked waiting for
an object from the pool.
|
void |
invalidateObject(T obj)
Invalidates an object from the pool.
|
void |
invalidateObject(T obj,
DestroyMode destroyMode)
Invalidates an object from the pool, using the provided
DestroyMode
By contract, obj must have been obtained
using ObjectPool.borrowObject() or a related method as defined in an
implementation or sub-interface. |
java.util.Set<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)
Returns an instance to the pool.
|
void |
setConfig(GenericObjectPoolConfig<T> conf)
Sets the base pool configuration.
|
void |
setMaxIdle(int maxIdle)
Sets 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(java.lang.StringBuilder builder)
Used by sub-classes to include the fields defined by the sub-class in the
BaseObject.toString() output. |
void |
use(T pooledObject)
Called every time a pooled object is used to enable the pool to better track borrowed objects.
|
getBlockWhenExhausted, getBorrowedCount, getCreatedCount, getCreationStackTrace, getDestroyedByBorrowValidationCount, getDestroyedByEvictorCount, getDestroyedCount, getDurationBetweenEvictionRuns, getEvictionPolicy, getEvictionPolicyClassName, getEvictorShutdownTimeout, getEvictorShutdownTimeoutDuration, getEvictorShutdownTimeoutMillis, getFairness, getJmxName, getLifo, getLogAbandoned, getMaxBorrowWaitTimeMillis, getMaxTotal, getMaxWaitDuration, getMaxWaitMillis, getMeanActiveTimeMillis, getMeanBorrowWaitTimeMillis, getMeanIdleTimeMillis, getMessageStatistics, getMinEvictableIdleDuration, getMinEvictableIdleTime, getMinEvictableIdleTimeMillis, getNumTestsPerEvictionRun, getRemoveAbandonedOnBorrow, getRemoveAbandonedOnMaintenance, getRemoveAbandonedTimeout, getRemoveAbandonedTimeoutDuration, getReturnedCount, getSoftMinEvictableIdleDuration, getSoftMinEvictableIdleTime, getSoftMinEvictableIdleTimeMillis, getSwallowedExceptionListener, getTestOnBorrow, getTestOnCreate, getTestOnReturn, getTestWhileIdle, getTimeBetweenEvictionRuns, getTimeBetweenEvictionRunsMillis, isAbandonedConfig, isClosed, markReturningState, setAbandonedConfig, setBlockWhenExhausted, setConfig, setEvictionPolicy, setEvictionPolicyClassName, setEvictionPolicyClassName, setEvictorShutdownTimeout, setEvictorShutdownTimeoutMillis, setLifo, setMaxTotal, setMaxWait, setMaxWaitMillis, setMessagesStatistics, setMinEvictableIdle, setMinEvictableIdleTime, setMinEvictableIdleTimeMillis, setNumTestsPerEvictionRun, setSoftMinEvictableIdle, setSoftMinEvictableIdleTime, setSoftMinEvictableIdleTimeMillis, setSwallowedExceptionListener, setTestOnBorrow, setTestOnCreate, setTestOnReturn, setTestWhileIdle, setTimeBetweenEvictionRuns, setTimeBetweenEvictionRunsMillistoStringclone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, waitaddObjectsgetBlockWhenExhausted, getBorrowedCount, getCreatedCount, getCreationStackTrace, getDestroyedByBorrowValidationCount, getDestroyedByEvictorCount, getDestroyedCount, getFairness, getLifo, getLogAbandoned, getMaxBorrowWaitTimeMillis, getMaxTotal, getMaxWaitMillis, getMeanActiveTimeMillis, getMeanBorrowWaitTimeMillis, getMeanIdleTimeMillis, getMinEvictableIdleTimeMillis, getNumTestsPerEvictionRun, getRemoveAbandonedOnBorrow, getRemoveAbandonedOnMaintenance, getRemoveAbandonedTimeout, getReturnedCount, getTestOnBorrow, getTestOnCreate, getTestOnReturn, getTestWhileIdle, getTimeBetweenEvictionRunsMillis, isAbandonedConfig, isClosedpublic GenericObjectPool(PooledObjectFactory<T> factory)
GenericObjectPool using defaults from
GenericObjectPoolConfig.factory - The object factory to be used to create object instances
used by this poolpublic GenericObjectPool(PooledObjectFactory<T> factory, 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 GenericObjectPool(PooledObjectFactory<T> factory, GenericObjectPoolConfig<T> config, 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 void addObject()
throws java.lang.Exception
If there is no capacity available to add to the pool, this is a no-op (no exception, no impact to the pool).
addObject in interface ObjectPool<T>java.lang.Exception - when PooledObjectFactory.makeObject() fails.java.lang.IllegalStateException - after ObjectPool.close() has been called on this pool.java.lang.UnsupportedOperationException - when this pool cannot add new idle objects.public T borrowObject() throws java.lang.Exception
borrowObject(BaseGenericObjectPool.getMaxWaitDuration())
Instances returned from this method will have been either newly created
with PooledObjectFactory.makeObject() or will be a previously
idle object and have been activated with
PooledObjectFactory.activateObject(org.apache.tomcat.dbcp.pool2.PooledObject<T>) and then validated with
PooledObjectFactory.validateObject(org.apache.tomcat.dbcp.pool2.PooledObject<T>).
By contract, clients must return the borrowed instance
using ObjectPool.returnObject(T), ObjectPool.invalidateObject(T), or a related
method as defined in an implementation or sub-interface.
The behavior of this method when the pool has been exhausted is not strictly specified (although it may be specified by implementations).
borrowObject in interface ObjectPool<T>java.lang.IllegalStateException - after close has been called on this pool.java.lang.Exception - when PooledObjectFactory.makeObject() throws an
exception.java.util.NoSuchElementException - when the pool is exhausted and cannot or will not return
another instance.public T borrowObject(java.time.Duration borrowMaxWaitDuration) throws java.lang.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.
borrowMaxWaitDuration - The time to wait for an object
to become availablejava.util.NoSuchElementException - if an instance cannot be returnedjava.lang.Exception - if an object instance cannot be returned due to an
errorpublic T borrowObject(long borrowMaxWaitMillis) throws java.lang.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 availablejava.util.NoSuchElementException - if an instance cannot be returnedjava.lang.Exception - if an object instance cannot be returned due to an
errorpublic void clear()
PooledObjectFactory.destroyObject(PooledObject) method on each
idle instance.
Implementation notes:
SwallowedExceptionListener.clear in interface ObjectPool<T>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().
close in interface java.io.Closeableclose in interface java.lang.AutoCloseableclose in interface ObjectPool<T>close in class BaseGenericObjectPool<T>public void evict()
throws java.lang.Exception
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.
Successive activations of this method examine objects in sequence, cycling through objects in oldest-to-youngest order.
evict in class BaseGenericObjectPool<T>java.lang.Exception - when there is a problem evicting idle objects.public PooledObjectFactory<T> getFactory()
public java.lang.String getFactoryType()
getFactoryType in interface GenericObjectPoolMXBeanpublic int getMaxIdle()
getMaxIdle in interface GenericObjectPoolMXBeansetMaxIdle(int)public int getMinIdle()
BaseGenericObjectPool.getDurationBetweenEvictionRuns() 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 GenericObjectPoolMXBeansetMinIdle(int),
setMaxIdle(int),
BaseGenericObjectPool.setTimeBetweenEvictionRuns(Duration)public int getNumActive()
ObjectPoolgetNumActive in interface GenericObjectPoolMXBeangetNumActive in interface ObjectPool<T>public int getNumIdle()
BaseGenericObjectPoolgetNumIdle in interface GenericObjectPoolMXBeangetNumIdle in interface ObjectPool<T>getNumIdle in class BaseGenericObjectPool<T>public int getNumWaiters()
getNumWaiters in interface GenericObjectPoolMXBeanpublic void invalidateObject(T obj) throws java.lang.Exception
By contract, obj must have been obtained
using ObjectPool.borrowObject() or a related method as defined in an
implementation or sub-interface.
This method should be used when an object that has been borrowed is determined (due to an exception or other problem) to be invalid.
Activation of this method decrements the active count and attempts to
destroy the instance, using the default (NORMAL) DestroyMode.
invalidateObject in interface ObjectPool<T>obj - a borrowed instance to be disposed.java.lang.Exception - if an exception occurs destroying the
objectjava.lang.IllegalStateException - if obj does not belong to this poolpublic void invalidateObject(T obj, DestroyMode destroyMode) throws java.lang.Exception
DestroyMode
By contract, obj must have been obtained
using ObjectPool.borrowObject() or a related method as defined in an
implementation or sub-interface.
This method should be used when an object that has been borrowed is determined (due to an exception or other problem) to be invalid.
Activation of this method decrements the active count and attempts to
destroy the instance, using the provided DestroyMode.
invalidateObject in interface ObjectPool<T>obj - a borrowed instance to be disposed.destroyMode - destroy activation context provided to the factoryjava.lang.Exception - if an exception occurs destroying the
objectjava.lang.IllegalStateException - if obj does not belong to this poolpublic java.util.Set<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 GenericObjectPoolMXBeanpublic void preparePool()
throws java.lang.Exception
getMinIdle() idle instances are available
in the pool.java.lang.Exception - If the associated factory throws an exceptionpublic void returnObject(T obj)
obj
must have been obtained using ObjectPool.borrowObject() or
a related method as defined in an implementation or sub-interface.
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 ObjectPool<T>obj - a borrowed instance to be returned.public void setConfig(GenericObjectPoolConfig<T> conf)
conf - the new configuration to use. This is used by value.GenericObjectPoolConfigpublic 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.getDurationBetweenEvictionRuns() 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.getDurationBetweenEvictionRuns()protected void toStringAppendFields(java.lang.StringBuilder builder)
BaseObjectBaseObject.toString() output.toStringAppendFields in class BaseGenericObjectPool<T>builder - Field names and values are appended to this objectpublic void use(T pooledObject)
UsageTrackinguse in interface UsageTracking<T>pooledObject - The object that is being used.Copyright © 2000-2023 Apache Software Foundation. All Rights Reserved.