Apache Commons Pool 2.12.0 · org.apache.commons.pool2.impl.GenericObjectPool

Modifier and Type	Field and Description
private final ConcurrentHashMap<BaseGenericObjectPool.IdentityWrapper<T>, PooledObject<T>>	allObjects
private final AtomicLong	createCount
private final PooledObjectFactory<T>	factory
private volatile String	factoryType
private final LinkedBlockingDeque<PooledObject<T>>	idleObjects
private long	makeObjectCount
private final Object	makeObjectCountLock
private volatile int	maxIdle
private volatile int	minIdle
private static final String	ONAME_BASE

Access	Constructor and Description
public	GenericObjectPool(final PooledObjectFactory<T> The object factory to be used to create object instances used by this pool factory) Creates a new `GenericObjectPool` using defaults from `GenericObjectPoolConfig`.
public	GenericObjectPool(final PooledObjectFactory<T> The object factory to be used to create object instances used by this pool factory, final GenericObjectPoolConfig<T> 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. config) Creates a new `GenericObjectPool` using a specific configuration.
public	GenericObjectPool(final PooledObjectFactory<T> The object factory to be used to create object instances used by this pool factory, final GenericObjectPoolConfig<T> 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. config, final AbandonedConfig Configuration for abandoned object identification and removal. The configuration is used by value. 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
private void	addIdleObject(final PooledObject<T> The object to make idle p) Adds the provided wrapped pooled object to the set of idle objects for this pool.
public void	addObject() Implements org.apache.commons.pool2.ObjectPool.addObject. Creates an object, and place it into the pool.
public T	borrowObject() Implements org.apache.commons.pool2.ObjectPool.borrowObject. Equivalent to `borrowObject(getMaxWaitDuration())`.
public T	Returns: object instance from the pool borrowObject(final Duration The time to wait for an object to become available borrowMaxWaitDuration) Borrows an object from the pool using the specific waiting time which only applies if `getBlockWhenExhausted()` is true.
public T	Returns: object instance from the pool borrowObject(final long The time to wait in milliseconds for an object to become available borrowMaxWaitMillis) Borrows an object from the pool using the specific waiting time which only applies if `getBlockWhenExhausted()` is true.
public void	clear() Implements org.apache.commons.pool2.ObjectPool.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.
public void	close() Implements abstract org.apache.commons.pool2.impl.BaseGenericObjectPool.close. Implements org.apache.commons.pool2.ObjectPool.close, java.lang.AutoCloseable.close. Closes the pool.
private PooledObject<T>	Returns: The new wrapped pooled object or null. create() Attempts to create a new wrapped pooled object.
private void	destroy(final PooledObject<T> The wrapped pooled object to destroy toDestroy, final DestroyMode DestroyMode context provided to the factory destroyMode) Destroys a wrapped pooled object.
private void	ensureIdle(final int the number of idle instances desired idleCount, final boolean true means create instances even if the pool has no threads waiting always) Tries to ensure that `idleCount` idle instances exist in the pool.
pack-priv void	ensureMinIdle() Implements abstract org.apache.commons.pool2.impl.BaseGenericObjectPool.ensureMinIdle. Tries to ensure that the configured minimum number of idle instances are available in the pool.
public void	evict() Implements abstract org.apache.commons.pool2.impl.BaseGenericObjectPool.evict. Perform `numTests` idle object eviction tests, evicting examined objects that meet the criteria for eviction.
public PooledObjectFactory<T>	Returns: the factory getFactory() Gets a reference to the factory used to create, destroy and validate the objects used by this pool.
public String	Returns: A string representation of the factory type getFactoryType() Implements org.apache.commons.pool2.impl.GenericObjectPoolMXBean.getFactoryType. Gets the type - including the specific type rather than the generic - of the factory.
public int	Returns: the maximum number of "idle" instances that can be held in the pool or a negative value if there is no limit getMaxIdle() Implements org.apache.commons.pool2.impl.GenericObjectPoolMXBean.getMaxIdle. Gets the cap on the number of "idle" instances in the pool.
public int	Returns: The minimum number of objects. getMinIdle() Implements org.apache.commons.pool2.impl.GenericObjectPoolMXBean.getMinIdle. Gets the target for the minimum number of idle objects to maintain in the pool.
public int	getNumActive() Implements org.apache.commons.pool2.ObjectPool.getNumActive, org.apache.commons.pool2.impl.GenericObjectPoolMXBean.getNumActive. Gets the number of instances currently borrowed from this pool.
public int	getNumIdle() Implements abstract org.apache.commons.pool2.impl.BaseGenericObjectPool.getNumIdle. Implements org.apache.commons.pool2.ObjectPool.getNumIdle, org.apache.commons.pool2.impl.GenericObjectPoolMXBean.getNumIdle. Gets the number of instances currently idle in this pool.
private int	Returns: The number of objects to test for validity getNumTests() Calculates the number of objects to test in a run of the idle object evictor.
public int	Returns: The estimate of the number of threads currently blocked waiting for an object from the pool getNumWaiters() Implements org.apache.commons.pool2.impl.GenericObjectPoolMXBean.getNumWaiters. Gets an estimate of the number of threads currently blocked waiting for an object from the pool.
pack-priv PooledObject<T>	getPooledObject(final T obj)
pack-priv String	getStatsString() Overrides org.apache.commons.pool2.impl.BaseGenericObjectPool.getStatsString. Gets a statistics string.
public void	invalidateObject(final T a `borrowed` instance to be disposed. obj) Implements org.apache.commons.pool2.ObjectPool.invalidateObject. Invalidates an object from the pool.
public void	invalidateObject(final T a `borrowed` instance to be disposed. obj, final DestroyMode destroy activation context provided to the factory destroyMode) Overrides default org.apache.commons.pool2.ObjectPool.invalidateObject. Invalidates an object from the pool, using the provided `DestroyMode` By contract, `obj` must have been obtained using `borrowObject` or a related method as defined in an implementation or sub-interface.
public Set<DefaultPooledObjectInfo>	Returns: Information grouped on all the objects in the pool listAllObjects() Implements org.apache.commons.pool2.impl.GenericObjectPoolMXBean.listAllObjects. Provides information on all the objects in the pool, both idle (waiting to be borrowed) and active (currently borrowed).
public void	preparePool() Tries to ensure that `getMinIdle()` idle instances are available in the pool.
private void	removeAbandoned(final AbandonedConfig The configuration to use to identify abandoned objects abandonedConfig) Recovers abandoned objects which have been checked out but not used since longer than the removeAbandonedTimeout.
public void	returnObject(final T a `borrowed` instance to be returned. obj) Implements org.apache.commons.pool2.ObjectPool.returnObject. Returns an instance to the pool.
public void	setConfig(final GenericObjectPoolConfig<T> the new configuration to use. This is used by value. conf) Sets the base pool configuration.
public void	setMaxIdle(final int The cap on the number of "idle" instances in the pool. Use a negative value to indicate an unlimited number of idle instances maxIdle) Sets the cap on the number of "idle" instances in the pool.
public void	setMinIdle(final int The minimum number of objects. minIdle) Sets the target for the minimum number of idle objects to maintain in the pool.
protected void	toStringAppendFields(final StringBuilder Field names and values are appended to this object builder) Overrides org.apache.commons.pool2.impl.BaseGenericObjectPool.toStringAppendFields. Used by sub-classes to include the fields defined by the sub-class in the `toString()` output.
public void	use(final T The object that is being used. pooledObject) Implements org.apache.commons.pool2.UsageTracking.use. Called every time a pooled object is used to enable the pool to better track borrowed objects.
private static void	wait(final Object obj, final Duration duration)

Inherited from org.apache.commons.pool2.impl.BaseGenericObjectPool:: appendStats assertOpen createRemoveList getBlockWhenExhausted getBorrowedCount getCreatedCount getCreationStackTrace getDestroyedByBorrowValidationCount getDestroyedByEvictorCount getDestroyedCount getDurationBetweenEvictionRuns getEvictionPolicy getEvictionPolicyClassName getEvictorShutdownTimeout getEvictorShutdownTimeoutDuration getEvictorShutdownTimeoutMillis getFairness getJmxName getLifo getLogAbandoned getMaxBorrowWaitDuration getMaxBorrowWaitTimeMillis getMaxTotal getMaxWaitDuration getMaxWaitMillis getMeanActiveDuration getMeanActiveTimeMillis getMeanBorrowWaitDuration getMeanBorrowWaitTimeMillis getMeanIdleDuration getMeanIdleTimeMillis getMessageStatistics getMinEvictableIdleDuration getMinEvictableIdleTime getMinEvictableIdleTimeMillis getNumTestsPerEvictionRun getRemoveAbandonedOnBorrow getRemoveAbandonedOnMaintenance getRemoveAbandonedTimeout getRemoveAbandonedTimeoutDuration getReturnedCount getSoftMinEvictableIdleDuration getSoftMinEvictableIdleTime getSoftMinEvictableIdleTimeMillis getSwallowedExceptionListener getTestOnBorrow getTestOnCreate getTestOnReturn getTestWhileIdle getTimeBetweenEvictionRuns getTimeBetweenEvictionRunsMillis isAbandonedConfig isClosed jmxUnregister markReturningState setAbandonedConfig setBlockWhenExhausted setConfig setDurationBetweenEvictionRuns setEvictionPolicy setEvictionPolicyClassName setEvictionPolicyClassName setEvictorShutdownTimeout setEvictorShutdownTimeoutMillis setLifo setMaxTotal setMaxWait setMaxWaitMillis setMessagesStatistics setMinEvictableIdle setMinEvictableIdleDuration setMinEvictableIdleTime setMinEvictableIdleTimeMillis setNumTestsPerEvictionRun setSoftMinEvictableIdle setSoftMinEvictableIdleDuration setSoftMinEvictableIdleTime setSoftMinEvictableIdleTimeMillis setSwallowedExceptionListener setTestOnBorrow setTestOnCreate setTestOnReturn setTestWhileIdle setTimeBetweenEvictionRuns setTimeBetweenEvictionRunsMillis startEvictor stopEvictor swallowException updateStatsBorrow updateStatsReturn

allObjects	back to summary
private final ConcurrentHashMap<BaseGenericObjectPool.IdentityWrapper<T>, PooledObject<T>> allObjects

createCount	back to summary
private final AtomicLong createCount

factory	back to summary
private final PooledObjectFactory<T> factory

factoryType	back to summary
private volatile String factoryType

idleObjects	back to summary
private final LinkedBlockingDeque<PooledObject<T>> idleObjects

makeObjectCount	back to summary
private long makeObjectCount

makeObjectCountLock	back to summary
private final Object makeObjectCountLock

maxIdle	back to summary
private volatile int maxIdle

minIdle	back to summary
private volatile int minIdle

ONAME_BASE	back to summary
private static final String ONAME_BASE

GenericObjectPool	back to summary
public GenericObjectPool(final PooledObjectFactory<T> factory) Creates a new `GenericObjectPool` using defaults from `GenericObjectPoolConfig`. Parameters factory:PooledObjectFactory<T> The object factory to be used to create object instances used by this pool

GenericObjectPool	back to summary
public GenericObjectPool(final PooledObjectFactory<T> factory, final GenericObjectPoolConfig<T> config) Creates a new `GenericObjectPool` using a specific configuration. Parameters factory:PooledObjectFactory<T> The object factory to be used to create object instances used by this pool config:GenericObjectPoolConfig<T> 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	back to summary
public GenericObjectPool(final PooledObjectFactory<T> factory, final GenericObjectPoolConfig<T> config, final AbandonedConfig abandonedConfig) Creates a new `GenericObjectPool` that tracks and destroys objects that are checked out, but never returned to the pool. Parameters factory:PooledObjectFactory<T> The object factory to be used to create object instances used by this pool config:GenericObjectPoolConfig<T> 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:AbandonedConfig Configuration for abandoned object identification and removal. The configuration is used by value.

Method Detail

addIdleObject back to summary

addIdleObject	back to summary
private void addIdleObject(final PooledObject<T> p) throws Exception Adds the provided wrapped pooled object to the set of idle objects for this pool. The object must already be part of the pool. If `p` is null, this is a no-op (no exception, but no impact on the pool). Parameters p:PooledObject<T> The object to make idle Exceptions Exception: If the factory fails to passivate the object

private void addIdleObject(final PooledObject<T> p) throws Exception

Adds the provided wrapped pooled object to the set of idle objects for this pool. The object must already be part of the pool. If p is null, this is a no-op (no exception, but no impact on the pool).

Parameters

p:PooledObject<T>: The object to make idle

Exceptions

Exception:: If the factory fails to passivate the object

addObject back to summary

addObject	back to summary
public void addObject() throws Exception Implements org.apache.commons.pool2.ObjectPool.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). If the factory returns null when creating an object, a `NullPointerException` is thrown. If there is no factory set (factory == null), an `IllegalStateException` is thrown. Annotations @Override Exceptions Exception: Doc from org.apache.commons.pool2.ObjectPool.addObject. when `PooledObjectFactory#makeObject` fails.

public void addObject() throws Exception

Implements org.apache.commons.pool2.ObjectPool.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).

If the factory returns null when creating an object, a NullPointerException is thrown. If there is no factory set (factory == null), an IllegalStateException is thrown.

Annotations

@Override

Exceptions

Exception:

Doc from org.apache.commons.pool2.ObjectPool.addObject.

when PooledObjectFactory#makeObject fails.

borrowObject back to summary

borrowObject	back to summary
public T borrowObject() throws Exception Implements org.apache.commons.pool2.ObjectPool.borrowObject. Doc from org.apache.commons.pool2.ObjectPool.borrowObject. Equivalent to `borrowObject(getMaxWaitDuration())`. Borrows 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 with `PooledObjectFactory#activateObject` and then validated with `PooledObjectFactory#validateObject`. By contract, clients must return the borrowed instance using `returnObject`, `invalidateObject`, 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). Returns:T an instance from this pool. Annotations @Override Exceptions Exception: when `PooledObjectFactory#makeObject` throws an exception.

public T borrowObject() throws Exception

Implements org.apache.commons.pool2.ObjectPool.borrowObject.

Doc from org.apache.commons.pool2.ObjectPool.borrowObject.

Equivalent to borrowObject(getMaxWaitDuration()). Borrows 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 with PooledObjectFactory#activateObject and then validated with PooledObjectFactory#validateObject.

By contract, clients must return the borrowed instance using returnObject, invalidateObject, 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).

Returns:T

an instance from this pool.

Annotations

@Override

Exceptions

Exception:: when PooledObjectFactory#makeObject throws an exception.

borrowObject back to summary

borrowObject	back to summary
public T borrowObject(final Duration borrowMaxWaitDuration) throws Exception Borrows an object from the pool using the specific waiting time which only applies if `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 `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) `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 factory returns null when creating an instance, a `NullPointerException` is thrown. If the pool is exhausted (no available idle instances and no capacity to create new ones), this method will either block (if `getBlockWhenExhausted()` is true) or throw a `NoSuchElementException` (if `getBlockWhenExhausted()` is false). The length of time that this method will block when `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 borrowMaxWaitDuration:Duration The time to wait for an object to become available Returns:T object instance from the pool Exceptions Exception: if an object instance cannot be returned due to an error NoSuchElementException: if an instance cannot be returned Since 2.10.0

public T borrowObject(final Duration borrowMaxWaitDuration) throws Exception

Borrows an object from the pool using the specific waiting time which only applies if 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 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) 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 factory returns null when creating an instance, a NullPointerException is thrown.

If the pool is exhausted (no available idle instances and no capacity to create new ones), this method will either block (if getBlockWhenExhausted() is true) or throw a NoSuchElementException (if getBlockWhenExhausted() is false). The length of time that this method will block when 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

borrowMaxWaitDuration:Duration: The time to wait for an object to become available

Returns:T

object instance from the pool

Exceptions

Exception:: if an object instance cannot be returned due to an error
NoSuchElementException:: if an instance cannot be returned

Since

2.10.0

borrowObject back to summary

borrowObject	back to summary
public T borrowObject(final long borrowMaxWaitMillis) throws Exception Borrows an object from the pool using the specific waiting time which only applies if `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 `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) `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 factory returns null when creating an instance, a `NullPointerException` is thrown. If the pool is exhausted (no available idle instances and no capacity to create new ones), this method will either block (if `getBlockWhenExhausted()` is true) or throw a `NoSuchElementException` (if `getBlockWhenExhausted()` is false). The length of time that this method will block when `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:long The time to wait in milliseconds for an object to become available Returns:T object instance from the pool Exceptions Exception: if an object instance cannot be returned due to an error NoSuchElementException: if an instance cannot be returned

public T borrowObject(final long borrowMaxWaitMillis) throws Exception

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

Parameters

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

Returns:T

object instance from the pool

Exceptions

Exception:: if an object instance cannot be returned due to an error
NoSuchElementException:: if an instance cannot be returned

clear back to summary

clear	back to summary
public void clear() Implements org.apache.commons.pool2.ObjectPool.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`. Annotations @Override

public void clear()

Implements org.apache.commons.pool2.ObjectPool.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.

Annotations

@Override

close back to summary

close	back to summary
public void close() Implements abstract org.apache.commons.pool2.impl.BaseGenericObjectPool.close. Implements org.apache.commons.pool2.ObjectPool.close, java.lang.AutoCloseable.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()`. Annotations @Override

public void close()

Implements abstract org.apache.commons.pool2.impl.BaseGenericObjectPool.close.

Implements org.apache.commons.pool2.ObjectPool.close, java.lang.AutoCloseable.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().

Annotations

@Override

create back to summary

create	back to summary
private PooledObject<T> create() throws Exception Attempts to create a new wrapped pooled object. If there are `getMaxTotal()` objects already in circulation or in process of being created, this method returns null. If the factory makeObject returns null, this method throws a NullPointerException. Returns:PooledObject<T> The new wrapped pooled object or null. Exceptions Exception: if the object factory's `makeObject` fails

private PooledObject<T> create() throws Exception

Attempts to create a new wrapped pooled object.

If there are getMaxTotal() objects already in circulation or in process of being created, this method returns null.

If the factory makeObject returns null, this method throws a NullPointerException.

Returns:PooledObject<T>

The new wrapped pooled object or null.

Exceptions

Exception:: if the object factory's makeObject fails

destroy	back to summary
private void destroy(final PooledObject<T> toDestroy, final DestroyMode destroyMode) throws Exception Destroys a wrapped pooled object. Parameters toDestroy:PooledObject<T> The wrapped pooled object to destroy destroyMode:DestroyMode DestroyMode context provided to the factory Exceptions Exception: If the factory fails to destroy the pooled object cleanly

destroy

back to summary

private void destroy(final PooledObject<T> toDestroy, final DestroyMode destroyMode) throws Exception

Destroys a wrapped pooled object.

Parameters

toDestroy:PooledObject<T>: The wrapped pooled object to destroy
destroyMode:DestroyMode: DestroyMode context provided to the factory

Exceptions

Exception:: If the factory fails to destroy the pooled object cleanly

ensureIdle back to summary

ensureIdle	back to summary
private void ensureIdle(final int idleCount, final boolean always) throws Exception Tries to ensure that `idleCount` idle instances exist in the pool. Creates and adds idle instances until either `getNumIdle()` reaches `idleCount` or the total number of objects (idle, checked out, or being created) reaches `getMaxTotal()`. If `always` is false, no instances are created unless there are threads waiting to check out instances from the pool. If the factory returns null when creating an instance, a `NullPointerException` is thrown. Parameters idleCount:int the number of idle instances desired always:boolean true means create instances even if the pool has no threads waiting Exceptions Exception: if the factory's makeObject throws

private void ensureIdle(final int idleCount, final boolean always) throws Exception

Tries to ensure that idleCount idle instances exist in the pool.

Creates and adds idle instances until either getNumIdle() reaches idleCount or the total number of objects (idle, checked out, or being created) reaches getMaxTotal(). If always is false, no instances are created unless there are threads waiting to check out instances from the pool.

If the factory returns null when creating an instance, a NullPointerException is thrown.

Parameters

idleCount:int: the number of idle instances desired
always:boolean: true means create instances even if the pool has no threads waiting

Exceptions

Exception:: if the factory's makeObject throws

ensureMinIdle	back to summary
pack-priv void ensureMinIdle() throws Exception Implements abstract org.apache.commons.pool2.impl.BaseGenericObjectPool.ensureMinIdle. Doc from org.apache.commons.pool2.impl.BaseGenericObjectPool.ensureMinIdle. Tries to ensure that the configured minimum number of idle instances are available in the pool. Annotations @Override Exceptions Exception: if an error occurs creating idle instances

ensureMinIdle

back to summary

pack-priv void ensureMinIdle() throws Exception

Implements abstract org.apache.commons.pool2.impl.BaseGenericObjectPool.ensureMinIdle.

Doc from org.apache.commons.pool2.impl.BaseGenericObjectPool.ensureMinIdle.

Tries to ensure that the configured minimum number of idle instances are available in the pool.

Annotations

@Override

Exceptions

Exception:: if an error occurs creating idle instances

evict back to summary

evict	back to summary
public void evict() throws Exception Implements abstract org.apache.commons.pool2.impl.BaseGenericObjectPool.evict. Doc from org.apache.commons.pool2.impl.BaseGenericObjectPool.evict. 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. Successive activations of this method examine objects in sequence, cycling through objects in oldest-to-youngest order. Annotations @Override Exceptions Exception: when there is a problem evicting idle objects.

