org.apache.commons.pool.impl
Class TapestryKeyedObjectPool

java.lang.Object
  extended by org.apache.commons.pool.BaseKeyedObjectPool
      extended by org.apache.commons.pool.impl.TapestryKeyedObjectPool
All Implemented Interfaces:
org.apache.commons.pool.KeyedObjectPool

public class TapestryKeyedObjectPool
extends org.apache.commons.pool.BaseKeyedObjectPool
implements org.apache.commons.pool.KeyedObjectPool

A configurable KeyedObjectPool implementation modifying the standard version coming with commons-pool to not lock each and every pool access which led to scalability issues and even deadlocks (TAPESTRY-2530, TAPESTRY-2382). TODO: switch back to the standard version once it works better.

When coupled with the appropriate KeyedPoolableObjectFactory, GenericKeyedObjectPool provides robust pooling functionality for keyed objects. A GenericKeyedObjectPool can be viewed as a map of pools, keyed on the (unique) key values provided to the preparePool, addObject or borrowObject methods. Each time a new key value is provided to one of these methods, a new pool is created under the given key to be managed by the containing GenericKeyedObjectPool.

A GenericKeyedObjectPool 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 and to ensure that a minimum number of idle objects is maintained for each key. 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:

The pools can be configured to behave as LIFO queues with respect to idle objects - always returning the most recently used object from the pool, or as FIFO queues, where borrowObject always returns the oldest object in the idle object 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 before the pool is used.

Since:
Pool 1.0
Version:
$Revision: 620830 $ $Date: 2008-02-12 16:41:58 +0100 (Di, 12 Feb 2008) $
Author:
Rodney Waldhoff, Dirk Verbeeck, Sandy McArthur
See Also:
GenericObjectPool

Nested Class Summary
static class TapestryKeyedObjectPool.Config
          A simple "struct" encapsulating the configuration information for a GenericKeyedObjectPool.
 
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 (per key) from the pool.
static int DEFAULT_MAX_IDLE
          The default cap on the number of idle instances (per key) in the pool.
static int DEFAULT_MAX_TOTAL
          The default cap on the the overall maximum number of objects that can exist at one time.
static long DEFAULT_MAX_WAIT
          The default maximum amount of time (in milliseconds) the borrowObject(java.lang.Object) 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 level of idle objects in the pool.
static int DEFAULT_NUM_TESTS_PER_EVICTION_RUN
          The default number of objects to examine per run in the idle object evictor.
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(java.lang.Object) 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(java.lang.Object) 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(java.lang.Object) method should simply create a new object anyway.
 
Constructor Summary
TapestryKeyedObjectPool()
          Create a new GenericKeyedObjectPool with no factory.
TapestryKeyedObjectPool(org.apache.commons.pool.KeyedPoolableObjectFactory factory)
          Create a new GenericKeyedObjectPool using the specified values.
TapestryKeyedObjectPool(org.apache.commons.pool.KeyedPoolableObjectFactory factory, org.apache.commons.pool.impl.GenericKeyedObjectPool.Config config)
          Create a new GenericKeyedObjectPool using the specified values.
TapestryKeyedObjectPool(org.apache.commons.pool.KeyedPoolableObjectFactory factory, int maxActive)
          Create a new GenericKeyedObjectPool using the specified values.
TapestryKeyedObjectPool(org.apache.commons.pool.KeyedPoolableObjectFactory factory, int maxActive, byte whenExhaustedAction, long maxWait)
          Create a new GenericKeyedObjectPool using the specified values.
TapestryKeyedObjectPool(org.apache.commons.pool.KeyedPoolableObjectFactory factory, int maxActive, byte whenExhaustedAction, long maxWait, boolean testOnBorrow, boolean testOnReturn)
          Create a new GenericKeyedObjectPool using the specified values.
TapestryKeyedObjectPool(org.apache.commons.pool.KeyedPoolableObjectFactory factory, int maxActive, byte whenExhaustedAction, long maxWait, int maxIdle)
          Create a new GenericKeyedObjectPool using the specified values.
TapestryKeyedObjectPool(org.apache.commons.pool.KeyedPoolableObjectFactory factory, int maxActive, byte whenExhaustedAction, long maxWait, int maxIdle, boolean testOnBorrow, boolean testOnReturn)
          Create a new GenericKeyedObjectPool using the specified values.
TapestryKeyedObjectPool(org.apache.commons.pool.KeyedPoolableObjectFactory factory, int maxActive, byte whenExhaustedAction, long maxWait, int maxIdle, boolean testOnBorrow, boolean testOnReturn, long timeBetweenEvictionRunsMillis, int numTestsPerEvictionRun, long minEvictableIdleTimeMillis, boolean testWhileIdle)
          Create a new GenericKeyedObjectPool using the specified values.
TapestryKeyedObjectPool(org.apache.commons.pool.KeyedPoolableObjectFactory factory, int maxActive, byte whenExhaustedAction, long maxWait, int maxIdle, int maxTotal, boolean testOnBorrow, boolean testOnReturn, long timeBetweenEvictionRunsMillis, int numTestsPerEvictionRun, long minEvictableIdleTimeMillis, boolean testWhileIdle)
          Create a new GenericKeyedObjectPool using the specified values.
TapestryKeyedObjectPool(org.apache.commons.pool.KeyedPoolableObjectFactory factory, int maxActive, byte whenExhaustedAction, long maxWait, int maxIdle, int maxTotal, int minIdle, boolean testOnBorrow, boolean testOnReturn, long timeBetweenEvictionRunsMillis, int numTestsPerEvictionRun, long minEvictableIdleTimeMillis, boolean testWhileIdle)
          Create a new GenericKeyedObjectPool using the specified values.
TapestryKeyedObjectPool(org.apache.commons.pool.KeyedPoolableObjectFactory factory, int maxActive, byte whenExhaustedAction, long maxWait, int maxIdle, int maxTotal, int minIdle, boolean testOnBorrow, boolean testOnReturn, long timeBetweenEvictionRunsMillis, int numTestsPerEvictionRun, long minEvictableIdleTimeMillis, boolean testWhileIdle, boolean lifo)
          Create a new GenericKeyedObjectPool using the specified values.
 
Method Summary
 void addObject(Object key)
          Create an object using the factory, passivate it, and then place it in the idle object pool.
 Object borrowObject(Object key)
           
 void clear()
          Clears the pool, removing all pooled instances.
 void clear(Object key)
          Clears the specified pool, removing all pooled instances corresponding to the given key.
 void clearOldest()
          Method clears oldest 15% of objects in pool.
 void close()
           
 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 pools act as LIFO queues.
 int getMaxActive()
          Returns the cap on the number of active instances per key.
 int getMaxIdle()
          Returns the cap on the number of "idle" instances per key.
 int getMaxTotal()
          Returns the overall maximum number of objects (across pools) that can exist at one time.
 long getMaxWait()
          Returns the maximum amount of time (in milliseconds) the borrowObject(java.lang.Object) 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 idle objects to maintain in each of the keyed pools.
 int getNumActive()
          Returns the total number of instances current borrowed from this pool but not yet returned.
 int getNumActive(Object key)
          Returns the number of instances currently borrowed from but not yet returned to the pool corresponding to the given key.
 int getNumIdle()
          Returns the total number of instances currently idle in this pool.
 int getNumIdle(Object key)
          Returns the number of instances corresponding to the given key currently idle in this pool.
 int getNumTestsPerEvictionRun()
          Returns the number of objects to examine during each run of the idle object evictor thread (if any).
 boolean getTestOnBorrow()
          When true, objects will be validated before being returned by the borrowObject(java.lang.Object) method.
 boolean getTestOnReturn()
          When true, objects will be validated before being returned to the pool within the returnObject(java.lang.Object, 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(java.lang.Object) method is invoked when the pool is exhausted (the maximum number of "active" objects has been reached).
 void invalidateObject(Object key, Object obj)
           
 void preparePool(Object key, boolean populateImmediately)
          Registers a key for pool control.
 void returnObject(Object key, Object obj)
           
 void setConfig(org.apache.commons.pool.impl.GenericKeyedObjectPool.Config conf)
          Sets the configuration.
 void setFactory(org.apache.commons.pool.KeyedPoolableObjectFactory factory)
           
 void setLifo(boolean lifo)
          Sets the LIFO property of the pools.
 void setMaxActive(int maxActive)
          Sets the cap on the number of active instances per key.
 void setMaxIdle(int maxIdle)
          Sets the cap on the number of "idle" instances in the pool.
 void setMaxTotal(int maxTotal)
          Sets the cap on the total number of instances from all pools combined.
 void setMaxWait(long maxWait)
          Sets the maximum amount of time (in milliseconds) the borrowObject(java.lang.Object) 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 poolSize)
          Sets the minimum number of idle objects to maintain in each of the keyed pools.
 void setNumTestsPerEvictionRun(int numTestsPerEvictionRun)
          Sets the number of objects to examine during each run of the idle object evictor thread (if any).
 void setTestOnBorrow(boolean testOnBorrow)
          When true, objects will be validated before being returned by the borrowObject(java.lang.Object) method.
 void setTestOnReturn(boolean testOnReturn)
          When true, objects will be validated before being returned to the pool within the returnObject(java.lang.Object, 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(java.lang.Object) 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.BaseKeyedObjectPool
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(java.lang.Object) 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(java.lang.Object) 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(java.lang.Object) 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 idle instances (per key) in the pool.

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

DEFAULT_MAX_ACTIVE

public static final int DEFAULT_MAX_ACTIVE
The default cap on the total number of active instances (per key) from the pool.

See Also:
getMaxActive(), setMaxActive(int), Constant Field Values

DEFAULT_MAX_TOTAL

public static final int DEFAULT_MAX_TOTAL
The default cap on the the overall maximum number of objects that can exist at one time.

See Also:
getMaxTotal(), setMaxTotal(int), 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_MAX_WAIT

public static final long DEFAULT_MAX_WAIT
The default maximum amount of time (in milliseconds) the borrowObject(java.lang.Object) 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_MIN_IDLE

public static final int DEFAULT_MIN_IDLE
The default minimum level of idle objects in the pool.

Since:
Pool 1.3
See Also:
setMinIdle(int), getMinIdle(), 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 a pool (if there are idle instances available). False means that pools behave as FIFO queues - objects are taken from idle object pools in the order that they are returned.

See Also:
setLifo(boolean), Constant Field Values
Constructor Detail

TapestryKeyedObjectPool

public TapestryKeyedObjectPool()
Create a new GenericKeyedObjectPool with no factory.

See Also:
#GenericKeyedObjectPool(KeyedPoolableObjectFactory), setFactory(KeyedPoolableObjectFactory)

TapestryKeyedObjectPool

public TapestryKeyedObjectPool(org.apache.commons.pool.KeyedPoolableObjectFactory factory)
Create a new GenericKeyedObjectPool using the specified values.

Parameters:
factory - the KeyedPoolableObjectFactory to use to create, validate, and destroy objects if not null

TapestryKeyedObjectPool

public TapestryKeyedObjectPool(org.apache.commons.pool.KeyedPoolableObjectFactory factory,
                               org.apache.commons.pool.impl.GenericKeyedObjectPool.Config config)
Create a new GenericKeyedObjectPool using the specified values.

Parameters:
factory - the KeyedPoolableObjectFactory to use to create, validate, and destroy objects if not null
config - a non-null GenericKeyedObjectPool.Config describing the configuration

TapestryKeyedObjectPool

public TapestryKeyedObjectPool(org.apache.commons.pool.KeyedPoolableObjectFactory factory,
                               int maxActive)
Create a new GenericKeyedObjectPool using the specified values.

Parameters:
factory - the KeyedPoolableObjectFactory to use to create, validate, and destroy objects if not null
maxActive - the maximum number of objects that can be borrowed from me at one time (see setMaxActive(int))

TapestryKeyedObjectPool

public TapestryKeyedObjectPool(org.apache.commons.pool.KeyedPoolableObjectFactory factory,
                               int maxActive,
                               byte whenExhaustedAction,
                               long maxWait)
Create a new GenericKeyedObjectPool using the specified values.

Parameters:
factory - the KeyedPoolableObjectFactory to use to create, validate, and destroy objects if not null
maxActive - the maximum number of objects that can be borrowed from me at one time (see setMaxActive(int))
whenExhaustedAction - the action to take when the pool is exhausted (see setWhenExhaustedAction(byte))
maxWait - the maximum amount of time to wait for an idle object when the pool is exhausted and whenExhaustedAction is WHEN_EXHAUSTED_BLOCK (otherwise ignored) (see setMaxWait(long))

TapestryKeyedObjectPool

public TapestryKeyedObjectPool(org.apache.commons.pool.KeyedPoolableObjectFactory factory,
                               int maxActive,
                               byte whenExhaustedAction,
                               long maxWait,
                               boolean testOnBorrow,
                               boolean testOnReturn)
Create a new GenericKeyedObjectPool using the specified values.

Parameters:
factory - the KeyedPoolableObjectFactory to use to create, validate, and destroy objects if not null
maxActive - the maximum number of objects that can be borrowed from me at one time (see setMaxActive(int))
maxWait - the maximum amount of time to wait for an idle object when the pool is exhausted and whenExhaustedAction is WHEN_EXHAUSTED_BLOCK (otherwise ignored) (see setMaxWait(long))
whenExhaustedAction - the action to take when the pool is exhausted (see setWhenExhaustedAction(byte))
testOnBorrow - whether or not to validate objects before they are returned by the borrowObject(java.lang.Object) method (see setTestOnBorrow(boolean))
testOnReturn - whether or not to validate objects after they are returned to the returnObject(java.lang.Object, java.lang.Object) method (see setTestOnReturn(boolean))

TapestryKeyedObjectPool

public TapestryKeyedObjectPool(org.apache.commons.pool.KeyedPoolableObjectFactory factory,
                               int maxActive,
                               byte whenExhaustedAction,
                               long maxWait,
                               int maxIdle)
Create a new GenericKeyedObjectPool using the specified values.

Parameters:
factory - the KeyedPoolableObjectFactory to use to create, validate, and destroy objects if not null
maxActive - the maximum number of objects that can be borrowed from me at one time (see setMaxActive(int))
whenExhaustedAction - the action to take when the pool is exhausted (see setWhenExhaustedAction(byte))
maxWait - the maximum amount of time to wait for an idle object when the pool is exhausted and whenExhaustedAction is WHEN_EXHAUSTED_BLOCK (otherwise ignored) (see setMaxWait(long))
maxIdle - the maximum number of idle objects in my pool (see setMaxIdle(int))

TapestryKeyedObjectPool

public TapestryKeyedObjectPool(org.apache.commons.pool.KeyedPoolableObjectFactory factory,
                               int maxActive,
                               byte whenExhaustedAction,
                               long maxWait,
                               int maxIdle,
                               boolean testOnBorrow,
                               boolean testOnReturn)
Create a new GenericKeyedObjectPool using the specified values.

Parameters:
factory - the KeyedPoolableObjectFactory to use to create, validate, and destroy objects if not null
maxActive - the maximum number of objects that can be borrowed from me at one time (see setMaxActive(int))
whenExhaustedAction - the action to take when the pool is exhausted (see setWhenExhaustedAction(byte))
maxWait - the maximum amount of time to wait for an idle object when the pool is exhausted and whenExhaustedAction is WHEN_EXHAUSTED_BLOCK (otherwise ignored) (see getMaxWait())
maxIdle - the maximum number of idle objects in my pool (see setMaxIdle(int))
testOnBorrow - whether or not to validate objects before they are returned by the borrowObject(java.lang.Object) method (see setTestOnBorrow(boolean))
testOnReturn - whether or not to validate objects after they are returned to the returnObject(java.lang.Object, java.lang.Object) method (see setTestOnReturn(boolean))

TapestryKeyedObjectPool

public TapestryKeyedObjectPool(org.apache.commons.pool.KeyedPoolableObjectFactory factory,
                               int maxActive,
                               byte whenExhaustedAction,
                               long maxWait,
                               int maxIdle,
                               boolean testOnBorrow,
                               boolean testOnReturn,
                               long timeBetweenEvictionRunsMillis,
                               int numTestsPerEvictionRun,
                               long minEvictableIdleTimeMillis,
                               boolean testWhileIdle)
Create a new GenericKeyedObjectPool using the specified values.

Parameters:
factory - the KeyedPoolableObjectFactory to use to create, validate, and destroy objects if not null
maxActive - the maximum number of objects that can be borrowed from me at one time (see setMaxActive(int))
whenExhaustedAction - the action to take when the pool is exhausted (see setWhenExhaustedAction(byte))
maxWait - the maximum amount of time to wait for an idle object when the pool is exhausted and whenExhaustedAction is WHEN_EXHAUSTED_BLOCK (otherwise ignored) (see setMaxWait(long))
maxIdle - the maximum number of idle objects in my pool (see setMaxIdle(int))
testOnBorrow - whether or not to validate objects before they are returned by the borrowObject(java.lang.Object) method (see setTestOnBorrow(boolean))
testOnReturn - whether or not to validate objects after they are returned to the returnObject(java.lang.Object, java.lang.Object) method (see setTestOnReturn(boolean))
timeBetweenEvictionRunsMillis - the amount of time (in milliseconds) to sleep between examining idle objects for eviction (see setTimeBetweenEvictionRunsMillis(long))
numTestsPerEvictionRun - the number of idle objects to examine per run within the idle object eviction thread (if any) (see setNumTestsPerEvictionRun(int))
minEvictableIdleTimeMillis - the minimum number of milliseconds an object can sit idle in the pool before it is eligible for eviction (see setMinEvictableIdleTimeMillis(long))
testWhileIdle - whether or not to validate objects in the idle object eviction thread, if any (see setTestWhileIdle(boolean))

TapestryKeyedObjectPool

public TapestryKeyedObjectPool(org.apache.commons.pool.KeyedPoolableObjectFactory factory,
                               int maxActive,
                               byte whenExhaustedAction,
                               long maxWait,
                               int maxIdle,
                               int maxTotal,
                               boolean testOnBorrow,
                               boolean testOnReturn,
                               long timeBetweenEvictionRunsMillis,
                               int numTestsPerEvictionRun,
                               long minEvictableIdleTimeMillis,
                               boolean testWhileIdle)
Create a new GenericKeyedObjectPool using the specified values.

Parameters:
factory - the KeyedPoolableObjectFactory to use to create, validate, and destroy objects if not null
maxActive - the maximum number of objects that can be borrowed from me at one time (see setMaxActive(int))
whenExhaustedAction - the action to take when the pool is exhausted (see setWhenExhaustedAction(byte))
maxWait - the maximum amount of time to wait for an idle object when the pool is exhausted and whenExhaustedAction is WHEN_EXHAUSTED_BLOCK (otherwise ignored) (see setMaxWait(long))
maxIdle - the maximum number of idle objects in my pool (see setMaxIdle(int))
maxTotal - the maximum number of objects that can exists at one time (see setMaxTotal(int))
testOnBorrow - whether or not to validate objects before they are returned by the borrowObject(java.lang.Object) method (see setTestOnBorrow(boolean))
testOnReturn - whether or not to validate objects after they are returned to the returnObject(java.lang.Object, java.lang.Object) method (see setTestOnReturn(boolean))
timeBetweenEvictionRunsMillis - the amount of time (in milliseconds) to sleep between examining idle objects for eviction (see setTimeBetweenEvictionRunsMillis(long))
numTestsPerEvictionRun - the number of idle objects to examine per run within the idle object eviction thread (if any) (see setNumTestsPerEvictionRun(int))
minEvictableIdleTimeMillis - the minimum number of milliseconds an object can sit idle in the pool before it is eligible for eviction (see setMinEvictableIdleTimeMillis(long))
testWhileIdle - whether or not to validate objects in the idle object eviction thread, if any (see setTestWhileIdle(boolean))

TapestryKeyedObjectPool

public TapestryKeyedObjectPool(org.apache.commons.pool.KeyedPoolableObjectFactory factory,
                               int maxActive,
                               byte whenExhaustedAction,
                               long maxWait,
                               int maxIdle,
                               int maxTotal,
                               int minIdle,
                               boolean testOnBorrow,
                               boolean testOnReturn,
                               long timeBetweenEvictionRunsMillis,
                               int numTestsPerEvictionRun,
                               long minEvictableIdleTimeMillis,
                               boolean testWhileIdle)
Create a new GenericKeyedObjectPool using the specified values.

Parameters:
factory - the KeyedPoolableObjectFactory to use to create, validate, and destroy objects if not null
maxActive - the maximum number of objects that can be borrowed from me at one time (see setMaxActive(int))
whenExhaustedAction - the action to take when the pool is exhausted (see setWhenExhaustedAction(byte))
maxWait - the maximum amount of time to wait for an idle object when the pool is exhausted and whenExhaustedAction is WHEN_EXHAUSTED_BLOCK (otherwise ignored) (see setMaxWait(long))
maxIdle - the maximum number of idle objects in my pool (see setMaxIdle(int))
maxTotal - the maximum number of objects that can exists at one time (see setMaxTotal(int))
minIdle - the minimum number of idle objects to have in the pool at any one time (see setMinIdle(int))
testOnBorrow - whether or not to validate objects before they are returned by the borrowObject(java.lang.Object) method (see setTestOnBorrow(boolean))
testOnReturn - whether or not to validate objects after they are returned to the returnObject(java.lang.Object, java.lang.Object) method (see setTestOnReturn(boolean))
timeBetweenEvictionRunsMillis - the amount of time (in milliseconds) to sleep between examining idle objects for eviction (see setTimeBetweenEvictionRunsMillis(long))
numTestsPerEvictionRun - the number of idle objects to examine per run within the idle object eviction thread (if any) (see setNumTestsPerEvictionRun(int))
minEvictableIdleTimeMillis - the minimum number of milliseconds an object can sit idle in the pool before it is eligible for eviction (see setMinEvictableIdleTimeMillis(long))
testWhileIdle - whether or not to validate objects in the idle object eviction thread, if any (see setTestWhileIdle(boolean))
Since:
Pool 1.3

TapestryKeyedObjectPool

public TapestryKeyedObjectPool(org.apache.commons.pool.KeyedPoolableObjectFactory factory,
                               int maxActive,
                               byte whenExhaustedAction,
                               long maxWait,
                               int maxIdle,
                               int maxTotal,
                               int minIdle,
                               boolean testOnBorrow,
                               boolean testOnReturn,
                               long timeBetweenEvictionRunsMillis,
                               int numTestsPerEvictionRun,
                               long minEvictableIdleTimeMillis,
                               boolean testWhileIdle,
                               boolean lifo)
Create a new GenericKeyedObjectPool using the specified values.

Parameters:
factory - the KeyedPoolableObjectFactory to use to create, validate, and destroy objects if not null
maxActive - the maximum number of objects that can be borrowed from me at one time (see setMaxActive(int))
whenExhaustedAction - the action to take when the pool is exhausted (see setWhenExhaustedAction(byte))
maxWait - the maximum amount of time to wait for an idle object when the pool is exhausted and whenExhaustedAction is WHEN_EXHAUSTED_BLOCK (otherwise ignored) (see setMaxWait(long))
maxIdle - the maximum number of idle objects in my pool (see setMaxIdle(int))
maxTotal - the maximum number of objects that can exists at one time (see setMaxTotal(int))
minIdle - the minimum number of idle objects to have in the pool at any one time (see setMinIdle(int))
testOnBorrow - whether or not to validate objects before they are returned by the borrowObject(java.lang.Object) method (see setTestOnBorrow(boolean))
testOnReturn - whether or not to validate objects after they are returned to the returnObject(java.lang.Object, java.lang.Object) method (see setTestOnReturn(boolean))
timeBetweenEvictionRunsMillis - the amount of time (in milliseconds) to sleep between examining idle objects for eviction (see setTimeBetweenEvictionRunsMillis(long))
numTestsPerEvictionRun - the number of idle objects to examine per run within the idle object eviction thread (if any) (see setNumTestsPerEvictionRun(int))
minEvictableIdleTimeMillis - the minimum number of milliseconds an object can sit idle in the pool before it is eligible for eviction (see setMinEvictableIdleTimeMillis(long))
testWhileIdle - whether or not to validate objects in the idle object eviction thread, if any (see setTestWhileIdle(boolean))
lifo - whether or not the pools behave as LIFO (last in first out) queues (see setLifo(boolean))
Since:
Pool 1.4
Method Detail

getMaxActive

public int getMaxActive()
Returns the cap on the number of active instances per key. A negative value indicates no limit.

Returns:
the cap on the number of active instances per key.
See Also:
setMaxActive(int)

setMaxActive

public void setMaxActive(int maxActive)
Sets the cap on the number of active instances per key.

Parameters:
maxActive - The cap on the number of active instances per key. Use a negative value for no limit.
See Also:
getMaxActive()

getMaxTotal

public int getMaxTotal()
Returns the overall maximum number of objects (across pools) that can exist at one time. A negative value indicates no limit.

Returns:
the maximum number of instances in circulation at one time.
See Also:
setMaxTotal(int)

setMaxTotal

public void setMaxTotal(int maxTotal)
Sets the cap on the total number of instances from all pools combined. When maxTotal is set to a positive value and borrowObject is invoked when at the limit with no idle instances available, an attempt is made to create room by clearing the oldest 15% of the elements from the keyed pools.

Parameters:
maxTotal - The cap on the total number of instances across pools. Use a negative value for no limit.
See Also:
getMaxTotal()

getWhenExhaustedAction

public byte getWhenExhaustedAction()
Returns the action to take when the borrowObject(java.lang.Object) method is invoked when the pool is exhausted (the maximum number of "active" objects has been reached).

Returns:
one of WHEN_EXHAUSTED_BLOCK, WHEN_EXHAUSTED_FAIL or WHEN_EXHAUSTED_GROW
See Also:
setWhenExhaustedAction(byte)

setWhenExhaustedAction

public void setWhenExhaustedAction(byte whenExhaustedAction)
Sets the action to take when the borrowObject(java.lang.Object) method is invoked when the pool is exhausted (the maximum number of "active" objects has been reached).

Parameters:
whenExhaustedAction - the action code, which must be one of WHEN_EXHAUSTED_BLOCK, WHEN_EXHAUSTED_FAIL, or WHEN_EXHAUSTED_GROW
See Also:
getWhenExhaustedAction()

getMaxWait

public long getMaxWait()
Returns the maximum amount of time (in milliseconds) the borrowObject(java.lang.Object) method should block before throwing an exception when the pool is exhausted and the "when exhausted" action is WHEN_EXHAUSTED_BLOCK. When less than or equal to 0, the borrowObject(java.lang.Object) method may block indefinitely.

Returns:
the maximum number of milliseconds borrowObject will block.
See Also:
setMaxWait(long), setWhenExhaustedAction(byte), WHEN_EXHAUSTED_BLOCK

setMaxWait

public void setMaxWait(long maxWait)
Sets the maximum amount of time (in milliseconds) the borrowObject(java.lang.Object) method should block before throwing an exception when the pool is exhausted and the "when exhausted" action is WHEN_EXHAUSTED_BLOCK. When less than or equal to 0, the borrowObject(java.lang.Object) method may block indefinitely.

Parameters:
maxWait - the maximum number of milliseconds borrowObject will block or negative for indefinitely.
See Also:
getMaxWait(), setWhenExhaustedAction(byte), WHEN_EXHAUSTED_BLOCK

getMaxIdle

public int getMaxIdle()
Returns the cap on the number of "idle" instances per key.

Returns:
the maximum number of "idle" instances that can be held in a given keyed pool.
See Also:
setMaxIdle(int)

setMaxIdle

public void setMaxIdle(int maxIdle)
Sets the cap on the number of "idle" instances in the pool.

Parameters:
maxIdle - the maximum number of "idle" instances that can be held in a given keyed pool. Use a negative value for no limit.
See Also:
getMaxIdle(), DEFAULT_MAX_IDLE

setMinIdle

public void setMinIdle(int poolSize)
Sets the minimum number of idle objects to maintain in each of the keyed pools. This setting has no effect unless timeBetweenEvictionRunsMillis > 0 and attempts to ensure that each pool has the required minimum number of instances are only made during idle object eviction runs.

Parameters:
poolSize - - The minimum size of the each keyed pool
Since:
Pool 1.3
See Also:
getMinIdle(), setTimeBetweenEvictionRunsMillis(long)

getMinIdle

public int getMinIdle()
Returns the minimum number of idle objects to maintain in each of the keyed pools. This setting has no effect unless timeBetweenEvictionRunsMillis > 0 and attempts to ensure that each pool has the required minimum number of instances are only made during idle object eviction runs.

Returns:
minimum size of the each keyed pool
Since:
Pool 1.3
See Also:
setTimeBetweenEvictionRunsMillis(long)

getTestOnBorrow

public boolean getTestOnBorrow()
When true, objects will be validated before being returned by the borrowObject(java.lang.Object) method. If the object fails to validate, it will be dropped from the pool, and we will attempt to borrow another.

Returns:
true if objects are validated before being borrowed.
See Also:
setTestOnBorrow(boolean)

setTestOnBorrow

public void setTestOnBorrow(boolean testOnBorrow)
When true, objects will be validated before being returned by the borrowObject(java.lang.Object) method. If the object fails to validate, it will be dropped from the pool, and we will attempt to borrow another.

Parameters:
testOnBorrow - whether object should be validated before being returned by borrowObject.
See Also:
getTestOnBorrow()

getTestOnReturn

public boolean getTestOnReturn()
When true, objects will be validated before being returned to the pool within the returnObject(java.lang.Object, java.lang.Object).

Returns:
true when objects will be validated before being returned.
See Also:
setTestOnReturn(boolean)

setTestOnReturn

public void setTestOnReturn(boolean testOnReturn)
When true, objects will be validated before being returned to the pool within the returnObject(java.lang.Object, java.lang.Object).

Parameters:
testOnReturn - true so objects will be validated before being returned.
See Also:
getTestOnReturn()

getTimeBetweenEvictionRunsMillis

public long getTimeBetweenEvictionRunsMillis()
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.

Returns:
milliseconds to sleep between evictor runs.
See Also:
setTimeBetweenEvictionRunsMillis(long)

setTimeBetweenEvictionRunsMillis

public void setTimeBetweenEvictionRunsMillis(long timeBetweenEvictionRunsMillis)
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.

Parameters:
timeBetweenEvictionRunsMillis - milliseconds to sleep between evictor runs.
See Also:
getTimeBetweenEvictionRunsMillis()

getNumTestsPerEvictionRun

public int getNumTestsPerEvictionRun()
Returns the number of objects to examine during each run of the idle object evictor thread (if any).

Returns:
number of objects to examine each eviction run.
See Also:
setNumTestsPerEvictionRun(int), setTimeBetweenEvictionRunsMillis(long)

setNumTestsPerEvictionRun

public void setNumTestsPerEvictionRun(int numTestsPerEvictionRun)
Sets the number of objects to examine during each run of the idle object evictor thread (if any).

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

Parameters:
numTestsPerEvictionRun - number of objects to examine each eviction run.
See Also:
getNumTestsPerEvictionRun(), setTimeBetweenEvictionRunsMillis(long)

getMinEvictableIdleTimeMillis

public 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).

Returns:
minimum amount of time an object may sit idle in the pool before it is eligible for eviction.
See Also:
setMinEvictableIdleTimeMillis(long), setTimeBetweenEvictionRunsMillis(long)

setMinEvictableIdleTimeMillis

public 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). When non-positive, no objects will be evicted from the pool due to idle time alone.

Parameters:
minEvictableIdleTimeMillis - minimum amount of time an object may sit idle in the pool before it is eligible for eviction.
See Also:
getMinEvictableIdleTimeMillis(), setTimeBetweenEvictionRunsMillis(long)

getTestWhileIdle

public boolean getTestWhileIdle()
When true, objects will be validated by the idle object evictor (if any). If an object fails to validate, it will be dropped from the pool.

Returns:
true when objects are validated when borrowed.
See Also:
setTestWhileIdle(boolean), setTimeBetweenEvictionRunsMillis(long)

setTestWhileIdle

public void setTestWhileIdle(boolean testWhileIdle)
When true, objects will be validated by the idle object evictor (if any). If an object fails to validate, it will be dropped from the pool.

Parameters:
testWhileIdle - true so objects are validated when borrowed.
See Also:
getTestWhileIdle(), setTimeBetweenEvictionRunsMillis(long)

setConfig

public void setConfig(org.apache.commons.pool.impl.GenericKeyedObjectPool.Config conf)
Sets the configuration.

Parameters:
conf - the new configuration to use.
See Also:
GenericKeyedObjectPool.Config

getLifo

public boolean getLifo()
Whether or not the idle object pools act as LIFO queues. True means that borrowObject returns the most recently used ("last in") idle object in a pool (if there are idle instances available). False means that the pools behave as FIFO queues - objects are taken from idle object pools in the order that they are returned.

Returns:
true if the pools are configured to act as LIFO queues
Since:
1.4

setLifo

public void setLifo(boolean lifo)
Sets the LIFO property of the pools. True means that borrowObject returns the most recently used ("last in") idle object in a pool (if there are idle instances available). False means that the pools behave as FIFO queues - objects are taken from idle object pools in the order that they are returned.

Parameters:
lifo - the new value for the lifo property
Since:
1.4

borrowObject

public Object borrowObject(Object key)
                    throws Exception
Specified by:
borrowObject in interface org.apache.commons.pool.KeyedObjectPool
Specified by:
borrowObject in class org.apache.commons.pool.BaseKeyedObjectPool
Throws:
Exception

clear

public void clear()
Clears the pool, removing all pooled instances.

Specified by:
clear in interface org.apache.commons.pool.KeyedObjectPool
Overrides:
clear in class org.apache.commons.pool.BaseKeyedObjectPool

