Java Doc for GenericObjectPool.java in  » Web-Crawler » heritrix » org » apache » commons » pool » impl » Java Source Code / Java DocumentationJava Source Code and Java Documentation

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

A GenericObjectPool provides a number of configurable parameters:

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

• GenericObjectPool.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.
• GenericObjectPool.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.
• GenericObjectPool.setTestWhileIdle testWhileIdle indicates whether or not idle objects should be validated using the factory's PoolableObjectFactory.validateObject method. Objects that fail to validate will be dropped from the pool.

GenericObjectPool is not usable without a PoolableObjectFactory . A non-null factory must be provided either as a constructor argument or via a call to GenericObjectPool.setFactory before the pool is used.
See Also:   GenericKeyedObjectPool
author:
   Rodney Waldhoff
author:
   Dirk Verbeeck
version:
   $Revision: 4672 $ $Date: 2006-09-27 00:03:16 +0000 (Wed, 27 Sep 2006) $

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

When a negative value is supplied, ceil( GenericObjectPool.getNumIdle )/abs( GenericObjectPool.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:   GenericObjectPool.getNumTestsPerEvictionRun
See Also:   GenericObjectPool.setTimeBetweenEvictionRunsMillis