public void evict() throws Exception

Implements abstract org.apache.commons.pool2.impl.BaseGenericObjectPool.evict.

Doc from org.apache.commons.pool2.impl.BaseGenericObjectPool.evict.

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.

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

Annotations

@Override

Exceptions

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

getFactory	back to summary
public PooledObjectFactory<T> getFactory() Gets a reference to the factory used to create, destroy and validate the objects used by this pool. Returns:PooledObjectFactory<T> the factory

getFactory

back to summary

public PooledObjectFactory<T> getFactory()

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

Returns:PooledObjectFactory<T>: the factory

getFactoryType	back to summary
public String getFactoryType() Implements org.apache.commons.pool2.impl.GenericObjectPoolMXBean.getFactoryType. Gets the type - including the specific type rather than the generic - of the factory. Returns:String A string representation of the factory type Annotations @Override

getFactoryType

back to summary

public String getFactoryType()

Implements org.apache.commons.pool2.impl.GenericObjectPoolMXBean.getFactoryType.

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

Returns:String

A string representation of the factory type

Annotations

@Override

getMaxIdle back to summary

getMaxIdle	back to summary
public int getMaxIdle() Implements org.apache.commons.pool2.impl.GenericObjectPoolMXBean.getMaxIdle. Gets 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. Returns:int the maximum number of "idle" instances that can be held in the pool or a negative value if there is no limit Annotations @Override See Also `setMaxIdle`

public int getMaxIdle()

Implements org.apache.commons.pool2.impl.GenericObjectPoolMXBean.getMaxIdle.

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

Returns:int

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

Annotations

@Override

See Also

setMaxIdle

getMinIdle back to summary

