| java.lang.Object
 org.apache.commons.pool.BaseObjectPool
org.apache.commons.pool.impl.GenericObjectPool
| GenericObjectPool | | public class GenericObjectPool extends BaseObjectPool implements ObjectPool(Code) | | 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:
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 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: 390563 $ $Date: 2006-03-31 20:28:14 -0500 (Fri, 31 Mar 2006) $ |
| Inner Class :public static class Config | |
| Constructor Summary | |
| public | GenericObjectPool()
Create a new GenericObjectPool. | | public | GenericObjectPool(PoolableObjectFactory factory)
Create a new GenericObjectPool using the specified values. | | public | GenericObjectPool(PoolableObjectFactory factory, GenericObjectPool.Config config)
Create a new GenericObjectPool using the specified values. | | public | GenericObjectPool(PoolableObjectFactory factory, int maxActive)
Create a new GenericObjectPool using the specified values. | | public | GenericObjectPool(PoolableObjectFactory factory, int maxActive, byte whenExhaustedAction, long maxWait)
Create a new GenericObjectPool using the specified values. | | public | GenericObjectPool(PoolableObjectFactory factory, int maxActive, byte whenExhaustedAction, long maxWait, boolean testOnBorrow, boolean testOnReturn)
Create a new GenericObjectPool using the specified values. | | public | GenericObjectPool(PoolableObjectFactory factory, int maxActive, byte whenExhaustedAction, long maxWait, int maxIdle)
Create a new GenericObjectPool using the specified values. | | public | GenericObjectPool(PoolableObjectFactory factory, int maxActive, byte whenExhaustedAction, long maxWait, int maxIdle, boolean testOnBorrow, boolean testOnReturn)
Create a new GenericObjectPool using the specified values. | | public | 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. | | public | 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. | | public | 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.
Parameters:
factory - the (possibly null)PoolableObjectFactory to use to create, validate and destroy objects
Parameters:
maxActive - the maximum number of objects that can be borrowed from me at one time (see GenericObjectPool.setMaxActive)
Parameters:
whenExhaustedAction - the action to take when the pool is exhausted (see GenericObjectPool.setWhenExhaustedAction)
Parameters:
maxWait - the maximum amount of time to wait for an idle object when the pool is exhausted an and whenExhaustedAction is GenericObjectPool.WHEN_EXHAUSTED_BLOCK (otherwise ignored) (see GenericObjectPool.setMaxWait)
Parameters:
maxIdle - the maximum number of idle objects in my pool (see GenericObjectPool.setMaxIdle)
Parameters:
minIdle - the minimum number of idle objects in my pool (see GenericObjectPool.setMinIdle)
Parameters:
testOnBorrow - whether or not to validate objects before they are returned by the GenericObjectPool.borrowObject method (see GenericObjectPool.setTestOnBorrow)
Parameters:
testOnReturn - whether or not to validate objects after they are returned to the GenericObjectPool.returnObject method (see GenericObjectPool.setTestOnReturn)
Parameters:
timeBetweenEvictionRunsMillis - the amount of time (in milliseconds) to sleep between examining idle objects for eviction (see GenericObjectPool.setTimeBetweenEvictionRunsMillis)
Parameters:
numTestsPerEvictionRun - the number of idle objects to examine per run within the idle object eviction thread (if any) (see GenericObjectPool.setNumTestsPerEvictionRun)
Parameters:
minEvictableIdleTimeMillis - the minimum number of milliseconds an object can sit idle in the pool before it is eligable for evcition (see GenericObjectPool.setMinEvictableIdleTimeMillis)
Parameters:
testWhileIdle - whether or not to validate objects in the idle object eviction thread, if any (see GenericObjectPool.setTestWhileIdle)
Parameters:
softMinEvictableIdleTimeMillis - the minimum number of milliseconds an object can sit idle in the pool before it is eligable for evcition with the extra condition that at least "minIdle" amount of object remain in the pool. |
| Method Summary | |
| public synchronized void | addObject()
Create an object, and place it into the pool. | | public synchronized Object | borrowObject()
| | public synchronized void | clear()
| | public synchronized void | close()
| | synchronized String | debugInfo()
| | public synchronized void | evict()
| | public synchronized int | getMaxActive()
Returns the cap on the total number of active instances from my pool. | | public synchronized int | getMaxIdle()
Returns the cap on the number of "idle" instances in the pool. | | public synchronized long | getMaxWait()
Returns the maximum amount of time (in milliseconds) the
GenericObjectPool.borrowObject method should block before throwing
an exception when the pool is exhausted and the
GenericObjectPool.setWhenExhaustedAction "when exhausted" action is
GenericObjectPool.WHEN_EXHAUSTED_BLOCK . | | public synchronized long | getMinEvictableIdleTimeMillis()
Returns the minimum amount of time an object may sit idle in the pool
before it is eligable for eviction by the idle object evictor
(if any). | | public synchronized int | getMinIdle()
Returns the minimum number of objects allowed in the pool
before the evictor thread (if active) spawns new objects. | | public synchronized int | getNumActive()
| | public synchronized int | getNumIdle()
| | public synchronized int | getNumTestsPerEvictionRun()
Returns the max number of objects to examine during each run of the
idle object evictor thread (if any). | | public synchronized long | getSoftMinEvictableIdleTimeMillis()
Returns the minimum amount of time an object may sit idle in the pool
before it is eligable for eviction by the idle object evictor
(if any), with the extra condition that at least
"minIdle" amount of object remain in the pool. | | public synchronized boolean | getTestOnBorrow()
When true, objects will be
PoolableObjectFactory.validateObject validated before being returned by the
GenericObjectPool.borrowObject method. | | public synchronized boolean | getTestOnReturn()
When true, objects will be
PoolableObjectFactory.validateObject validated before being returned to the pool within the
GenericObjectPool.returnObject . | | public synchronized boolean | getTestWhileIdle()
When true, objects will be
PoolableObjectFactory.validateObject validated by the idle object evictor (if any). | | public synchronized long | getTimeBetweenEvictionRunsMillis()
Returns the number of milliseconds to sleep between runs of the
idle object evictor thread. | | public synchronized byte | getWhenExhaustedAction()
Returns the action to take when the
GenericObjectPool.borrowObject method
is invoked when the pool is exhausted (the maximum number
of "active" objects has been reached). | | public synchronized void | invalidateObject(Object obj)
| | public synchronized void | returnObject(Object obj)
| | public synchronized void | setConfig(GenericObjectPool.Config conf)
Sets my configuration. | | public synchronized void | setFactory(PoolableObjectFactory factory)
| | public synchronized void | setMaxActive(int maxActive)
Sets the cap on the total number of active instances from my pool. | | public synchronized void | setMaxIdle(int maxIdle)
Sets the cap on the number of "idle" instances in the pool. | | public synchronized void | setMaxWait(long maxWait)
Sets the maximum amount of time (in milliseconds) the
GenericObjectPool.borrowObject method should block before throwing
an exception when the pool is exhausted and the
GenericObjectPool.setWhenExhaustedAction "when exhausted" action is
GenericObjectPool.WHEN_EXHAUSTED_BLOCK . | | public synchronized void | setMinEvictableIdleTimeMillis(long minEvictableIdleTimeMillis)
Sets the minimum amount of time an object may sit idle in the pool
before it is eligable for eviction by the idle object evictor
(if any). | | public synchronized void | setMinIdle(int minIdle)
Sets the minimum number of objects allowed in the pool
before the evictor thread (if active) spawns new objects. | | public synchronized void | setNumTestsPerEvictionRun(int numTestsPerEvictionRun)
Sets the max number of objects to examine during each run of the
idle object evictor thread (if any).
When a negative value is supplied, ceil(
GenericObjectPool.getNumIdle )/abs(
GenericObjectPool.getNumTestsPerEvictionRun )
tests will be run. | | public synchronized void | setSoftMinEvictableIdleTimeMillis(long softMinEvictableIdleTimeMillis)
Sets the minimum amount of time an object may sit idle in the pool
before it is eligable for eviction by the idle object evictor
(if any), with the extra condition that at least
"minIdle" amount of object remain in the pool. | | public synchronized void | setTestOnBorrow(boolean testOnBorrow)
When true, objects will be
PoolableObjectFactory.validateObject validated before being returned by the
GenericObjectPool.borrowObject method. | | public synchronized void | setTestOnReturn(boolean testOnReturn)
When true, objects will be
PoolableObjectFactory.validateObject validated before being returned to the pool within the
GenericObjectPool.returnObject . | | public synchronized void | setTestWhileIdle(boolean testWhileIdle)
When true, objects will be
PoolableObjectFactory.validateObject validated by the idle object evictor (if any). | | public synchronized void | setTimeBetweenEvictionRunsMillis(long timeBetweenEvictionRunsMillis)
Sets the number of milliseconds to sleep between runs of the
idle object evictor thread. | | public synchronized void | setWhenExhaustedAction(byte whenExhaustedAction)
Sets the action to take when the
GenericObjectPool.borrowObject method
is invoked when the pool is exhausted (the maximum number
of "active" objects has been reached). | | protected synchronized void | startEvictor(long delay)
Start the eviction thread or service, or when
delay is non-positive, stop it
if it is already running. |
| GenericObjectPool | | public GenericObjectPool()(Code) | | Create a new GenericObjectPool.
|
| GenericObjectPool | | public GenericObjectPool(PoolableObjectFactory factory)(Code) | | Create a new GenericObjectPool using the specified values.
Parameters:
factory - the (possibly null)PoolableObjectFactory to use to create, validate and destroy objects |
| GenericObjectPool | | public GenericObjectPool(PoolableObjectFactory factory, int maxActive)(Code) | | Create a new GenericObjectPool using the specified values.
Parameters:
factory - the (possibly null)PoolableObjectFactory to use to create, validate and destroy objects
Parameters:
maxActive - the maximum number of objects that can be borrowed from me at one time (see GenericObjectPool.setMaxActive) |
| GenericObjectPool | | public GenericObjectPool(PoolableObjectFactory factory, int maxActive, byte whenExhaustedAction, long maxWait, int maxIdle, boolean testOnBorrow, boolean testOnReturn, long timeBetweenEvictionRunsMillis, int numTestsPerEvictionRun, long minEvictableIdleTimeMillis, boolean testWhileIdle)(Code) | | Create a new GenericObjectPool using the specified values.
Parameters:
factory - the (possibly null)PoolableObjectFactory to use to create, validate and destroy objects
Parameters:
maxActive - the maximum number of objects that can be borrowed from me at one time (see GenericObjectPool.setMaxActive)
Parameters:
whenExhaustedAction - the action to take when the pool is exhausted (see GenericObjectPool.setWhenExhaustedAction)
Parameters:
maxWait - the maximum amount of time to wait for an idle object when the pool is exhausted an and whenExhaustedAction is GenericObjectPool.WHEN_EXHAUSTED_BLOCK (otherwise ignored) (see GenericObjectPool.setMaxWait)
Parameters:
maxIdle - the maximum number of idle objects in my pool (see GenericObjectPool.setMaxIdle)
Parameters:
testOnBorrow - whether or not to validate objects before they are returned by the GenericObjectPool.borrowObject method (see GenericObjectPool.setTestOnBorrow)
Parameters:
testOnReturn - whether or not to validate objects after they are returned to the GenericObjectPool.returnObject method (see GenericObjectPool.setTestOnReturn)
Parameters:
timeBetweenEvictionRunsMillis - the amount of time (in milliseconds) to sleep between examining idle objects for eviction (see GenericObjectPool.setTimeBetweenEvictionRunsMillis)
Parameters:
numTestsPerEvictionRun - the number of idle objects to examine per run within the idle object eviction thread (if any) (see GenericObjectPool.setNumTestsPerEvictionRun)
Parameters:
minEvictableIdleTimeMillis - the minimum number of milliseconds an object can sit idle in the pool before it is eligable for evcition (see GenericObjectPool.setMinEvictableIdleTimeMillis)
Parameters:
testWhileIdle - whether or not to validate objects in the idle object eviction thread, if any (see GenericObjectPool.setTestWhileIdle) |
| GenericObjectPool | | public 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)(Code) | | Create a new GenericObjectPool using the specified values.
Parameters:
factory - the (possibly null)PoolableObjectFactory to use to create, validate and destroy objects
Parameters:
maxActive - the maximum number of objects that can be borrowed from me at one time (see GenericObjectPool.setMaxActive)
Parameters:
whenExhaustedAction - the action to take when the pool is exhausted (see GenericObjectPool.setWhenExhaustedAction)
Parameters:
maxWait - the maximum amount of time to wait for an idle object when the pool is exhausted an and whenExhaustedAction is GenericObjectPool.WHEN_EXHAUSTED_BLOCK (otherwise ignored) (see GenericObjectPool.setMaxWait)
Parameters:
maxIdle - the maximum number of idle objects in my pool (see GenericObjectPool.setMaxIdle)
Parameters:
minIdle - the minimum number of idle objects in my pool (see GenericObjectPool.setMinIdle)
Parameters:
testOnBorrow - whether or not to validate objects before they are returned by the GenericObjectPool.borrowObject method (see GenericObjectPool.setTestOnBorrow)
Parameters:
testOnReturn - whether or not to validate objects after they are returned to the GenericObjectPool.returnObject method (see GenericObjectPool.setTestOnReturn)
Parameters:
timeBetweenEvictionRunsMillis - the amount of time (in milliseconds) to sleep between examining idle objects for eviction (see GenericObjectPool.setTimeBetweenEvictionRunsMillis)
Parameters:
numTestsPerEvictionRun - the number of idle objects to examine per run within the idle object eviction thread (if any) (see GenericObjectPool.setNumTestsPerEvictionRun)
Parameters:
minEvictableIdleTimeMillis - the minimum number of milliseconds an object can sit idle in the pool before it is eligable for evcition (see GenericObjectPool.setMinEvictableIdleTimeMillis)
Parameters:
testWhileIdle - whether or not to validate objects in the idle object eviction thread, if any (see GenericObjectPool.setTestWhileIdle) |
| GenericObjectPool | | public 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)(Code) | | Create a new GenericObjectPool using the specified values.
Parameters:
factory - the (possibly null)PoolableObjectFactory to use to create, validate and destroy objects
Parameters:
maxActive - the maximum number of objects that can be borrowed from me at one time (see GenericObjectPool.setMaxActive)
Parameters:
whenExhaustedAction - the action to take when the pool is exhausted (see GenericObjectPool.setWhenExhaustedAction)
Parameters:
maxWait - the maximum amount of time to wait for an idle object when the pool is exhausted an and whenExhaustedAction is GenericObjectPool.WHEN_EXHAUSTED_BLOCK (otherwise ignored) (see GenericObjectPool.setMaxWait)
Parameters:
maxIdle - the maximum number of idle objects in my pool (see GenericObjectPool.setMaxIdle)
Parameters:
minIdle - the minimum number of idle objects in my pool (see GenericObjectPool.setMinIdle)
Parameters:
testOnBorrow - whether or not to validate objects before they are returned by the GenericObjectPool.borrowObject method (see GenericObjectPool.setTestOnBorrow)
Parameters:
testOnReturn - whether or not to validate objects after they are returned to the GenericObjectPool.returnObject method (see GenericObjectPool.setTestOnReturn)
Parameters:
timeBetweenEvictionRunsMillis - the amount of time (in milliseconds) to sleep between examining idle objects for eviction (see GenericObjectPool.setTimeBetweenEvictionRunsMillis)
Parameters:
numTestsPerEvictionRun - the number of idle objects to examine per run within the idle object eviction thread (if any) (see GenericObjectPool.setNumTestsPerEvictionRun)
Parameters:
minEvictableIdleTimeMillis - the minimum number of milliseconds an object can sit idle in the pool before it is eligable for evcition (see GenericObjectPool.setMinEvictableIdleTimeMillis)
Parameters:
testWhileIdle - whether or not to validate objects in the idle object eviction thread, if any (see GenericObjectPool.setTestWhileIdle)
Parameters:
softMinEvictableIdleTimeMillis - the minimum number of milliseconds an object can sit idle in the pool before it is eligable for evcition with the extra condition that at least "minIdle" amount of object remain in the pool. (see GenericObjectPool.setSoftMinEvictableIdleTimeMillis) |
| addObject | | public synchronized void addObject() throws Exception(Code) | | Create an object, and place it into the pool.
addObject() is useful for "pre-loading" a pool with idle objects.
|
| clear | | public synchronized void clear()(Code) | | |
| getMaxActive | | public synchronized int getMaxActive()(Code) | | Returns the cap on the total number of active instances from my pool.
the cap on the total number of active instances from my pool.
See Also: GenericObjectPool.setMaxActive |
| getMaxIdle | | public synchronized int getMaxIdle()(Code) | | Returns the cap on the number of "idle" instances in the pool.
the cap on the number of "idle" instances in the pool.
See Also: GenericObjectPool.setMaxIdle |
| getMinIdle | | public synchronized int getMinIdle()(Code) | | Returns the minimum number of objects allowed in the pool
before the evictor thread (if active) spawns new objects.
(Note no objects are created when: numActive + numIdle >= maxActive)
The minimum number of objects.
See Also: GenericObjectPool.setMinIdle |
| getNumActive | | public synchronized int getNumActive()(Code) | | |
| getNumIdle | | public synchronized int getNumIdle()(Code) | | |
| getSoftMinEvictableIdleTimeMillis | | public synchronized long getSoftMinEvictableIdleTimeMillis()(Code) | | Returns the minimum amount of time an object may sit idle in the pool
before it is eligable for eviction by the idle object evictor
(if any), with the extra condition that at least
"minIdle" amount of object remain in the pool.
See Also: GenericObjectPool.setSoftMinEvictableIdleTimeMillis |
| getTimeBetweenEvictionRunsMillis | | public synchronized long getTimeBetweenEvictionRunsMillis()(Code) | | Returns 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.
See Also: GenericObjectPool.setTimeBetweenEvictionRunsMillis |
| setMaxActive | | public synchronized void setMaxActive(int maxActive)(Code) | | Sets the cap on the total number of active instances from my pool.
Parameters:
maxActive - The cap on the total number of active instances from my pool.Use a negative value for an infinite number of instances.
See Also: GenericObjectPool.getMaxActive |
| setMaxIdle | | public synchronized void setMaxIdle(int maxIdle)(Code) | | Sets the cap on the number of "idle" instances in the pool.
Parameters:
maxIdle - The cap on the number of "idle" instances in the pool.Use a negative value to indicate an unlimited numberof idle instances.
See Also: GenericObjectPool.getMaxIdle |
| setMinIdle | | public synchronized void setMinIdle(int minIdle)(Code) | | Sets the minimum number of objects allowed in the pool
before the evictor thread (if active) spawns new objects.
(Note no objects are created when: numActive + numIdle >= maxActive)
Parameters:
minIdle - The minimum number of objects.
See Also: GenericObjectPool.getMinIdle |
| setSoftMinEvictableIdleTimeMillis | | public synchronized void setSoftMinEvictableIdleTimeMillis(long softMinEvictableIdleTimeMillis)(Code) | | Sets the minimum amount of time an object may sit idle in the pool
before it is eligable for eviction by the idle object evictor
(if any), with the extra condition that at least
"minIdle" amount of object remain in the pool.
When non-positive, no objects will be evicted from the pool
due to idle time alone.
See Also: GenericObjectPool.getSoftMinEvictableIdleTimeMillis |
| setTimeBetweenEvictionRunsMillis | | public synchronized void setTimeBetweenEvictionRunsMillis(long timeBetweenEvictionRunsMillis)(Code) | | Sets 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.
See Also: GenericObjectPool.getTimeBetweenEvictionRunsMillis |
| startEvictor | | protected synchronized void startEvictor(long delay)(Code) | | Start the eviction thread or service, or when
delay is non-positive, stop it
if it is already running.
|
|
|