clearOldest

public void clearOldest()
Method clears oldest 15% of objects in pool. The method sorts the objects into a TreeMap and then iterates the first 15% for removal

Since:
Pool 1.3

clear

public void clear(Object key)
Clears the specified pool, removing all pooled instances corresponding to the given key.

Specified by:
clear in interface org.apache.commons.pool.KeyedObjectPool
Overrides:
clear in class org.apache.commons.pool.BaseKeyedObjectPool
Parameters:
key - the key to clear

getNumActive

public int getNumActive()
Returns the total number of instances current borrowed from this pool but not yet returned.

Specified by:
getNumActive in interface org.apache.commons.pool.KeyedObjectPool
Overrides:
getNumActive in class org.apache.commons.pool.BaseKeyedObjectPool
Returns:
the total number of instances currently borrowed from this pool

getNumIdle

public int getNumIdle()
Returns the total number of instances currently idle in this pool.

Specified by:
getNumIdle in interface org.apache.commons.pool.KeyedObjectPool
Overrides:
getNumIdle in class org.apache.commons.pool.BaseKeyedObjectPool
Returns:
the total number of instances currently idle in this pool

getNumActive

public int getNumActive(Object key)
Returns the number of instances currently borrowed from but not yet returned to the pool corresponding to the given key.

Specified by:
getNumActive in interface org.apache.commons.pool.KeyedObjectPool
Overrides:
getNumActive in class org.apache.commons.pool.BaseKeyedObjectPool
Parameters:
key - the key to query
Returns:
the number of instances corresponding to the given key currently borrowed in this pool

getNumIdle

public int getNumIdle(Object key)
Returns the number of instances corresponding to the given key currently idle in this pool.

Specified by:
getNumIdle in interface org.apache.commons.pool.KeyedObjectPool
Overrides:
getNumIdle in class org.apache.commons.pool.BaseKeyedObjectPool
Parameters:
key - the key to query
Returns:
the number of instances corresponding to the given key currently idle in this pool

returnObject

public void returnObject(Object key,
                         Object obj)
                  throws Exception
Specified by:
returnObject in interface org.apache.commons.pool.KeyedObjectPool
Specified by:
returnObject in class org.apache.commons.pool.BaseKeyedObjectPool
Throws:
Exception

invalidateObject

public void invalidateObject(Object key,
                             Object obj)
                      throws Exception
Specified by:
invalidateObject in interface org.apache.commons.pool.KeyedObjectPool
Specified by:
invalidateObject in class org.apache.commons.pool.BaseKeyedObjectPool
Throws:
Exception

addObject

public void addObject(Object key)
               throws Exception
Create an object using the factory, passivate it, and then place it in the idle object pool. addObject is useful for "pre-loading" a pool with idle objects.

Specified by:
addObject in interface org.apache.commons.pool.KeyedObjectPool
Overrides:
addObject in class org.apache.commons.pool.BaseKeyedObjectPool
Parameters:
key - the key a new instance should be added to
Throws:
Exception - when KeyedPoolableObjectFactory.makeObject(java.lang.Object) fails.
IllegalStateException - when no factory has been set or after close() has been called on this pool.

preparePool

public void preparePool(Object key,
                        boolean populateImmediately)
Registers a key for pool control. If populateImmediately is true and minIdle > 0, the pool under the given key will be populated immediately with minIdle idle instances.

Parameters:
key - - The key to register for pool control.
populateImmediately - - If this is true, the pool will be populated immediately.
Since:
Pool 1.3

close

public void close()
           throws Exception
Specified by:
close in interface org.apache.commons.pool.KeyedObjectPool
Overrides:
close in class org.apache.commons.pool.BaseKeyedObjectPool
Throws:
Exception

setFactory

public void setFactory(org.apache.commons.pool.KeyedPoolableObjectFactory factory)
                throws IllegalStateException
Specified by:
setFactory in interface org.apache.commons.pool.KeyedObjectPool
Overrides:
setFactory in class org.apache.commons.pool.BaseKeyedObjectPool
Throws:
IllegalStateException

evict

public void evict()
           throws Exception

Perform numTests idle object eviction tests, evicting examined objects that meet the criteria for eviction. If testWhileIdle is true, examined objects are validated when visited (and removed if invalid); otherwise only objects that have been idle for more than minEvicableIdletimeMillis are removed.

Successive activations of this method examine objects in keyed pools in sequence, cycling through the keys and examining objects in oldest-to-youngest order within the keyed pools.

Throws:
Exception - when there is a problem evicting idle objects.

startEvictor

protected void startEvictor(long delay)
Start the eviction thread or service, or when delay is non-positive, stop it if it is already running.

Parameters:
delay - milliseconds between evictor runs.


Copyright © 2006-2011 Apache Software Foundation. All Rights Reserved.