getMinIdle	back to summary
public int getMinIdle() Implements org.apache.commons.pool2.impl.GenericObjectPoolMXBean.getMinIdle. Gets 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 `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. Returns:int The minimum number of objects. Annotations @Override See Also `setMinIdle(int)`, `setMaxIdle(int)`, `setDurationBetweenEvictionRuns(Duration)`

public int getMinIdle()

Implements org.apache.commons.pool2.impl.GenericObjectPoolMXBean.getMinIdle.

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

Returns:int

The minimum number of objects.

Annotations

@Override

getNumActive	back to summary
public int getNumActive() Implements org.apache.commons.pool2.ObjectPool.getNumActive, org.apache.commons.pool2.impl.GenericObjectPoolMXBean.getNumActive. Doc from org.apache.commons.pool2.ObjectPool.getNumActive. Gets the number of instances currently borrowed from this pool. Returns a negative value if this information is not available. Returns:int the number of instances currently borrowed from this pool. Annotations @Override

getNumActive

back to summary

public int getNumActive()

Implements org.apache.commons.pool2.ObjectPool.getNumActive, org.apache.commons.pool2.impl.GenericObjectPoolMXBean.getNumActive.

Doc from org.apache.commons.pool2.ObjectPool.getNumActive.

Gets the number of instances currently borrowed from this pool. Returns a negative value if this information is not available.

Returns:int

the number of instances currently borrowed from this pool.

Annotations

@Override

getNumIdle back to summary

getNumIdle	back to summary
public int getNumIdle() Implements abstract org.apache.commons.pool2.impl.BaseGenericObjectPool.getNumIdle. Implements org.apache.commons.pool2.ObjectPool.getNumIdle, org.apache.commons.pool2.impl.GenericObjectPoolMXBean.getNumIdle. Doc from org.apache.commons.pool2.ObjectPool.getNumIdle. Gets the number of instances currently idle in this pool. This may be considered an approximation of the number of objects that can be `borrowed` without creating any new instances. Returns a negative value if this information is not available. Returns:int the number of instances currently idle in this pool. Annotations @Override

public int getNumIdle()

Implements abstract org.apache.commons.pool2.impl.BaseGenericObjectPool.getNumIdle.

Implements org.apache.commons.pool2.ObjectPool.getNumIdle, org.apache.commons.pool2.impl.GenericObjectPoolMXBean.getNumIdle.

Doc from org.apache.commons.pool2.ObjectPool.getNumIdle.

Gets the number of instances currently idle in this pool. This may be considered an approximation of the number of objects that can be borrowed without creating any new instances. Returns a negative value if this information is not available.

Returns:int

the number of instances currently idle in this pool.

Annotations

@Override

getNumTests	back to summary
private int getNumTests() Calculates the number of objects to test in a run of the idle object evictor. Returns:int The number of objects to test for validity

getNumTests

back to summary

private int getNumTests()

Calculates the number of objects to test in a run of the idle object evictor.

Returns:int: The number of objects to test for validity

getNumWaiters	back to summary
public int getNumWaiters() Implements org.apache.commons.pool2.impl.GenericObjectPoolMXBean.getNumWaiters. Gets 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. Returns:int The estimate of the number of threads currently blocked waiting for an object from the pool Annotations @Override

getNumWaiters

back to summary

public int getNumWaiters()

Implements org.apache.commons.pool2.impl.GenericObjectPoolMXBean.getNumWaiters.

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

Returns:int

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

Annotations

@Override

getPooledObject	back to summary
pack-priv PooledObject<T> getPooledObject(final T obj)

getStatsString	back to summary
pack-priv String getStatsString() Overrides org.apache.commons.pool2.impl.BaseGenericObjectPool.getStatsString. Doc from org.apache.commons.pool2.impl.BaseGenericObjectPool.getStatsString. Gets a statistics string. Returns:String a statistics string. Annotations @Override

getStatsString

back to summary

pack-priv String getStatsString()

Overrides org.apache.commons.pool2.impl.BaseGenericObjectPool.getStatsString.

Doc from org.apache.commons.pool2.impl.BaseGenericObjectPool.getStatsString.

Gets a statistics string.

Returns:String

a statistics string.

Annotations

@Override

invalidateObject back to summary

invalidateObject	back to summary
public void invalidateObject(final T obj) throws Exception Implements org.apache.commons.pool2.ObjectPool.invalidateObject. Doc from org.apache.commons.pool2.ObjectPool.invalidateObject. Invalidates an object from the pool. By contract, `obj` must have been obtained using `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`. Parameters obj:T a `borrowed` instance to be disposed. Annotations @Override Exceptions Exception: if an exception occurs destroying the IllegalStateException: if obj does not belong to this pool

public void invalidateObject(final T obj) throws Exception

Implements org.apache.commons.pool2.ObjectPool.invalidateObject.

Doc from org.apache.commons.pool2.ObjectPool.invalidateObject.

Invalidates an object from the pool.

By contract, obj must have been obtained using 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.

Parameters

obj:T: a borrowed instance to be disposed.

Annotations

@Override

Exceptions

Exception:: if an exception occurs destroying the
IllegalStateException:: if obj does not belong to this pool

invalidateObject back to summary

invalidateObject	back to summary
public void invalidateObject(final T obj, final DestroyMode destroyMode) throws Exception Overrides default org.apache.commons.pool2.ObjectPool.invalidateObject. Doc from org.apache.commons.pool2.ObjectPool.invalidateObject. Invalidates an object from the pool, using the provided `DestroyMode` By contract, `obj` must have been obtained using `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`. Parameters obj:T a `borrowed` instance to be disposed. destroyMode:DestroyMode destroy activation context provided to the factory Annotations @Override Exceptions Exception: if an exception occurs destroying the object IllegalStateException: if obj does not belong to this pool Since 2.9.0

public void invalidateObject(final T obj, final DestroyMode destroyMode) throws Exception

Overrides default org.apache.commons.pool2.ObjectPool.invalidateObject.

Doc from org.apache.commons.pool2.ObjectPool.invalidateObject.

Invalidates an object from the pool, using the provided DestroyMode

By contract, obj must have been obtained using 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.

Parameters

obj:T: a borrowed instance to be disposed.
destroyMode:DestroyMode: destroy activation context provided to the factory

Annotations

@Override

Exceptions

Exception:: if an exception occurs destroying the object
IllegalStateException:: if obj does not belong to this pool

Since

2.9.0

listAllObjects	back to summary
public Set<DefaultPooledObjectInfo> listAllObjects() Implements org.apache.commons.pool2.impl.GenericObjectPoolMXBean.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. Returns:Set<DefaultPooledObjectInfo> Information grouped on all the objects in the pool Annotations @Override

listAllObjects

back to summary

public Set<DefaultPooledObjectInfo> listAllObjects()

Implements org.apache.commons.pool2.impl.GenericObjectPoolMXBean.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.

Returns:Set<DefaultPooledObjectInfo>

Information grouped on all the objects in the pool

Annotations

@Override

preparePool back to summary

preparePool	back to summary
public void preparePool() throws Exception Tries to ensure that `getMinIdle()` idle instances are available in the pool. Exceptions Exception: If the associated factory throws an exception Since 2.4

public void preparePool() throws Exception

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

Exceptions

Exception:: If the associated factory throws an exception

Since

2.4

removeAbandoned	back to summary
private void removeAbandoned(final AbandonedConfig abandonedConfig) Recovers abandoned objects which have been checked out but not used since longer than the removeAbandonedTimeout. Parameters abandonedConfig:AbandonedConfig The configuration to use to identify abandoned objects Annotations @SuppressWarnings:resource

removeAbandoned

back to summary

private void removeAbandoned(final AbandonedConfig abandonedConfig)

Recovers abandoned objects which have been checked out but not used since longer than the removeAbandonedTimeout.

Parameters

abandonedConfig:AbandonedConfig: The configuration to use to identify abandoned objects

Annotations

@SuppressWarnings:resource

returnObject back to summary

returnObject	back to summary
public void returnObject(final T obj) Implements org.apache.commons.pool2.ObjectPool.returnObject. Doc from org.apache.commons.pool2.ObjectPool.returnObject. Returns an instance to the pool. By contract, `obj` must have been obtained using `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`. Parameters obj:T a `borrowed` instance to be returned. Annotations @Override

public void returnObject(final T obj)

Implements org.apache.commons.pool2.ObjectPool.returnObject.

Doc from org.apache.commons.pool2.ObjectPool.returnObject.

Returns an instance to the pool. By contract, obj must have been obtained using 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.

Parameters

obj:T: a borrowed instance to be returned.

Annotations

@Override

setConfig back to summary

setConfig	back to summary
public void setConfig(final GenericObjectPoolConfig<T> conf) Sets the base pool configuration. Parameters conf:GenericObjectPoolConfig<T> the new configuration to use. This is used by value. See Also `GenericObjectPoolConfig`

public void setConfig(final GenericObjectPoolConfig<T> conf)

Sets the base pool configuration.

Parameters

conf:GenericObjectPoolConfig<T>: the new configuration to use. This is used by value.

See Also

GenericObjectPoolConfig

setMaxIdle back to summary

setMaxIdle	back to summary
public void setMaxIdle(final int maxIdle) Sets 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:int 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`

