Apache Commons Pool 2.13.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 places 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, not null. maxWaitDuration) 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 maxWaitMillis) Deprecated Use `borrowObject(Duration)`. 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(final Duration The time to wait for capacity to create. maxWaitDurationRequest) 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 obj) Implements org.apache.commons.pool2.ObjectPool.invalidateObject. Invalidates an object from the pool.
public void	invalidateObject(final T obj, final DestroyMode 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 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 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 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.

Inherited from org.apache.commons.pool2.impl.BaseGenericObjectPool:: appendStats assertOpen createRemoveList durationSince getBlockWhenExhausted getBorrowedCount getCollectDetailedStatistics 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 setCollectDetailedStatistics 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 wait

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 places 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, or there are already `getMaxIdle()` idle instances in 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 places 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, or there are already getMaxIdle() idle instances in 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). 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).

Annotations

@Override

Exceptions

Exception:: when PooledObjectFactory#makeObject throws an exception.

borrowObject back to summary

borrowObject	back to summary
public T borrowObject(final Duration maxWaitDuration) 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 the `maxWaitDuration` 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 `maxWaitDuration` parameter. Passing a negative duration will cause this method to block indefinitely until an object becomes available. 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 maxWaitDuration:Duration The time to wait for an object to become available, not null. 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 maxWaitDuration) 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 the maxWaitDuration 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 maxWaitDuration parameter. Passing a negative duration will cause this method to block indefinitely until an object becomes available.

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

maxWaitDuration:Duration: The time to wait for an object to become available, not null.

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 maxWaitMillis) throws Exception Deprecated Use `borrowObject(Duration)`. 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 `maxWaitMillis` 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 `maxWaitMillis` parameter. Passing a negative duration will cause this method to block indefinitely until an object becomes available. 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 maxWaitMillis:long The time to wait in milliseconds for an object to become available Returns:T object instance from the pool Annotations @Deprecated 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 maxWaitMillis) throws Exception

Deprecated

Use borrowObject(Duration).

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

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 maxWaitMillis 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 maxWaitMillis parameter. Passing a negative duration will cause this method to block indefinitely until an object becomes available.

Parameters

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

Returns:T

object instance from the pool

Annotations

@Deprecated

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(final Duration maxWaitDurationRequest) 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. Parameters maxWaitDurationRequest:Duration The time to wait for capacity to create. Returns:PooledObject<T> The new wrapped pooled object or null. Exceptions Exception: if the object factory's `makeObject` fails.

private PooledObject<T> create(final Duration maxWaitDurationRequest) 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.

Parameters

maxWaitDurationRequest:Duration: The time to wait for capacity to create.

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

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

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

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

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`. To ensure liveness of the pool, `addObject()` is called to replace the invalidated instance. 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. To ensure liveness of the pool, addObject() is called to replace the invalidated instance.

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

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. For each object deemed abandoned, `invalidateObject(Object)` is called. This results in the object being destroyed and then `addObject()` is called to try to replace it. Parameters abandonedConfig:AbandonedConfig The configuration to use to identify abandoned objects Annotations @SuppressWarnings:resource

private void removeAbandoned(final AbandonedConfig abandonedConfig)

Recovers abandoned objects which have been checked out but not used since longer than the removeAbandonedTimeout. For each object deemed abandoned, invalidateObject(Object) is called. This results in the object being destroyed and then addObject() is called to try to replace it.

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

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

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

Annotations

@Override

public Class GenericObjectPool<T>

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail