Package org.apache.tomcat.dbcp.pool2.impl

Class BaseGenericObjectPool<T>

java.lang.Object

org.apache.tomcat.dbcp.pool2.BaseObject

org.apache.tomcat.dbcp.pool2.impl.BaseGenericObjectPool<T>

Type Parameters:

T - Type of element pooled in this pool.

All Implemented Interfaces:

AutoCloseable

Direct Known Subclasses:

GenericKeyedObjectPool, GenericObjectPool

public abstract class BaseGenericObjectPool<T>
extends BaseObject
implements AutoCloseable

Base class that provides common functionality for GenericObjectPool and GenericKeyedObjectPool. The primary reason this class exists is reduce code duplication between the two pool implementations.

Concrete implementations of this class are expected to be thread-safe.

Since:

2.0

Field Summary

Fields

Modifier and Type	Field	Description
protected AbandonedConfig	abandonedConfig	Additional configuration properties for abandoned object tracking.
static final int	MEAN_TIMING_STATS_CACHE_SIZE	The size of the caches used to store historical data for some attributes so that rolling means may be calculated.

Constructor Summary

Constructors

Constructor	Description
BaseGenericObjectPool(BaseObjectPoolConfig<T> config, String jmxNameBase, String jmxNamePrefix)	Handles JMX registration (if required) and the initialization required for monitoring.

Method Summary

Modifier and Type	Method	Description
abstract void	close()	Closes the pool, destroys the remaining idle objects and, if registered in JMX, deregisters it.
abstract void	evict()	Perform numTests idle object eviction tests, evicting examined objects that meet the criteria for eviction.
final boolean	getBlockWhenExhausted()	Gets whether to block when the borrowObject() method is invoked when the pool is exhausted (the maximum number of "active" objects has been reached).
final long	getBorrowedCount()	Gets the total number of objects successfully borrowed from this pool over the lifetime of the pool.
final long	getCreatedCount()	Gets the total number of objects created for this pool over the lifetime of the pool.
final String	getCreationStackTrace()	Gets the stack trace for the call that created this pool.
final long	getDestroyedByBorrowValidationCount()	Gets the total number of objects destroyed by this pool as a result of failing validation during borrowObject() over the lifetime of the pool.
final long	getDestroyedByEvictorCount()	Gets the total number of objects destroyed by the evictor associated with this pool over the lifetime of the pool.
final long	getDestroyedCount()	Gets the total number of objects destroyed by this pool over the lifetime of the pool.
final Duration	getDurationBetweenEvictionRuns()	Gets the duration to sleep between runs of the idle object evictor thread.
EvictionPolicy<T>	getEvictionPolicy()	Gets the EvictionPolicy defined for this pool.
final String	getEvictionPolicyClassName()	Gets the name of the EvictionPolicy implementation that is used by this pool.
final Duration	getEvictorShutdownTimeout()	Deprecated. Use getEvictorShutdownTimeoutDuration().
final Duration	getEvictorShutdownTimeoutDuration()	Gets the timeout that will be used when waiting for the Evictor to shutdown if this pool is closed and it is the only pool still using the the value for the Evictor.
final long	getEvictorShutdownTimeoutMillis()	Deprecated. Use getEvictorShutdownTimeoutDuration().
final boolean	getFairness()	Gets whether or not the pool serves threads waiting to borrow objects fairly.
final ObjectName	getJmxName()	Gets the name under which the pool has been registered with the platform MBean server or null if the pool has not been registered.
final boolean	getLifo()	Gets whether the pool has LIFO (last in, first out) behavior with respect to idle objects - always returning the most recently used object from the pool, or as a FIFO (first in, first out) queue, where the pool always returns the oldest object in the idle object pool.
boolean	getLogAbandoned()	Gets whether this pool identifies and logs any abandoned objects.
final Duration	getMaxBorrowWaitDuration()	Gets the maximum time a thread has waited to borrow objects from the pool.
final long	getMaxBorrowWaitTimeMillis()	Deprecated. Use getMaxBorrowWaitDuration().
final int	getMaxTotal()	Gets the maximum number of objects that can be allocated by the pool (checked out to clients, or idle awaiting checkout) at a given time.
final Duration	getMaxWaitDuration()	Gets the maximum duration the borrowObject() method should block before throwing an exception when the pool is exhausted and getBlockWhenExhausted() is true.
final long	getMaxWaitMillis()	Deprecated. Use getMaxWaitDuration().
final Duration	getMeanActiveDuration()	Gets the mean time objects are active for based on the last MEAN_TIMING_STATS_CACHE_SIZE objects returned to the pool.
final long	getMeanActiveTimeMillis()	Deprecated. Use getMeanActiveDuration().
final Duration	getMeanBorrowWaitDuration()	Gets the mean time threads wait to borrow an object based on the last MEAN_TIMING_STATS_CACHE_SIZE objects borrowed from the pool.
final long	getMeanBorrowWaitTimeMillis()	Deprecated. Use getMeanBorrowWaitDuration().
final Duration	getMeanIdleDuration()	Gets the mean time objects are idle for based on the last MEAN_TIMING_STATS_CACHE_SIZE objects borrowed from the pool.
final long	getMeanIdleTimeMillis()	Deprecated. Use getMeanIdleDuration().
boolean	getMessageStatistics()	Gets whether to include statistics in exception messages.
final Duration	getMinEvictableIdleDuration()	Gets the minimum amount of time an object may sit idle in the pool before it is eligible for eviction by the idle object evictor (if any - see setDurationBetweenEvictionRuns(Duration)).
final Duration	getMinEvictableIdleTime()	Deprecated. Use getMinEvictableIdleDuration().
final long	getMinEvictableIdleTimeMillis()	Deprecated. Use getMinEvictableIdleDuration().
abstract int	getNumIdle()	Gets the number of instances currently idle in this pool.
final int	getNumTestsPerEvictionRun()	Gets the maximum number of objects to examine during each run (if any) of the idle object evictor thread.
boolean	getRemoveAbandonedOnBorrow()	Gets whether a check is made for abandoned objects when an object is borrowed from this pool.
boolean	getRemoveAbandonedOnMaintenance()	Gets whether a check is made for abandoned objects when the evictor runs.
int	getRemoveAbandonedTimeout()	Deprecated. Use getRemoveAbandonedTimeoutDuration().
Duration	getRemoveAbandonedTimeoutDuration()	Gets the timeout before which an object will be considered to be abandoned by this pool.
final long	getReturnedCount()	Gets the total number of objects returned to this pool over the lifetime of the pool.
final Duration	getSoftMinEvictableIdleDuration()	Gets the minimum amount of time an object may sit idle in the pool before it is eligible for eviction by the idle object evictor (if any - see setDurationBetweenEvictionRuns(Duration)), with the extra condition that at least minIdle object instances remain in the pool.
final Duration	getSoftMinEvictableIdleTime()	Deprecated. Use getSoftMinEvictableIdleDuration().
final long	getSoftMinEvictableIdleTimeMillis()	Deprecated. Use getSoftMinEvictableIdleTime().
final SwallowedExceptionListener	getSwallowedExceptionListener()	Gets the listener used (if any) to receive notifications of exceptions unavoidably swallowed by the pool.
final boolean	getTestOnBorrow()	Gets whether objects borrowed from the pool will be validated before being returned from the borrowObject() method.
final boolean	getTestOnCreate()	Gets whether objects created for the pool will be validated before being returned from the borrowObject() method.
final boolean	getTestOnReturn()	Gets whether objects borrowed from the pool will be validated when they are returned to the pool via the returnObject() method.
final boolean	getTestWhileIdle()	Gets whether objects sitting idle in the pool will be validated by the idle object evictor (if any - see setDurationBetweenEvictionRuns(Duration)).
final Duration	getTimeBetweenEvictionRuns()	Deprecated. getDurationBetweenEvictionRuns().
final long	getTimeBetweenEvictionRunsMillis()	Deprecated. Use getDurationBetweenEvictionRuns().
boolean	isAbandonedConfig()	Tests whether or not abandoned object removal is configured for this pool.
final boolean	isClosed()	Tests whether this pool instance been closed.
protected void	markReturningState(PooledObject<T> pooledObject)	Marks the object as returning to the pool.
void	setAbandonedConfig(AbandonedConfig abandonedConfig)	Sets the abandoned object removal configuration.
final void	setBlockWhenExhausted(boolean blockWhenExhausted)	Sets whether to block when the borrowObject() method is invoked when the pool is exhausted (the maximum number of "active" objects has been reached).
protected void	setConfig(BaseObjectPoolConfig<T> config)	Sets the receiver with the given configuration.
final void	setDurationBetweenEvictionRuns(Duration timeBetweenEvictionRuns)	Sets the number of milliseconds to sleep between runs of the idle object evictor thread.
void	setEvictionPolicy(EvictionPolicy<T> evictionPolicy)	Sets the eviction policy for this pool.
final void	setEvictionPolicyClassName(String evictionPolicyClassName)	Sets the name of the EvictionPolicy implementation that is used by this pool.
final void	setEvictionPolicyClassName(String evictionPolicyClassName, ClassLoader classLoader)	Sets the name of the EvictionPolicy implementation that is used by this pool.
final void	setEvictorShutdownTimeout(Duration evictorShutdownTimeout)	Sets the timeout that will be used when waiting for the Evictor to shutdown if this pool is closed and it is the only pool still using the value for the Evictor.
final void	setEvictorShutdownTimeoutMillis(long evictorShutdownTimeoutMillis)	Deprecated. Use setEvictorShutdownTimeout(Duration).
final void	setLifo(boolean lifo)	Sets whether the pool has LIFO (last in, first out) behavior with respect to idle objects - always returning the most recently used object from the pool, or as a FIFO (first in, first out) queue, where the pool always returns the oldest object in the idle object pool.
final void	setMaxTotal(int maxTotal)	Sets the cap on the number of objects that can be allocated by the pool (checked out to clients, or idle awaiting checkout) at a given time.
final void	setMaxWait(Duration maxWaitDuration)	Sets the maximum duration the borrowObject() method should block before throwing an exception when the pool is exhausted and getBlockWhenExhausted() is true.
final void	setMaxWaitMillis(long maxWaitMillis)	Deprecated. Use setMaxWait(java.time.Duration).
void	setMessagesStatistics(boolean messagesDetails)	Sets whether to include statistics in exception messages.
final void	setMinEvictableIdle(Duration minEvictableIdleTime)	Deprecated. Use setMinEvictableIdleDuration(Duration).
final void	setMinEvictableIdleDuration(Duration minEvictableIdleTime)	Sets the minimum amount of time an object may sit idle in the pool before it is eligible for eviction by the idle object evictor (if any - see setDurationBetweenEvictionRuns(Duration)).
final void	setMinEvictableIdleTime(Duration minEvictableIdleTime)	Deprecated. Use setMinEvictableIdleDuration(Duration).
final void	setMinEvictableIdleTimeMillis(long minEvictableIdleTimeMillis)	Deprecated. Use setMinEvictableIdleTime(Duration).
final void	setNumTestsPerEvictionRun(int numTestsPerEvictionRun)	Sets the maximum number of objects to examine during each run (if any) of the idle object evictor thread.
final void	setSoftMinEvictableIdle(Duration softMinEvictableIdleTime)	Deprecated. Use setSoftMinEvictableIdleDuration(Duration).
final void	setSoftMinEvictableIdleDuration(Duration softMinEvictableIdleTime)	Sets the minimum amount of time an object may sit idle in the pool before it is eligible for eviction by the idle object evictor (if any - see setDurationBetweenEvictionRuns(Duration)), with the extra condition that at least minIdle object instances remain in the pool.
final void	setSoftMinEvictableIdleTime(Duration softMinEvictableIdleTime)	Deprecated. Use setSoftMinEvictableIdleDuration(Duration).
final void	setSoftMinEvictableIdleTimeMillis(long softMinEvictableIdleTimeMillis)	Deprecated. Use setSoftMinEvictableIdleDuration(Duration).
final void	setSwallowedExceptionListener(SwallowedExceptionListener swallowedExceptionListener)	Sets the listener used (if any) to receive notifications of exceptions unavoidably swallowed by the pool.
final void	setTestOnBorrow(boolean testOnBorrow)	Sets whether objects borrowed from the pool will be validated before being returned from the borrowObject() method.
final void	setTestOnCreate(boolean testOnCreate)	Sets whether objects created for the pool will be validated before being returned from the borrowObject() method.
final void	setTestOnReturn(boolean testOnReturn)	Sets whether objects borrowed from the pool will be validated when they are returned to the pool via the returnObject() method.
final void	setTestWhileIdle(boolean testWhileIdle)	Sets whether objects sitting idle in the pool will be validated by the idle object evictor (if any - see setDurationBetweenEvictionRuns(Duration)).
final void	setTimeBetweenEvictionRuns(Duration timeBetweenEvictionRuns)	Deprecated. Use setDurationBetweenEvictionRuns(Duration).
final void	setTimeBetweenEvictionRunsMillis(long timeBetweenEvictionRunsMillis)	Deprecated. Use setDurationBetweenEvictionRuns(Duration).
protected void	toStringAppendFields(StringBuilder builder)	Used by sub-classes to include the fields defined by the sub-class in the BaseObject.toString() output.

Methods inherited from class org.apache.tomcat.dbcp.pool2.BaseObject

toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Details

MEAN_TIMING_STATS_CACHE_SIZE

public static final int MEAN_TIMING_STATS_CACHE_SIZE

The size of the caches used to store historical data for some attributes so that rolling means may be calculated.

See Also:

• Constant Field Values

abandonedConfig

protected volatile AbandonedConfig abandonedConfig

Additional configuration properties for abandoned object tracking.

Constructor Details

BaseGenericObjectPool

public BaseGenericObjectPool(BaseObjectPoolConfig<T> config,
 String jmxNameBase,
 String jmxNamePrefix)

Handles JMX registration (if required) and the initialization required for monitoring.

Parameters:

config - Pool configuration

jmxNameBase - The default base JMX name for the new pool unless overridden by the config

jmxNamePrefix - Prefix to be used for JMX name for the new pool

Method Details

close

public abstract void close()

Closes the pool, destroys the remaining idle objects and, if registered in JMX, deregisters it.

Specified by:

close in interface AutoCloseable

evict

public abstract void evict()
                    throws Exception

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.

Throws:

Exception - when there is a problem evicting idle objects.

getBlockWhenExhausted

public final boolean getBlockWhenExhausted()

Gets whether to block when the borrowObject() method is invoked when the pool is exhausted (the maximum number of "active" objects has been reached).

Returns:

true if borrowObject() should block when the pool is exhausted

See Also:

• setBlockWhenExhausted(boolean)

getBorrowedCount

public final long getBorrowedCount()

Gets the total number of objects successfully borrowed from this pool over the lifetime of the pool.

Returns:

the borrowed object count

getCreatedCount

public final long getCreatedCount()

Gets the total number of objects created for this pool over the lifetime of the pool.

Returns:

the created object count

getCreationStackTrace

public final String getCreationStackTrace()

Gets the stack trace for the call that created this pool. JMX registration may trigger a memory leak so it is important that pools are deregistered when no longer used by calling the close() method. This method is provided to assist with identifying code that creates but does not close it thereby creating a memory leak.

Returns:

pool creation stack trace

getDestroyedByBorrowValidationCount

public final long getDestroyedByBorrowValidationCount()

Gets the total number of objects destroyed by this pool as a result of failing validation during borrowObject() over the lifetime of the pool.

Returns:

validation destroyed object count

getDestroyedByEvictorCount

public final long getDestroyedByEvictorCount()

Gets the total number of objects destroyed by the evictor associated with this pool over the lifetime of the pool.

Returns:

the evictor destroyed object count

getDestroyedCount

public final long getDestroyedCount()

Gets the total number of objects destroyed by this pool over the lifetime of the pool.

Returns:

the destroyed object count

getDurationBetweenEvictionRuns

public final Duration getDurationBetweenEvictionRuns()

Gets the duration to sleep between runs of the idle object evictor thread. When non-positive, no idle object evictor thread will be run.

Returns:

number of milliseconds to sleep between evictor runs

Since:

2.11.0

See Also:

• setTimeBetweenEvictionRuns(java.time.Duration)

getEvictionPolicy

public EvictionPolicy<T> getEvictionPolicy()

Gets the EvictionPolicy defined for this pool.

Returns:

the eviction policy

Since:

2.4, 2.6.0 Changed access from protected to public.

getEvictionPolicyClassName

public final String getEvictionPolicyClassName()

Gets the name of the EvictionPolicy implementation that is used by this pool.

Returns:

The fully qualified class name of the EvictionPolicy

See Also:

• setEvictionPolicyClassName(String)

getEvictorShutdownTimeout

@Deprecated
public final Duration getEvictorShutdownTimeout()

Deprecated.

Use getEvictorShutdownTimeoutDuration().

Gets the timeout that will be used when waiting for the Evictor to shutdown if this pool is closed and it is the only pool still using the the value for the Evictor.

Returns:

The timeout that will be used while waiting for the Evictor to shut down.

Since:

2.10.0

getEvictorShutdownTimeoutDuration

public final Duration getEvictorShutdownTimeoutDuration()

Gets the timeout that will be used when waiting for the Evictor to shutdown if this pool is closed and it is the only pool still using the the value for the Evictor.

Returns:

The timeout that will be used while waiting for the Evictor to shut down.

Since:

2.11.0

getEvictorShutdownTimeoutMillis

@Deprecated
public final long getEvictorShutdownTimeoutMillis()

Deprecated.

Use getEvictorShutdownTimeoutDuration().

Gets the timeout that will be used when waiting for the Evictor to shutdown if this pool is closed and it is the only pool still using the the value for the Evictor.

Returns:

The timeout in milliseconds that will be used while waiting for the Evictor to shut down.

getFairness

public final boolean getFairness()

Gets whether or not the pool serves threads waiting to borrow objects fairly. True means that waiting threads are served as if waiting in a FIFO queue.

Returns:

true if waiting threads are to be served by the pool in arrival order

getJmxName

public final ObjectName getJmxName()

Gets the name under which the pool has been registered with the platform MBean server or null if the pool has not been registered.

Returns:

the JMX name

getLifo

public final boolean getLifo()

Gets whether the pool has LIFO (last in, first out) behavior with respect to idle objects - always returning the most recently used object from the pool, or as a FIFO (first in, first out) queue, where the pool always returns the oldest object in the idle object pool.

Returns:

true if the pool is configured with LIFO behavior or false if the pool is configured with FIFO behavior

See Also:

• setLifo(boolean)

getLogAbandoned

public boolean getLogAbandoned()

Gets whether this pool identifies and logs any abandoned objects.

Returns:

true if abandoned object removal is configured for this pool and removal events are to be logged otherwise false

Since:

2.11.0

See Also:

• AbandonedConfig.getLogAbandoned()

getMaxBorrowWaitDuration

public final Duration getMaxBorrowWaitDuration()

Gets the maximum time a thread has waited to borrow objects from the pool.

Returns:

maximum wait time in milliseconds since the pool was created

Since:

2.12.0

getMaxBorrowWaitTimeMillis

@Deprecated
public final long getMaxBorrowWaitTimeMillis()

Deprecated.

Use getMaxBorrowWaitDuration().

Gets the maximum time a thread has waited to borrow objects from the pool.

Returns:

maximum wait time in milliseconds since the pool was created

getMaxTotal

public final int getMaxTotal()

Gets the maximum number of objects that can be allocated by the pool (checked out to clients, or idle awaiting checkout) at a given time. When negative, there is no limit to the number of objects that can be managed by the pool at one time.

Returns:

the cap on the total number of object instances managed by the pool.

See Also:

• setMaxTotal(int)

getMaxWaitDuration

public final Duration getMaxWaitDuration()

Gets the maximum duration the borrowObject() method should block before throwing an exception when the pool is exhausted and getBlockWhenExhausted() is true. When less than 0, the borrowObject() method may block indefinitely.

Returns:

the maximum number of milliseconds borrowObject() will block.

Since:

2.11.0

See Also:

• setMaxWait(java.time.Duration)
• setBlockWhenExhausted(boolean)

getMaxWaitMillis

@Deprecated
public final long getMaxWaitMillis()

Deprecated.

Use getMaxWaitDuration().

Gets the maximum amount of time (in milliseconds) the borrowObject() method should block before throwing an exception when the pool is exhausted and getBlockWhenExhausted() is true. When less than 0, the borrowObject() method may block indefinitely.

Returns:

the maximum number of milliseconds borrowObject() will block.

See Also:

• setMaxWait(java.time.Duration)
• setBlockWhenExhausted(boolean)

getMeanActiveDuration

public final Duration getMeanActiveDuration()

Gets the mean time objects are active for based on the last MEAN_TIMING_STATS_CACHE_SIZE objects returned to the pool.

Returns:

mean time an object has been checked out from the pool among recently returned objects.

Since:

2.12.0

getMeanActiveTimeMillis

@Deprecated
public final long getMeanActiveTimeMillis()

Deprecated.

Use getMeanActiveDuration().

Gets the mean time objects are active for based on the last MEAN_TIMING_STATS_CACHE_SIZE objects returned to the pool.

Returns:

mean time an object has been checked out from the pool among recently returned objects.

getMeanBorrowWaitDuration

public final Duration getMeanBorrowWaitDuration()

Gets the mean time threads wait to borrow an object based on the last MEAN_TIMING_STATS_CACHE_SIZE objects borrowed from the pool.

Returns:

mean time in milliseconds that a recently served thread has had to wait to borrow an object from the pool.

Since:

2.12.0

getMeanBorrowWaitTimeMillis

@Deprecated
public final long getMeanBorrowWaitTimeMillis()

Deprecated.

Use getMeanBorrowWaitDuration().

Gets the mean time threads wait to borrow an object based on the last MEAN_TIMING_STATS_CACHE_SIZE objects borrowed from the pool.

Returns:

mean time in milliseconds that a recently served thread has had to wait to borrow an object from the pool.

getMeanIdleDuration

public final Duration getMeanIdleDuration()

Gets the mean time objects are idle for based on the last MEAN_TIMING_STATS_CACHE_SIZE objects borrowed from the pool.

Returns:

mean time an object has been idle in the pool among recently borrowed objects.

Since:

2.12.0

getMeanIdleTimeMillis

@Deprecated
public final long getMeanIdleTimeMillis()

Deprecated.

Use getMeanIdleDuration().

Gets the mean time objects are idle for based on the last MEAN_TIMING_STATS_CACHE_SIZE objects borrowed from the pool.

Returns:

mean time an object has been idle in the pool among recently borrowed objects.

getMessageStatistics

public boolean getMessageStatistics()

Gets whether to include statistics in exception messages.

Statistics may not accurately reflect snapshot state at the time of the exception because we do not want to lock the pool when gathering this information.

Returns:

whether to include statistics in exception messages.

Since:

2.11.0

getMinEvictableIdleDuration

public final Duration getMinEvictableIdleDuration()

Gets the minimum amount of time an object may sit idle in the pool before it is eligible for eviction by the idle object evictor (if any - see setDurationBetweenEvictionRuns(Duration)). When non-positive, no objects will be evicted from the pool due to idle time alone.

Returns:

minimum amount of time an object may sit idle in the pool before it is eligible for eviction

Since:

2.11.0

See Also:

• setMinEvictableIdleTimeMillis(long)
• setTimeBetweenEvictionRunsMillis(long)

getMinEvictableIdleTime

@Deprecated
public final Duration getMinEvictableIdleTime()

Deprecated.

Use getMinEvictableIdleDuration().

Gets the minimum amount of time an object may sit idle in the pool before it is eligible for eviction by the idle object evictor (if any - see setDurationBetweenEvictionRuns(Duration)). When non-positive, no objects will be evicted from the pool due to idle time alone.

Returns:

minimum amount of time an object may sit idle in the pool before it is eligible for eviction

Since:

2.10.0

See Also:

• setMinEvictableIdleTimeMillis(long)
• setTimeBetweenEvictionRunsMillis(long)

getMinEvictableIdleTimeMillis

@Deprecated
public final long getMinEvictableIdleTimeMillis()

Deprecated.

Use getMinEvictableIdleDuration().

Gets the minimum amount of time an object may sit idle in the pool before it is eligible for eviction by the idle object evictor (if any - see setTimeBetweenEvictionRunsMillis(long)). When non-positive, no objects will be evicted from the pool due to idle time alone.

Returns:

minimum amount of time an object may sit idle in the pool before it is eligible for eviction

See Also:

• setMinEvictableIdleTimeMillis(long)
• setTimeBetweenEvictionRunsMillis(long)

getNumIdle

public abstract int getNumIdle()

Gets the number of instances currently idle in this pool.

Returns:

count of instances available for checkout from the pool

getNumTestsPerEvictionRun

public final int getNumTestsPerEvictionRun()

Gets the maximum number of objects to examine during each run (if any) of the idle object evictor thread. When positive, the number of tests performed for a run will be the minimum of the configured value and the number of idle instances in the pool. When negative, the number of tests performed will be ceil(getNumIdle()/ abs(getNumTestsPerEvictionRun())) which means that when the value is -n roughly one nth of the idle objects will be tested per run.

Returns:

max number of objects to examine during each evictor run

See Also:

• setNumTestsPerEvictionRun(int)
• setTimeBetweenEvictionRunsMillis(long)

getRemoveAbandonedOnBorrow

public boolean getRemoveAbandonedOnBorrow()

Gets whether a check is made for abandoned objects when an object is borrowed from this pool.

Returns:

true if abandoned object removal is configured to be activated by borrowObject otherwise false

Since:

2.11.0

See Also:

• AbandonedConfig.getRemoveAbandonedOnBorrow()

getRemoveAbandonedOnMaintenance

public boolean getRemoveAbandonedOnMaintenance()

Gets whether a check is made for abandoned objects when the evictor runs.

Returns:

true if abandoned object removal is configured to be activated when the evictor runs otherwise false

Since:

2.11.0

See Also:

• AbandonedConfig.getRemoveAbandonedOnMaintenance()

getRemoveAbandonedTimeout

@Deprecated
public int getRemoveAbandonedTimeout()

Deprecated.

Use getRemoveAbandonedTimeoutDuration().

Gets the timeout before which an object will be considered to be abandoned by this pool.

Returns:

The abandoned object timeout in seconds if abandoned object removal is configured for this pool; Integer.MAX_VALUE otherwise.

Since:

2.11.0

See Also:

• AbandonedConfig.getRemoveAbandonedTimeoutDuration()
• AbandonedConfig.getRemoveAbandonedTimeoutDuration()

getRemoveAbandonedTimeoutDuration

public Duration getRemoveAbandonedTimeoutDuration()

Gets the timeout before which an object will be considered to be abandoned by this pool.

Returns:

The abandoned object timeout in seconds if abandoned object removal is configured for this pool; Integer.MAX_VALUE otherwise.

Since:

2.11.0

See Also:

• AbandonedConfig.getRemoveAbandonedTimeoutDuration()

getReturnedCount

public final long getReturnedCount()

Gets the total number of objects returned to this pool over the lifetime of the pool. This excludes attempts to return the same object multiple times.

Returns:

the returned object count

getSoftMinEvictableIdleDuration

public final Duration getSoftMinEvictableIdleDuration()

Gets the minimum amount of time an object may sit idle in the pool before it is eligible for eviction by the idle object evictor (if any - see setDurationBetweenEvictionRuns(Duration)), with the extra condition that at least minIdle object instances remain in the pool. This setting is overridden by getMinEvictableIdleTime() (that is, if getMinEvictableIdleTime() is positive, then getSoftMinEvictableIdleTime() is ignored).

Returns:

minimum amount of time an object may sit idle in the pool before it is eligible for eviction if minIdle instances are available

Since:

2.11.0

See Also:

• setSoftMinEvictableIdleDuration(Duration)

getSoftMinEvictableIdleTime

@Deprecated
public final Duration getSoftMinEvictableIdleTime()

Deprecated.

Use getSoftMinEvictableIdleDuration().

Gets the minimum amount of time an object may sit idle in the pool before it is eligible for eviction by the idle object evictor (if any - see setDurationBetweenEvictionRuns(Duration)), with the extra condition that at least minIdle object instances remain in the pool. This setting is overridden by getMinEvictableIdleTime() (that is, if getMinEvictableIdleTime() is positive, then getSoftMinEvictableIdleTime() is ignored).

Returns:

minimum amount of time an object may sit idle in the pool before it is eligible for eviction if minIdle instances are available

Since:

2.10.0

See Also:

• setSoftMinEvictableIdleDuration(Duration)

getSoftMinEvictableIdleTimeMillis

@Deprecated
public final long getSoftMinEvictableIdleTimeMillis()

Deprecated.

Use getSoftMinEvictableIdleTime().

Gets the minimum amount of time an object may sit idle in the pool before it is eligible for eviction by the idle object evictor (if any - see setTimeBetweenEvictionRunsMillis(long)), with the extra condition that at least minIdle object instances remain in the pool. This setting is overridden by getMinEvictableIdleTimeMillis() (that is, if getMinEvictableIdleTimeMillis() is positive, then getSoftMinEvictableIdleTimeMillis() is ignored).

Returns:

minimum amount of time an object may sit idle in the pool before it is eligible for eviction if minIdle instances are available

See Also:

• setSoftMinEvictableIdleTimeMillis(long)

getSwallowedExceptionListener

public final SwallowedExceptionListener getSwallowedExceptionListener()

Gets the listener used (if any) to receive notifications of exceptions unavoidably swallowed by the pool.

Returns:

The listener or null for no listener

getTestOnBorrow

public final boolean getTestOnBorrow()

Gets whether objects borrowed from the pool will be validated before being returned from the borrowObject() method. Validation is performed by the validateObject() method of the factory associated with the pool. If the object fails to validate, it will be removed from the pool and destroyed, and a new attempt will be made to borrow an object from the pool.

Returns:

true if objects are validated before being returned from the borrowObject() method

See Also:

• setTestOnBorrow(boolean)

getTestOnCreate

public final boolean getTestOnCreate()