public void setMaxIdle(final int maxIdle)

Sets 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:int: 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 back to summary

setMinIdle	back to summary
public void setMinIdle(final 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 `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. Parameters minIdle:int The minimum number of objects. See Also `getMinIdle()`, `getMaxIdle()`, `getDurationBetweenEvictionRuns()`

public void setMinIdle(final 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 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.

Parameters

minIdle:int: The minimum number of objects.

toStringAppendFields back to summary

toStringAppendFields	back to summary
protected void toStringAppendFields(final StringBuilder builder) Overrides org.apache.commons.pool2.impl.BaseGenericObjectPool.toStringAppendFields. Doc from org.apache.commons.pool2.BaseObject.toStringAppendFields. Used by sub-classes to include the fields defined by the sub-class in the `toString()` output. Parameters builder:StringBuilder Field names and values are appended to this object Annotations @Override

protected void toStringAppendFields(final StringBuilder builder)

Overrides org.apache.commons.pool2.impl.BaseGenericObjectPool.toStringAppendFields.

Doc from org.apache.commons.pool2.BaseObject.toStringAppendFields.

Used by sub-classes to include the fields defined by the sub-class in the toString() output.

Parameters

builder:StringBuilder: Field names and values are appended to this object

Annotations

@Override

use	back to summary
public void use(final T pooledObject) Implements org.apache.commons.pool2.UsageTracking.use. Doc from org.apache.commons.pool2.UsageTracking.use. Called every time a pooled object is used to enable the pool to better track borrowed objects. Parameters pooledObject:T The object that is being used. Annotations @Override

use

back to summary

public void use(final T pooledObject)

Implements org.apache.commons.pool2.UsageTracking.use.

Doc from org.apache.commons.pool2.UsageTracking.use.

Called every time a pooled object is used to enable the pool to better track borrowed objects.

Parameters

pooledObject:T: The object that is being used.

Annotations

@Override

wait	back to summary
private static void wait(final Object obj, final Duration duration) throws InterruptedException

public Class GenericObjectPool<T>

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail