Class GenericObjectPool<T>
- Type Parameters:
T
- Type of element pooled in this pool.
- All Implemented Interfaces:
Closeable
,AutoCloseable
,GenericObjectPoolMXBean
,ObjectPool<T>
,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.
- Since:
- 2.0
- See Also:
-
Field Summary
Fields inherited from class org.apache.tomcat.dbcp.pool2.impl.BaseGenericObjectPool
MEAN_TIMING_STATS_CACHE_SIZE
-
Constructor Summary
ConstructorDescriptionGenericObjectPool
(PooledObjectFactory<T> factory) Creates a newGenericObjectPool
using defaults fromGenericObjectPoolConfig
.GenericObjectPool
(PooledObjectFactory<T> factory, GenericObjectPoolConfig<T> config) Creates a newGenericObjectPool
using a specific configuration.GenericObjectPool
(PooledObjectFactory<T> factory, GenericObjectPoolConfig<T> config, AbandonedConfig abandonedConfig) Creates a newGenericObjectPool
that tracks and destroys objects that are checked out, but never returned to the pool. -
Method Summary
Modifier and TypeMethodDescriptionvoid
Creates an object, and place it into the pool. addObject() is useful for "pre-loading" a pool with idle objects.void
addObjects
(int count) CallsObjectPool.addObject()
count
number of times.Equivalent to
.borrowObject
(BaseGenericObjectPool.getMaxWaitMillis()
)borrowObject
(long borrowMaxWaitMillis) Borrows an object from the pool using the specific waiting time which only applies ifBaseGenericObjectPool.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 configuredPooledObjectFactory.destroyObject(PooledObject)
method on each idle instance.void
close()
Closes the pool.void
evict()
PerformnumTests
idle object eviction tests, evicting examined objects that meet the criteria for eviction.Obtains a reference to the factory used to create, destroy and validate the objects used by this pool.Returns the type - including the specific type rather than the generic - of the factory.boolean
Gets whether this pool identifies and logs any abandoned objects.int
Returns the cap on the number of "idle" instances in the pool.int
Returns the target for the minimum number of idle objects to maintain in the pool.int
Returns the number of instances currently borrowed from this pool.int
The number of instances currently idle in this pool.int
Returns an estimate of the number of threads currently blocked waiting for an object from the pool.boolean
Gets whether a check is made for abandoned objects when an object is borrowed from this pool.boolean
Gets whether a check is made for abandoned objects when the evictor runs.int
Obtains the timeout before which an object will be considered to be abandoned by this pool.void
invalidateObject
(T obj) Invalidates an object from the pool.void
invalidateObject
(T obj, DestroyMode mode) Invalidates an object from the pool, using the providedDestroyMode
boolean
Gets whether or not abandoned object removal is configured for this pool.Provides information on all the objects in the pool, both idle (waiting to be borrowed) and active (currently borrowed).void
Tries to ensure thatgetMinIdle()
idle instances are available in the pool.void
returnObject
(T obj) Returns an instance to the pool.void
setAbandonedConfig
(AbandonedConfig abandonedConfig) Sets the abandoned object removal configuration.void
setConfig
(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) Used by sub-classes to include the fields defined by the sub-class in theBaseObject.toString()
output.void
This method is called every time a pooled object is used to enable the pool to better track borrowed objects.Methods inherited from class org.apache.tomcat.dbcp.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.tomcat.dbcp.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.tomcat.dbcp.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 Details
-
GenericObjectPool
Creates a newGenericObjectPool
using defaults fromGenericObjectPoolConfig
.- Parameters:
factory
- The object factory to be used to create object instances used by this pool
-
GenericObjectPool
Creates a newGenericObjectPool
using a specific configuration.- Parameters:
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.
-
GenericObjectPool
public GenericObjectPool(PooledObjectFactory<T> factory, GenericObjectPoolConfig<T> config, AbandonedConfig abandonedConfig) Creates a newGenericObjectPool
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 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.
-
-
Method Details
-
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 interfaceGenericObjectPoolMXBean
- 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
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:
-
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 andBaseGenericObjectPool.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
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 andBaseGenericObjectPool.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 interfaceGenericObjectPoolMXBean
- Returns:
- The minimum number of objects.
- See Also:
-
isAbandonedConfig
public boolean isAbandonedConfig()Gets whether or not abandoned object removal is configured for this pool.- Specified by:
isAbandonedConfig
in interfaceGenericObjectPoolMXBean
- 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 interfaceGenericObjectPoolMXBean
- Returns:
true
if abandoned object removal is configured for this pool and removal events are to be logged otherwisefalse
- See Also:
-
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 interfaceGenericObjectPoolMXBean
- Returns:
true
if abandoned object removal is configured to be activated by borrowObject otherwisefalse
- See Also:
-
getRemoveAbandonedOnMaintenance
public boolean getRemoveAbandonedOnMaintenance()Gets whether a check is made for abandoned objects when the evictor runs.- Specified by:
getRemoveAbandonedOnMaintenance
in interfaceGenericObjectPoolMXBean
- Returns:
true
if abandoned object removal is configured to be activated when the evictor runs otherwisefalse
- See Also:
-
getRemoveAbandonedTimeout
public int getRemoveAbandonedTimeout()Obtains the timeout before which an object will be considered to be abandoned by this pool.- Specified by:
getRemoveAbandonedTimeout
in interfaceGenericObjectPoolMXBean
- Returns:
- The abandoned object timeout in seconds if abandoned object removal is configured for this pool; Integer.MAX_VALUE otherwise.
- See Also:
-
setConfig
Sets the base pool configuration.- Parameters:
conf
- the new configuration to use. This is used by value.- See Also:
-
setAbandonedConfig
Sets the abandoned object removal configuration.- Parameters:
abandonedConfig
- the new configuration to use. This is used by value.- See Also:
-
getFactory
Obtains a reference to the factory used to create, destroy and validate the objects used by this pool.- Returns:
- the factory
-
borrowObject
Equivalent to
.borrowObject
(BaseGenericObjectPool.getMaxWaitMillis()
)Obtains an instance from this pool.
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 withPooledObjectFactory.activateObject(org.apache.tomcat.dbcp.pool2.PooledObject<T>)
and then validated withPooledObjectFactory.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).
- Specified by:
borrowObject
in interfaceObjectPool<T>
- Returns:
- an instance from this pool.
- Throws:
IllegalStateException
- afterclose
has been called on this pool.Exception
- whenPooledObjectFactory.makeObject()
throws an exception.NoSuchElementException
- when the pool is exhausted and cannot or will not return another instance.
-
borrowObject
Borrows an object from the pool using the specific waiting time which only applies ifBaseGenericObjectPool.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, ortestOnBorrow
is set totrue
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 theborrowMaxWaitMillis
parameter. If the number of instances checked out from the pool is less thanmaxTotal,
a new instance is created, activated and (if applicable) validated and returned to the caller. If validation fails, aNoSuchElementException
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 aNoSuchElementException
(ifBaseGenericObjectPool.getBlockWhenExhausted()
is false). The length of time that this method will block whenBaseGenericObjectPool.getBlockWhenExhausted()
is true is determined by the value passed in to theborrowMaxWaitMillis
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 returnedException
- if an object instance cannot be returned due to an error
-
returnObject
Returns an instance to the pool. By contract,obj
must have been obtained usingObjectPool.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
.- Specified by:
returnObject
in interfaceObjectPool<T>
- Parameters:
obj
- aborrowed
instance to be returned.
-
invalidateObject
Invalidates an object from the pool.By contract,
obj
must have been obtained usingObjectPool.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
.- Specified by:
invalidateObject
in interfaceObjectPool<T>
- Parameters:
obj
- aborrowed
instance to be disposed.- Throws:
Exception
- if an exception occurs destroying the objectIllegalStateException
- if obj does not belong to this pool
-
invalidateObject
Invalidates an object from the pool, using the providedDestroyMode
By contract,
obj
must have been obtained usingObjectPool.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
.- Specified by:
invalidateObject
in interfaceObjectPool<T>
- Parameters:
obj
- aborrowed
instance to be disposed.mode
- destroy activation context provided to the factory- Throws:
Exception
- if an exception occurs destroying the objectIllegalStateException
- 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 configuredPooledObjectFactory.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 interfaceObjectPool<T>
-
getNumActive
public int getNumActive()Description copied from interface:ObjectPool
Returns the number of instances currently borrowed from this pool. Returns a negative value if this information is not available.- Specified by:
getNumActive
in interfaceGenericObjectPoolMXBean
- Specified by:
getNumActive
in interfaceObjectPool<T>
- Returns:
- the number of instances currently borrowed from this pool.
-
getNumIdle
public int getNumIdle()Description copied from class:BaseGenericObjectPool
The number of instances currently idle in this pool.- Specified by:
getNumIdle
in interfaceGenericObjectPoolMXBean
- Specified by:
getNumIdle
in interfaceObjectPool<T>
- Specified by:
getNumIdle
in classBaseGenericObjectPool<T>
- Returns:
- count of instances available for checkout from the pool
-
close
public void close()Closes the pool. Once the pool is closed,borrowObject()
will fail with IllegalStateException, butreturnObject(Object)
andinvalidateObject(Object)
will continue to work, with returned objects destroyed on return.Destroys idle instances in the pool by invoking
clear()
.- Specified by:
close
in interfaceAutoCloseable
- Specified by:
close
in interfaceCloseable
- Specified by:
close
in interfaceObjectPool<T>
- Specified by:
close
in classBaseGenericObjectPool<T>
-
evict
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.Successive activations of this method examine objects in sequence, cycling through objects in oldest-to-youngest order.
- Specified by:
evict
in classBaseGenericObjectPool<T>
- Throws:
Exception
- when there is a problem evicting idle objects.
-
preparePool
Tries to ensure thatgetMinIdle()
idle instances are available in the pool.- Throws:
Exception
- If the associated factory throws an exception- Since:
- 2.4
-
addObject
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 interfaceObjectPool<T>
- Throws:
Exception
- whenPooledObjectFactory.makeObject()
fails.IllegalStateException
- afterObjectPool.close()
has been called on this pool.UnsupportedOperationException
- when this pool cannot add new idle objects.
-
addObjects
CallsObjectPool.addObject()
count
number of times.- Specified by:
addObjects
in interfaceObjectPool<T>
- Parameters:
count
- the number of idle objects to add.- Throws:
Exception
- whenObjectPool.addObject()
fails.- Since:
- 2.8.0
-
use
Description copied from interface:UsageTracking
This method is called every time a pooled object is used to enable the pool to better track borrowed objects.- Specified by:
use
in interfaceUsageTracking<T>
- Parameters:
pooledObject
- The object that is being used
-
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 interfaceGenericObjectPoolMXBean
- Returns:
- The estimate of the number of threads currently blocked waiting for an object from the pool
-
getFactoryType
Returns the type - including the specific type rather than the generic - of the factory.- Specified by:
getFactoryType
in interfaceGenericObjectPoolMXBean
- Returns:
- A string representation of the factory type
-
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 interfaceGenericObjectPoolMXBean
- Returns:
- Information grouped on all the objects in the pool
-
toStringAppendFields
Description copied from class:BaseObject
Used by sub-classes to include the fields defined by the sub-class in theBaseObject.toString()
output.- Overrides:
toStringAppendFields
in classBaseGenericObjectPool<T>
- Parameters:
builder
- Field names and values are appended to this object
-