When coupled with the appropriate KeyedPoolableObjectFactory , GenericKeyedObjectPool provides robust pooling functionality for arbitrary objects.

A GenericKeyedObjectPool provides a number of configurable parameters:

• maxActive controls the maximum number of objects (per key) that can be borrowed from the pool at one time. When non-positive, there is no limit to the number of objects that may be active at one time. When maxActive is exceeded, the pool is said to be exhausted.
• maxIdle controls the maximum number of objects that can sit idle in the pool (per key) at any time. When negative, there is no limit to the number of objects that may be idle at one time.
• whenExhaustedAction specifies the behaviour of the borrowObject(Object) method when the pool is exhausted:
  • When whenExhaustedAction is WHEN_EXHAUSTED_FAIL , borrowObject(Object) will throw a NoSuchElementException
  • When whenExhaustedAction is WHEN_EXHAUSTED_GROW , borrowObject(Object) will create a new object and return it(essentially making maxActive meaningless.)
  • When whenExhaustedAction is WHEN_EXHAUSTED_BLOCK , borrowObject(Object) will block (invoke wait(long) until a new or idle object is available. If a positive maxWait value is supplied, the borrowObject(Object) will block for at most that many milliseconds, after which a NoSuchElementException will be thrown. If maxWait is non-positive, the borrowObject(Object) method will block indefinitely.
• When testOnBorrow is set, the pool will attempt to validate each object before it is returned from the borrowObject(Object) method. (Using the provided factory's validateObject(Object, Object) method.) Objects that fail to validate will be dropped from the pool, and a different object will be borrowed.
• When testOnReturn is set, the pool will attempt to validate each object before it is returned to the pool in the returnObject(Object, Object) method. (Using the provided factory's validateObject(Object, Object) method.) Objects that fail to validate will be dropped from the pool.

Optionally, one may configure the pool to examine and possibly evict objects as they sit idle in the pool. This is performed by an "idle object eviction" thread, which runs asychronously. 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.
• minEvictableIdleTimeMillis specifies the minimum amount of time that an object may sit idle in the pool before it is eligable for eviction due to idle time. When non-positive, no object will be dropped from the pool due to idle time alone.
• testWhileIdle indicates whether or not idle objects should be validated using the factory's validateObject(Object, Object) method. Objects that fail to validate will be dropped from the pool.

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