Java Doc for GenericKeyedObjectPool.java in  » Database-JDBC-Connection-Pool » Apache-commons-pool-1.3 » org » apache » commons » pool » impl » Java Source Code / Java DocumentationJava Source Code and Java Documentation

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

A GenericKeyedObjectPool provides a number of configurable parameters:

• GenericKeyedObjectPool.setMaxActive 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 GenericKeyedObjectPool.setMaxActive maxActive is exceeded, the pool is said to be exhausted.
• GenericKeyedObjectPool.setMaxIdle 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.
• GenericKeyedObjectPool.setWhenExhaustedAction whenExhaustedAction specifies the behaviour of the GenericKeyedObjectPool.borrowObject method when the pool is exhausted:
  • When GenericKeyedObjectPool.setWhenExhaustedAction whenExhaustedAction is GenericKeyedObjectPool.WHEN_EXHAUSTED_FAIL , GenericKeyedObjectPool.borrowObject will throw a NoSuchElementException
  • When GenericKeyedObjectPool.setWhenExhaustedAction whenExhaustedAction is GenericKeyedObjectPool.WHEN_EXHAUSTED_GROW , GenericKeyedObjectPool.borrowObject will create a new object and return it(essentially making GenericKeyedObjectPool.setMaxActive maxActive meaningless.)
  • When GenericKeyedObjectPool.setWhenExhaustedAction whenExhaustedAction is GenericKeyedObjectPool.WHEN_EXHAUSTED_BLOCK , GenericKeyedObjectPool.borrowObject will block (invoke Object.wait until a new or idle object is available. If a positive GenericKeyedObjectPool.setMaxWait maxWait value is supplied, the GenericKeyedObjectPool.borrowObject will block for at most that many milliseconds, after which a NoSuchElementException will be thrown. If GenericKeyedObjectPool.setMaxWait maxWait is non-positive, the GenericKeyedObjectPool.borrowObject method will block indefinitely.
• When GenericKeyedObjectPool.setTestOnBorrow testOnBorrow is set, the pool will attempt to validate each object before it is returned from the GenericKeyedObjectPool.borrowObject method. (Using the provided factory's KeyedPoolableObjectFactory.validateObject method.) Objects that fail to validate will be dropped from the pool, and a different object will be borrowed.
• When GenericKeyedObjectPool.setTestOnReturn testOnReturn is set, the pool will attempt to validate each object before it is returned to the pool in the GenericKeyedObjectPool.returnObject method. (Using the provided factory's KeyedPoolableObjectFactory.validateObject 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:

• GenericKeyedObjectPool.setTimeBetweenEvictionRunsMillis timeBetweenEvictionRunsMillis indicates how long the eviction thread should sleep before "runs" of examining idle objects. When non-positive, no eviction thread will be launched.
• GenericKeyedObjectPool.setMinEvictableIdleTimeMillis 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.
• GenericKeyedObjectPool.setTestWhileIdle testWhileIdle indicates whether or not idle objects should be validated using the factory's KeyedPoolableObjectFactory.validateObject 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 GenericKeyedObjectPool.setFactory before the pool is used.

When a negative value is supplied, ceil( GenericKeyedObjectPool.getNumIdle )/abs( GenericKeyedObjectPool.getNumTestsPerEvictionRun ) tests will be run.

When a negative value is supplied, ceil( GenericKeyedObjectPool.getNumIdle )/abs( GenericKeyedObjectPool.getNumTestsPerEvictionRun ) tests will be run. I.e., when the value is -n, roughly one nth of the idle objects will be tested per run.
See Also:   GenericKeyedObjectPool.getNumTestsPerEvictionRun
See Also:   GenericKeyedObjectPool.setTimeBetweenEvictionRunsMillis