GenericObjectPool (Commons Pool 1.5.1 API)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.apache.commons.pool.impl
Class GenericObjectPool

java.lang.Object
  org.apache.commons.pool.BaseObjectPool
      org.apache.commons.pool.impl.GenericObjectPool

All Implemented Interfaces:: ObjectPool

public class GenericObjectPool
extends BaseObjectPool
implements ObjectPool
extends BaseObjectPool
implements ObjectPool

A configurable ObjectPool implementation.

When coupled with the appropriate PoolableObjectFactory, GenericObjectPool provides robust pooling functionality for arbitrary objects.

A GenericObjectPool provides a number of configurable parameters:

maxActive controls 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 non-positive, there is no limit to the number of objects that can be managed by the pool at one time. When maxActive is reached, the pool is said to be exhausted. The default setting for this parameter is 8.
maxIdle controls the maximum number of objects that can sit idle in the pool at any time. When negative, there is no limit to the number of objects that may be idle at one time. The default setting for this parameter is 8.
whenExhaustedAction specifies the behavior of the borrowObject() method when the pool is exhausted:
- When whenExhaustedAction is WHEN_EXHAUSTED_FAIL, borrowObject() will throw a NoSuchElementException
- When whenExhaustedAction is WHEN_EXHAUSTED_GROW, borrowObject() will create a new object and return it (essentially making maxActive meaningless.)
- When whenExhaustedAction is WHEN_EXHAUSTED_BLOCK, borrowObject() will block (invoke Object.wait()) until a new or idle object is available. If a positive maxWait value is supplied, then borrowObject() will block for at most that many milliseconds, after which a NoSuchElementException will be thrown. If maxWait is non-positive, the borrowObject() method will block indefinitely.
The default whenExhaustedAction setting is WHEN_EXHAUSTED_BLOCK and the default maxWait setting is -1. By default, therefore, borrowObject will block indefinitely until an idle instance becomes available.
When testOnBorrow is set, the pool will attempt to validate each object before it is returned from the borrowObject() method. (Using the provided factory's PoolableObjectFactory.validateObject(java.lang.Object) method.) Objects that fail to validate will be dropped from the pool, and a different object will be borrowed. The default setting for this parameter is false.
When testOnReturn is set, the pool will attempt to validate each object before it is returned to the pool in the returnObject(java.lang.Object) method. (Using the provided factory's PoolableObjectFactory.validateObject(java.lang.Object) method.) Objects that fail to validate will be dropped from the pool. The default setting for this parameter is false.

Optionally, one may configure the pool to examine and possibly evict objects as they sit idle in the pool and to ensure that a minimum number of idle objects are available. This is performed by an "idle object eviction" thread, which runs asynchronously. Caution should be used when configuring this optional feature. Eviction runs require an exclusive synchronization lock on the pool, so if they run too frequently and / or incur excessive latency when creating, destroying or validating object instances, performance issues may result. The idle object eviction thread may be configured using the following attributes:

timeBetweenEvictionRunsMillis indicates how long the eviction thread should sleep before "runs" of examining idle objects. When non-positive, no eviction thread will be launched. The default setting for this parameter is -1 (i.e., idle object eviction is disabled by default).
minEvictableIdleTimeMillis specifies the minimum amount of time that an object may sit idle in the pool before it is eligible for eviction due to idle time. When non-positive, no object will be dropped from the pool due to idle time alone. This setting has no effect unless timeBetweenEvictionRunsMillis > 0. The default setting for this parameter is 30 minutes.
testWhileIdle indicates whether or not idle objects should be validated using the factory's PoolableObjectFactory.validateObject(java.lang.Object) method. Objects that fail to validate will be dropped from the pool. This setting has no effect unless timeBetweenEvictionRunsMillis > 0. The default setting for this parameter is false.
softMinEvictableIdleTimeMillis specifies 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), with the extra condition that at least "minIdle" object instances remain in the pool. When non-positive, no objects will be evicted from the pool due to idle time alone. This setting has no effect unless timeBetweenEvictionRunsMillis > 0. and it is superceded by minEvictableIdleTimeMillis (that is, if minEvictableIdleTimeMillis is positive, then softMinEvictableIdleTimeMillis is ignored). The default setting for this parameter is -1 (disabled).
numTestsPerEvictionRun determines the number of objects examined in each run of the idle object evictor. This setting has no effect unless timeBetweenEvictionRunsMillis > 0. The default setting for this parameter is 3.

The pool can be configured to behave as a LIFO queue with respect to idle objects - always returning the most recently used object from the pool, or as a FIFO queue, where borrowObject always returns the oldest object in the idle object pool.

lifo determines whether or not the pool returns idle objects in last-in-first-out order. The default setting for this parameter is true.

GenericObjectPool is not usable without a PoolableObjectFactory. A non-null factory must be provided either as a constructor argument or via a call to setFactory(org.apache.commons.pool.PoolableObjectFactory) before the pool is used.

Implementation note: To prevent possible deadlocks, care has been taken to ensure that no call to a factory method will occur within a synchronization block. See POOL-125 and DBCP-44 for more information.

Since:: Pool 1.0
Version:: $Revision: 784441 $ $Date: 2009-06-13 13:42:28 -0400 (Sat, 13 Jun 2009) $
Author:: Rodney Waldhoff, Dirk Verbeeck, Sandy McArthur
See Also:: GenericKeyedObjectPool

Nested Class Summary
`static class`	`GenericObjectPool.Config` A simple "struct" encapsulating the configuration information for a `GenericObjectPool`.

Field Summary
`static boolean`	`DEFAULT_LIFO` The default LIFO status.
`static int`	`DEFAULT_MAX_ACTIVE` The default cap on the total number of active instances from the pool.
`static int`	`DEFAULT_MAX_IDLE` The default cap on the number of "sleeping" instances in the pool.
`static long`	`DEFAULT_MAX_WAIT` The default maximum amount of time (in milliseconds) the `borrowObject()` method should block before throwing an exception when the pool is exhausted and the `"when exhausted" action` is `WHEN_EXHAUSTED_BLOCK`.
`static long`	`DEFAULT_MIN_EVICTABLE_IDLE_TIME_MILLIS` The default value for `getMinEvictableIdleTimeMillis()`.
`static int`	`DEFAULT_MIN_IDLE` The default minimum number of "sleeping" instances in the pool before before the evictor thread (if active) spawns new objects.
`static int`	`DEFAULT_NUM_TESTS_PER_EVICTION_RUN` The default number of objects to examine per run in the idle object evictor.
`static long`	`DEFAULT_SOFT_MIN_EVICTABLE_IDLE_TIME_MILLIS` The default value for `getSoftMinEvictableIdleTimeMillis()`.
`static boolean`	`DEFAULT_TEST_ON_BORROW` The default "test on borrow" value.
`static boolean`	`DEFAULT_TEST_ON_RETURN` The default "test on return" value.
`static boolean`	`DEFAULT_TEST_WHILE_IDLE` The default "test while idle" value.
`static long`	`DEFAULT_TIME_BETWEEN_EVICTION_RUNS_MILLIS` The default "time between eviction runs" value.
`static byte`	`DEFAULT_WHEN_EXHAUSTED_ACTION` The default "when exhausted action" for the pool.
`static byte`	`WHEN_EXHAUSTED_BLOCK` A "when exhausted action" type indicating that when the pool is exhausted (i.e., the maximum number of active objects has been reached), the `borrowObject()` method should block until a new object is available, or the `maximum wait time` has been reached.
`static byte`	`WHEN_EXHAUSTED_FAIL` A "when exhausted action" type indicating that when the pool is exhausted (i.e., the maximum number of active objects has been reached), the `borrowObject()` method should fail, throwing a `NoSuchElementException`.
`static byte`	`WHEN_EXHAUSTED_GROW` A "when exhausted action" type indicating that when the pool is exhausted (i.e., the maximum number of active objects has been reached), the `borrowObject()` method should simply create a new object anyway.

Constructor Summary
`GenericObjectPool()` Create a new `GenericObjectPool` with default properties.
`GenericObjectPool(PoolableObjectFactory factory)` Create a new `GenericObjectPool` using the specified factory.
`GenericObjectPool(PoolableObjectFactory factory, GenericObjectPool.Config config)` Create a new `GenericObjectPool` using the specified values.
`GenericObjectPool(PoolableObjectFactory factory, int maxActive)` Create a new `GenericObjectPool` using the specified values.
`GenericObjectPool(PoolableObjectFactory factory, int maxActive, byte whenExhaustedAction, long maxWait)` Create a new `GenericObjectPool` using the specified values.
`GenericObjectPool(PoolableObjectFactory factory, int maxActive, byte whenExhaustedAction, long maxWait, boolean testOnBorrow, boolean testOnReturn)` Create a new `GenericObjectPool` using the specified values.
`GenericObjectPool(PoolableObjectFactory factory, int maxActive, byte whenExhaustedAction, long maxWait, int maxIdle)` Create a new `GenericObjectPool` using the specified values.
`GenericObjectPool(PoolableObjectFactory factory, int maxActive, byte whenExhaustedAction, long maxWait, int maxIdle, boolean testOnBorrow, boolean testOnReturn)` Create a new `GenericObjectPool` using the specified values.
`GenericObjectPool(PoolableObjectFactory factory, int maxActive, byte whenExhaustedAction, long maxWait, int maxIdle, boolean testOnBorrow, boolean testOnReturn, long timeBetweenEvictionRunsMillis, int numTestsPerEvictionRun, long minEvictableIdleTimeMillis, boolean testWhileIdle)` Create a new `GenericObjectPool` using the specified values.
`GenericObjectPool(PoolableObjectFactory factory, int maxActive, byte whenExhaustedAction, long maxWait, int maxIdle, int minIdle, boolean testOnBorrow, boolean testOnReturn, long timeBetweenEvictionRunsMillis, int numTestsPerEvictionRun, long minEvictableIdleTimeMillis, boolean testWhileIdle)` Create a new `GenericObjectPool` using the specified values.
`GenericObjectPool(PoolableObjectFactory factory, int maxActive, byte whenExhaustedAction, long maxWait, int maxIdle, int minIdle, boolean testOnBorrow, boolean testOnReturn, long timeBetweenEvictionRunsMillis, int numTestsPerEvictionRun, long minEvictableIdleTimeMillis, boolean testWhileIdle, long softMinEvictableIdleTimeMillis)` Create a new `GenericObjectPool` using the specified values.
`GenericObjectPool(PoolableObjectFactory factory, int maxActive, byte whenExhaustedAction, long maxWait, int maxIdle, int minIdle, boolean testOnBorrow, boolean testOnReturn, long timeBetweenEvictionRunsMillis, int numTestsPerEvictionRun, long minEvictableIdleTimeMillis, boolean testWhileIdle, long softMinEvictableIdleTimeMillis, boolean lifo)` Create a new `GenericObjectPool` using the specified values.

Method Summary
`void`	`addObject()` Create an object, and place it into the pool.
`Object`	`borrowObject()` Borrows an object from the pool.
`void`	`clear()` Clears any objects sitting idle in the pool.
`void`	`close()` Closes the pool.
`void`	`evict()` Perform `numTests` idle object eviction tests, evicting examined objects that meet the criteria for eviction.
`boolean`	`getLifo()` Whether or not the idle object pool acts as a LIFO queue.
`int`	`getMaxActive()` Returns the maximum number of objects that can be allocated by the pool (checked out to clients, or idle awaiting checkout) at a given time.
`int`	`getMaxIdle()` Returns the cap on the number of "idle" instances in the pool.
`long`	`getMaxWait()` Returns the maximum amount of time (in milliseconds) the `borrowObject()` method should block before throwing an exception when the pool is exhausted and the `"when exhausted" action` is `WHEN_EXHAUSTED_BLOCK`.
`long`	`getMinEvictableIdleTimeMillis()` Returns 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).
`int`	`getMinIdle()` Returns the minimum number of objects allowed in the pool before the evictor thread (if active) spawns new objects.
`int`	`getNumActive()` Return the number of instances currently borrowed from this pool.
`int`	`getNumIdle()` Return the number of instances currently idle in this pool.
`int`	`getNumTestsPerEvictionRun()` Returns the max number of objects to examine during each run of the idle object evictor thread (if any).
`long`	`getSoftMinEvictableIdleTimeMillis()` Returns 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), with the extra condition that at least "minIdle" amount of object remain in the pool.
`boolean`	`getTestOnBorrow()` When `true`, objects will be `validated` before being returned by the `borrowObject()` method.
`boolean`	`getTestOnReturn()` When `true`, objects will be `validated` before being returned to the pool within the `returnObject(java.lang.Object)`.
`boolean`	`getTestWhileIdle()` When `true`, objects will be `validated` by the idle object evictor (if any).
`long`	`getTimeBetweenEvictionRunsMillis()` Returns the number of milliseconds to sleep between runs of the idle object evictor thread.
`byte`	`getWhenExhaustedAction()` Returns the action to take when the `borrowObject()` method is invoked when the pool is exhausted (the maximum number of "active" objects has been reached).
`void`	`invalidateObject(Object obj)` Invalidates the given object instance.
`void`	`returnObject(Object obj)` Returns an object instance to the pool.
`void`	`setConfig(GenericObjectPool.Config conf)` Sets my configuration.
`void`	`setFactory(PoolableObjectFactory factory)` Sets the `factory` this pool uses to create new instances.
`void`	`setLifo(boolean lifo)` Sets the LIFO property of the pool.
`void`	`setMaxActive(int maxActive)` 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.
`void`	`setMaxIdle(int maxIdle)` Sets the cap on the number of "idle" instances in the pool.
`void`	`setMaxWait(long maxWait)` Sets the maximum amount of time (in milliseconds) the `borrowObject()` method should block before throwing an exception when the pool is exhausted and the `"when exhausted" action` is `WHEN_EXHAUSTED_BLOCK`.
`void`	`setMinEvictableIdleTimeMillis(long minEvictableIdleTimeMillis)` 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).
`void`	`setMinIdle(int minIdle)` Sets the minimum number of objects allowed in the pool before the evictor thread (if active) spawns new objects.
`void`	`setNumTestsPerEvictionRun(int numTestsPerEvictionRun)` Sets the max number of objects to examine during each run of the idle object evictor thread (if any).
`void`	`setSoftMinEvictableIdleTimeMillis(long softMinEvictableIdleTimeMillis)` 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), with the extra condition that at least "minIdle" object instances remain in the pool.
`void`	`setTestOnBorrow(boolean testOnBorrow)` When `true`, objects will be `validated` before being returned by the `borrowObject()` method.
`void`	`setTestOnReturn(boolean testOnReturn)` When `true`, objects will be `validated` before being returned to the pool within the `returnObject(java.lang.Object)`.
`void`	`setTestWhileIdle(boolean testWhileIdle)` When `true`, objects will be `validated` by the idle object evictor (if any).
`void`	`setTimeBetweenEvictionRunsMillis(long timeBetweenEvictionRunsMillis)` Sets the number of milliseconds to sleep between runs of the idle object evictor thread.
`void`	`setWhenExhaustedAction(byte whenExhaustedAction)` Sets the action to take when the `borrowObject()` method is invoked when the pool is exhausted (the maximum number of "active" objects has been reached).
`protected void`	`startEvictor(long delay)` Start the eviction thread or service, or when delay is non-positive, stop it if it is already running.

Methods inherited from class org.apache.commons.pool.BaseObjectPool
`assertOpen, isClosed`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

WHEN_EXHAUSTED_FAIL

public static final byte WHEN_EXHAUSTED_FAIL

A "when exhausted action" type indicating that when the pool is exhausted (i.e., the maximum number of active objects has been reached), the borrowObject() method should fail, throwing a NoSuchElementException.

See Also:: WHEN_EXHAUSTED_BLOCK, WHEN_EXHAUSTED_GROW, setWhenExhaustedAction(byte), Constant Field Values

WHEN_EXHAUSTED_BLOCK

public static final byte WHEN_EXHAUSTED_BLOCK

A "when exhausted action" type indicating that when the pool is exhausted (i.e., the maximum number of active objects has been reached), the borrowObject() method should block until a new object is available, or the maximum wait time has been reached.

See Also:: WHEN_EXHAUSTED_FAIL, WHEN_EXHAUSTED_GROW, setMaxWait(long), getMaxWait(), setWhenExhaustedAction(byte), Constant Field Values

WHEN_EXHAUSTED_GROW

public static final byte WHEN_EXHAUSTED_GROW

A "when exhausted action" type indicating that when the pool is exhausted (i.e., the maximum number of active objects has been reached), the borrowObject() method should simply create a new object anyway.

See Also:: WHEN_EXHAUSTED_FAIL, WHEN_EXHAUSTED_GROW, setWhenExhaustedAction(byte), Constant Field Values

DEFAULT_MAX_IDLE

public static final int DEFAULT_MAX_IDLE

The default cap on the number of "sleeping" instances in the pool.

See Also:: getMaxIdle(), setMaxIdle(int), Constant Field Values

DEFAULT_MIN_IDLE

public static final int DEFAULT_MIN_IDLE

The default minimum number of "sleeping" instances in the pool before before the evictor thread (if active) spawns new objects.

See Also:: getMinIdle(), setMinIdle(int), Constant Field Values

DEFAULT_MAX_ACTIVE

public static final int DEFAULT_MAX_ACTIVE

The default cap on the total number of active instances from the pool.

See Also:: getMaxActive(), Constant Field Values

DEFAULT_WHEN_EXHAUSTED_ACTION

public static final byte DEFAULT_WHEN_EXHAUSTED_ACTION

The default "when exhausted action" for the pool.

See Also:: WHEN_EXHAUSTED_BLOCK, WHEN_EXHAUSTED_FAIL, WHEN_EXHAUSTED_GROW, setWhenExhaustedAction(byte), Constant Field Values

DEFAULT_LIFO

public static final boolean DEFAULT_LIFO

The default LIFO status. True means that borrowObject returns the most recently used ("last in") idle object in the pool (if there are idle instances available). False means that the pool behaves as a FIFO queue - objects are taken from the idle object pool in the order that they are returned to the pool.

Since:: 1.4
See Also:: setLifo(boolean), Constant Field Values

DEFAULT_MAX_WAIT

public static final long DEFAULT_MAX_WAIT

The default maximum amount of time (in milliseconds) the borrowObject() method should block before throwing an exception when the pool is exhausted and the "when exhausted" action is WHEN_EXHAUSTED_BLOCK.

See Also:: getMaxWait(), setMaxWait(long), Constant Field Values

DEFAULT_TEST_ON_BORROW

public static final boolean DEFAULT_TEST_ON_BORROW

The default "test on borrow" value.

See Also:: getTestOnBorrow(), setTestOnBorrow(boolean), Constant Field Values

DEFAULT_TEST_ON_RETURN

public static final boolean DEFAULT_TEST_ON_RETURN

The default "test on return" value.

See Also:: getTestOnReturn(), setTestOnReturn(boolean), Constant Field Values

DEFAULT_TEST_WHILE_IDLE

public static final boolean DEFAULT_TEST_WHILE_IDLE

The default "test while idle" value.

See Also:: getTestWhileIdle(), setTestWhileIdle(boolean), getTimeBetweenEvictionRunsMillis(), setTimeBetweenEvictionRunsMillis(long), Constant Field Values

DEFAULT_TIME_BETWEEN_EVICTION_RUNS_MILLIS

public static final long DEFAULT_TIME_BETWEEN_EVICTION_RUNS_MILLIS

The default "time between eviction runs" value.

See Also:: getTimeBetweenEvictionRunsMillis(), setTimeBetweenEvictionRunsMillis(long), Constant Field Values

DEFAULT_NUM_TESTS_PER_EVICTION_RUN

public static final int DEFAULT_NUM_TESTS_PER_EVICTION_RUN

The default number of objects to examine per run in the idle object evictor.

See Also:: getNumTestsPerEvictionRun(), setNumTestsPerEvictionRun(int), getTimeBetweenEvictionRunsMillis(), setTimeBetweenEvictionRunsMillis(long), Constant Field Values

DEFAULT_MIN_EVICTABLE_IDLE_TIME_MILLIS

public static final long DEFAULT_MIN_EVICTABLE_IDLE_TIME_MILLIS

The default value for getMinEvictableIdleTimeMillis().

See Also:: getMinEvictableIdleTimeMillis(), setMinEvictableIdleTimeMillis(long), Constant Field Values

DEFAULT_SOFT_MIN_EVICTABLE_IDLE_TIME_MILLIS

public static final long DEFAULT_SOFT_MIN_EVICTABLE_IDLE_TIME_MILLIS

The default value for getSoftMinEvictableIdleTimeMillis().

See Also:: getSoftMinEvictableIdleTimeMillis(), setSoftMinEvictableIdleTimeMillis(long), Constant Field Values

Constructor Detail

GenericObjectPool

public GenericObjectPool()

Create a new GenericObjectPool with default properties.

GenericObjectPool

public GenericObjectPool(PoolableObjectFactory factory)

Create a new GenericObjectPool using the specified factory.

Parameters:: factory - the (possibly null)PoolableObjectFactory to use to create, validate and destroy objects