Gets whether objects created for the pool will be validated before being returned from the borrowObject() method. Validation is performed by the validateObject() method of the factory associated with the pool. If the object fails to validate, then borrowObject() will fail.

Returns:

true if newly created objects are validated before being returned from the borrowObject() method

Since:

2.2

See Also:

• setTestOnCreate(boolean)

getTestOnReturn

public final boolean getTestOnReturn()

Gets whether objects borrowed from the pool will be validated when they are returned to the pool via the returnObject() method. Validation is performed by the validateObject() method of the factory associated with the pool. Returning objects that fail validation are destroyed rather then being returned the pool.

Returns:

true if objects are validated on return to the pool via the returnObject() method

See Also:

• setTestOnReturn(boolean)

getTestWhileIdle

public final boolean getTestWhileIdle()

Gets whether objects sitting idle in the pool will be validated by the idle object evictor (if any - see setDurationBetweenEvictionRuns(Duration)). Validation is performed by the validateObject() method of the factory associated with the pool. If the object fails to validate, it will be removed from the pool and destroyed.

Returns:

true if objects will be validated by the evictor

See Also:

• setTestWhileIdle(boolean)
• setTimeBetweenEvictionRunsMillis(long)

getTimeBetweenEvictionRuns

@Deprecated
public final Duration getTimeBetweenEvictionRuns()

Deprecated.

getDurationBetweenEvictionRuns().

Gets the duration to sleep between runs of the idle object evictor thread. When non-positive, no idle object evictor thread will be run.

Returns:

number of milliseconds to sleep between evictor runs

Since:

2.10.0

See Also:

• setTimeBetweenEvictionRuns(java.time.Duration)

getTimeBetweenEvictionRunsMillis

@Deprecated
public final long getTimeBetweenEvictionRunsMillis()

Deprecated.

Use getDurationBetweenEvictionRuns().

Gets the number of milliseconds to sleep between runs of the idle object evictor thread. When non-positive, no idle object evictor thread will be run.

Returns:

number of milliseconds to sleep between evictor runs

See Also:

• setTimeBetweenEvictionRunsMillis(long)

isAbandonedConfig

public boolean isAbandonedConfig()

Tests whether or not abandoned object removal is configured for this pool.

Returns:

true if this pool is configured to detect and remove abandoned objects

Since:

2.11.0

isClosed

public final boolean isClosed()

Tests whether this pool instance been closed.

Returns:

true when this pool has been closed.

markReturningState

protected void markReturningState(PooledObject<T> pooledObject)

Marks the object as returning to the pool.

Parameters:

pooledObject - instance to return to the keyed pool

setAbandonedConfig

public void setAbandonedConfig(AbandonedConfig abandonedConfig)

Sets the abandoned object removal configuration.

Parameters:

abandonedConfig - the new configuration to use. This is used by value.

Since:

2.11.0

See Also:

• AbandonedConfig

setBlockWhenExhausted

public final void setBlockWhenExhausted(boolean blockWhenExhausted)

Sets whether to block when the borrowObject() method is invoked when the pool is exhausted (the maximum number of "active" objects has been reached).

Parameters:

blockWhenExhausted - true if borrowObject() should block when the pool is exhausted

See Also:

• getBlockWhenExhausted()

setConfig

protected void setConfig(BaseObjectPoolConfig<T> config)

Sets the receiver with the given configuration.

Parameters:

config - Initialization source.

setDurationBetweenEvictionRuns

public final void setDurationBetweenEvictionRuns(Duration timeBetweenEvictionRuns)

Sets the number of milliseconds to sleep between runs of the idle object evictor thread.

• When positive, the idle object evictor thread starts.
• When null or non-positive, no idle object evictor thread runs.

Parameters:

timeBetweenEvictionRuns - duration to sleep between evictor runs

Since:

2.12.0

See Also:

• getDurationBetweenEvictionRuns()

setEvictionPolicy

public void setEvictionPolicy(EvictionPolicy<T> evictionPolicy)

Sets the eviction policy for this pool.

Parameters:

evictionPolicy - the eviction policy for this pool.

Since:

2.6.0

setEvictionPolicyClassName

public final void setEvictionPolicyClassName(String evictionPolicyClassName)

Sets the name of the EvictionPolicy implementation that is used by this pool. The Pool will attempt to load the class using the thread context class loader. If that fails, the use the class loader for the EvictionPolicy interface.

Parameters:

evictionPolicyClassName - the fully qualified class name of the new eviction policy

Since:

2.6.0 If loading the class using the thread context class loader fails, use the class loader for the EvictionPolicy interface.

See Also:

• getEvictionPolicyClassName()

setEvictionPolicyClassName

public final void setEvictionPolicyClassName(String evictionPolicyClassName,
 ClassLoader classLoader)

Sets the name of the EvictionPolicy implementation that is used by this pool. The Pool will attempt to load the class using the given class loader. If that fails, use the class loader for the EvictionPolicy interface.

Parameters:

evictionPolicyClassName - the fully qualified class name of the new eviction policy

classLoader - the class loader to load the given evictionPolicyClassName.

Since:

2.6.0 If loading the class using the given class loader fails, use the class loader for the EvictionPolicy interface.

See Also:

• getEvictionPolicyClassName()

setEvictorShutdownTimeout

public final void setEvictorShutdownTimeout(Duration evictorShutdownTimeout)

Sets the timeout that will be used when waiting for the Evictor to shutdown if this pool is closed and it is the only pool still using the value for the Evictor.

Parameters:

evictorShutdownTimeout - the timeout in milliseconds that will be used while waiting for the Evictor to shut down.

Since:

2.10.0

setEvictorShutdownTimeoutMillis

@Deprecated
public final void setEvictorShutdownTimeoutMillis(long evictorShutdownTimeoutMillis)

Deprecated.

Use setEvictorShutdownTimeout(Duration).

Sets the timeout that will be used when waiting for the Evictor to shutdown if this pool is closed and it is the only pool still using the value for the Evictor.

Parameters:

evictorShutdownTimeoutMillis - the timeout in milliseconds that will be used while waiting for the Evictor to shut down.

setLifo

public final void setLifo(boolean lifo)

Sets whether the pool has LIFO (last in, first out) behavior with respect to idle objects - always returning the most recently used object from the pool, or as a FIFO (first in, first out) queue, where the pool always returns the oldest object in the idle object pool.

Parameters:

lifo - true if the pool is to be configured with LIFO behavior or false if the pool is to be configured with FIFO behavior

See Also:

• getLifo()

setMaxTotal

public final void setMaxTotal(int maxTotal)

Sets the cap on the number of objects that can be allocated by the pool (checked out to clients, or idle awaiting checkout) at a given time. Use a negative value for no limit.

Parameters:

maxTotal - The cap on the total number of object instances managed by the pool. Negative values mean that there is no limit to the number of objects allocated by the pool.

See Also:

• getMaxTotal()

setMaxWait

public final void setMaxWait(Duration maxWaitDuration)

Sets the maximum duration the borrowObject() method should block before throwing an exception when the pool is exhausted and getBlockWhenExhausted() is true. When less than 0, the borrowObject() method may block indefinitely.

Parameters:

maxWaitDuration - the maximum duration borrowObject() will block or negative for indefinitely.

Since:

2.11.0

See Also:

• getMaxWaitDuration()
• setBlockWhenExhausted(boolean)

setMaxWaitMillis

@Deprecated
public final void setMaxWaitMillis(long maxWaitMillis)

Deprecated.

Use setMaxWait(java.time.Duration).

Sets the maximum amount of time (in milliseconds) the borrowObject() method should block before throwing an exception when the pool is exhausted and getBlockWhenExhausted() is true. When less than 0, the borrowObject() method may block indefinitely.

Parameters:

maxWaitMillis - the maximum number of milliseconds borrowObject() will block or negative for indefinitely.

See Also:

• getMaxWaitDuration()
• setBlockWhenExhausted(boolean)

setMessagesStatistics

public void setMessagesStatistics(boolean messagesDetails)

Sets whether to include statistics in exception messages.

Statistics may not accurately reflect snapshot state at the time of the exception because we do not want to lock the pool when gathering this information.

Parameters:

messagesDetails - whether to include statistics in exception messages.

Since:

2.11.0

setMinEvictableIdle

@Deprecated
public final void setMinEvictableIdle(Duration minEvictableIdleTime)

Deprecated.

Use setMinEvictableIdleDuration(Duration).

Sets the minimum amount of time an object may sit idle in the pool before it is eligible for eviction by the idle object evictor (if any - see setDurationBetweenEvictionRuns(Duration)). When non-positive, no objects will be evicted from the pool due to idle time alone.

Parameters:

minEvictableIdleTime - minimum amount of time an object may sit idle in the pool before it is eligible for eviction

Since:

2.11.0

See Also:

• getMinEvictableIdleTime()
• setTimeBetweenEvictionRuns(java.time.Duration)

setMinEvictableIdleDuration

public final void setMinEvictableIdleDuration(Duration minEvictableIdleTime)

Sets the minimum amount of time an object may sit idle in the pool before it is eligible for eviction by the idle object evictor (if any - see setDurationBetweenEvictionRuns(Duration)). When non-positive, no objects will be evicted from the pool due to idle time alone.

Parameters:

minEvictableIdleTime - minimum amount of time an object may sit idle in the pool before it is eligible for eviction

Since:

2.12.0

See Also:

• getMinEvictableIdleTime()
• setTimeBetweenEvictionRuns(java.time.Duration)

setMinEvictableIdleTime

@Deprecated
public final void setMinEvictableIdleTime(Duration minEvictableIdleTime)

Deprecated.

Use setMinEvictableIdleDuration(Duration).

Sets the minimum amount of time an object may sit idle in the pool before it is eligible for eviction by the idle object evictor (if any - see setDurationBetweenEvictionRuns(Duration)). When non-positive, no objects will be evicted from the pool due to idle time alone.

Parameters:

minEvictableIdleTime - minimum amount of time an object may sit idle in the pool before it is eligible for eviction

Since:

2.10.0

See Also:

• getMinEvictableIdleTime()
• setTimeBetweenEvictionRuns(java.time.Duration)

setMinEvictableIdleTimeMillis

@Deprecated
public final void setMinEvictableIdleTimeMillis(long minEvictableIdleTimeMillis)

Deprecated.

Use setMinEvictableIdleTime(Duration).

Sets the minimum amount of time an object may sit idle in the pool before it is eligible for eviction by the idle object evictor (if any - see setTimeBetweenEvictionRunsMillis(long)). When non-positive, no objects will be evicted from the pool due to idle time alone.

Parameters:

minEvictableIdleTimeMillis - minimum amount of time an object may sit idle in the pool before it is eligible for eviction

See Also:

• getMinEvictableIdleTimeMillis()
• setTimeBetweenEvictionRunsMillis(long)

setNumTestsPerEvictionRun

public final void setNumTestsPerEvictionRun(int numTestsPerEvictionRun)

Sets the maximum number of objects to examine during each run (if any) of the idle object evictor thread. When positive, the number of tests performed for a run will be the minimum of the configured value and the number of idle instances in the pool. When negative, the number of tests performed will be ceil(getNumIdle()/ abs(getNumTestsPerEvictionRun())) which means that when the value is -n roughly one nth of the idle objects will be tested per run.

Parameters:

numTestsPerEvictionRun - max number of objects to examine during each evictor run

See Also:

• getNumTestsPerEvictionRun()
• setTimeBetweenEvictionRunsMillis(long)

setSoftMinEvictableIdle

@Deprecated
public final void setSoftMinEvictableIdle(Duration softMinEvictableIdleTime)

Deprecated.

Use setSoftMinEvictableIdleDuration(Duration).

Sets the minimum amount of time an object may sit idle in the pool before it is eligible for eviction by the idle object evictor (if any - see setDurationBetweenEvictionRuns(Duration)), with the extra condition that at least minIdle object instances remain in the pool. This setting is overridden by getMinEvictableIdleTime() (that is, if getMinEvictableIdleTime() is positive, then getSoftMinEvictableIdleTime() is ignored).

Parameters:

softMinEvictableIdleTime - minimum amount of time an object may sit idle in the pool before it is eligible for eviction if minIdle instances are available

Since:

2.11.0

See Also:

• getSoftMinEvictableIdleTimeMillis()

setSoftMinEvictableIdleDuration

public final void setSoftMinEvictableIdleDuration(Duration softMinEvictableIdleTime)

Sets the minimum amount of time an object may sit idle in the pool before it is eligible for eviction by the idle object evictor (if any - see setDurationBetweenEvictionRuns(Duration)), with the extra condition that at least minIdle object instances remain in the pool. This setting is overridden by getMinEvictableIdleTime() (that is, if getMinEvictableIdleTime() is positive, then getSoftMinEvictableIdleTime() is ignored).

Parameters:

softMinEvictableIdleTime - minimum amount of time an object may sit idle in the pool before it is eligible for eviction if minIdle instances are available

Since:

2.12.0

See Also:

• getSoftMinEvictableIdleTimeMillis()

setSoftMinEvictableIdleTime

@Deprecated
public final void setSoftMinEvictableIdleTime(Duration softMinEvictableIdleTime)

Deprecated.

Use setSoftMinEvictableIdleDuration(Duration).

Sets the minimum amount of time an object may sit idle in the pool before it is eligible for eviction by the idle object evictor (if any - see setDurationBetweenEvictionRuns(Duration)), with the extra condition that at least minIdle object instances remain in the pool. This setting is overridden by getMinEvictableIdleTime() (that is, if getMinEvictableIdleTime() is positive, then getSoftMinEvictableIdleTime() is ignored).

Parameters:

softMinEvictableIdleTime - minimum amount of time an object may sit idle in the pool before it is eligible for eviction if minIdle instances are available

Since:

2.10.0

See Also:

• getSoftMinEvictableIdleTimeMillis()

setSoftMinEvictableIdleTimeMillis

@Deprecated
public final void setSoftMinEvictableIdleTimeMillis(long softMinEvictableIdleTimeMillis)

Deprecated.

Use setSoftMinEvictableIdleDuration(Duration).

Sets the minimum amount of time an object may sit idle in the pool before it is eligible for eviction by the idle object evictor (if any - see setTimeBetweenEvictionRunsMillis(long)), with the extra condition that at least minIdle object instances remain in the pool. This setting is overridden by getMinEvictableIdleTimeMillis() (that is, if getMinEvictableIdleTimeMillis() is positive, then getSoftMinEvictableIdleTimeMillis() is ignored).

Parameters:

softMinEvictableIdleTimeMillis - minimum amount of time an object may sit idle in the pool before it is eligible for eviction if minIdle instances are available

See Also:

• getSoftMinEvictableIdleTimeMillis()

setSwallowedExceptionListener

public final void setSwallowedExceptionListener(SwallowedExceptionListener swallowedExceptionListener)

Sets the listener used (if any) to receive notifications of exceptions unavoidably swallowed by the pool.

Parameters:

swallowedExceptionListener - The listener or null for no listener

setTestOnBorrow

public final void setTestOnBorrow(boolean testOnBorrow)

Sets whether objects borrowed from the pool will be validated before being returned from the borrowObject() method. Validation is performed by the validateObject() method of the factory associated with the pool. If the object fails to validate, it will be removed from the pool and destroyed, and a new attempt will be made to borrow an object from the pool.

Parameters:

testOnBorrow - true if objects should be validated before being returned from the borrowObject() method

See Also:

• getTestOnBorrow()

setTestOnCreate

public final void setTestOnCreate(boolean testOnCreate)

Sets whether objects created for the pool will be validated before being returned from the borrowObject() method. Validation is performed by the validateObject() method of the factory associated with the pool. If the object fails to validate, then borrowObject() will fail.

Parameters:

testOnCreate - true if newly created objects should be validated before being returned from the borrowObject() method

Since:

2.2

See Also:

• getTestOnCreate()

setTestOnReturn

public final void setTestOnReturn(boolean testOnReturn)

Sets whether objects borrowed from the pool will be validated when they are returned to the pool via the returnObject() method. Validation is performed by the validateObject() method of the factory associated with the pool. Returning objects that fail validation are destroyed rather then being returned the pool.

Parameters:

testOnReturn - true if objects are validated on return to the pool via the returnObject() method

See Also:

• getTestOnReturn()

setTestWhileIdle

public final void setTestWhileIdle(boolean testWhileIdle)

Sets whether objects sitting idle in the pool will be validated by the idle object evictor (if any - see setDurationBetweenEvictionRuns(Duration)). Validation is performed by the validateObject() method of the factory associated with the pool. If the object fails to validate, it will be removed from the pool and destroyed. Note that setting this property has no effect unless the idle object evictor is enabled by setting timeBetweenEvictionRunsMillis to a positive value.

Parameters:

testWhileIdle - true so objects will be validated by the evictor

See Also:

• getTestWhileIdle()
• setTimeBetweenEvictionRuns(java.time.Duration)

setTimeBetweenEvictionRuns

@Deprecated
public final void setTimeBetweenEvictionRuns(Duration timeBetweenEvictionRuns)

Deprecated.

Use setDurationBetweenEvictionRuns(Duration).

Sets the number of milliseconds to sleep between runs of the idle object evictor thread.

• When positive, the idle object evictor thread starts.
• When non-positive, no idle object evictor thread runs.

Parameters:

timeBetweenEvictionRuns - duration to sleep between evictor runs

Since:

2.10.0

See Also:

• getDurationBetweenEvictionRuns()

setTimeBetweenEvictionRunsMillis

@Deprecated
public final void setTimeBetweenEvictionRunsMillis(long timeBetweenEvictionRunsMillis)

Deprecated.

Use setDurationBetweenEvictionRuns(Duration).

Sets the number of milliseconds to sleep between runs of the idle object evictor thread.

• When positive, the idle object evictor thread starts.
• When non-positive, no idle object evictor thread runs.

Parameters:

timeBetweenEvictionRunsMillis - number of milliseconds to sleep between evictor runs

See Also:

• getDurationBetweenEvictionRuns()

toStringAppendFields

protected void toStringAppendFields(StringBuilder builder)

Description copied from class: BaseObject

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

Overrides:

toStringAppendFields in class BaseObject

Parameters:

builder - Field names and values are appended to this object