org.apache.commons.pool.impl

Class GenericKeyedObjectPool

Implemented Interfaces:
KeyedObjectPool

public class GenericKeyedObjectPool
extends BaseKeyedObjectPool
implements KeyedObjectPool

A configurable KeyedObjectPool implementation.

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

A GenericKeyedObjectPool provides a number of configurable parameters:

  • 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 KeyedPoolableObjectFactory.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 KeyedPoolableObjectFactory.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:

    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.

    Version:
    $Revision: 386116 $ $Date: 2006-03-15 12:15:58 -0500 (Wed, 15 Mar 2006) $
    Authors:
    Rodney Waldhoff
    Dirk Verbeeck
    See Also:
    GenericObjectPool

    Nested Class Summary

    static class
    GenericKeyedObjectPool.Config
    A simple "struct" encapsulating the configuration information for a GenericKeyedObjectPool.

    Field Summary

    static int
    DEFAULT_MAX_ACTIVE
    The default cap on the total number of active instances from the pool (per key).
    static int
    DEFAULT_MAX_IDLE
    The default cap on the number of idle instances in the pool (per key).
    static int
    DEFAULT_MAX_TOTAL
    The default cap on the the maximum number of objects that can exists at one time.
    static long
    DEFAULT_MAX_WAIT
    The default maximum amount of time (in millis) the borrowObject(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(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(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(Object) method should simply create a new object anyway.

    Constructor Summary

    GenericKeyedObjectPool()
    Create a new GenericKeyedObjectPool..
    GenericKeyedObjectPool(KeyedPoolableObjectFactory factory)
    Create a new GenericKeyedObjectPool using the specified values.
    GenericKeyedObjectPool(KeyedPoolableObjectFactory factory, int maxActive)
    Create a new GenericKeyedObjectPool using the specified values.
    GenericKeyedObjectPool(KeyedPoolableObjectFactory factory, int maxActive, byte whenExhaustedAction, long maxWait)
    Create a new GenericKeyedObjectPool using the specified values.
    GenericKeyedObjectPool(KeyedPoolableObjectFactory factory, int maxActive, byte whenExhaustedAction, long maxWait, boolean testOnBorrow, boolean testOnReturn)
    Create a new GenericKeyedObjectPool using the specified values.
    GenericKeyedObjectPool(KeyedPoolableObjectFactory factory, int maxActive, byte whenExhaustedAction, long maxWait, int maxIdle)
    Create a new GenericKeyedObjectPool using the specified values.
    GenericKeyedObjectPool(KeyedPoolableObjectFactory factory, int maxActive, byte whenExhaustedAction, long maxWait, int maxIdle, boolean testOnBorrow, boolean testOnReturn)
    Create a new GenericKeyedObjectPool using the specified values.
    GenericKeyedObjectPool(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.
    GenericKeyedObjectPool(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.
    GenericKeyedObjectPool(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.
    GenericKeyedObjectPool(KeyedPoolableObjectFactory factory, GenericKeyedObjectPool.Config config)
    Create a new GenericKeyedObjectPool using the specified values.

    Method Summary

    void
    addObject(Object key)
    Object
    borrowObject(Object key)
    void
    clear()
    void
    clear(Object key)
    void
    clearOldest()
    Method clears oldest 15% of objects in pool.
    void
    close()
    void
    evict()
    int
    getMaxActive()
    Returns the cap on the number of active instances from my pool (per key).
    int
    getMaxIdle()
    Returns the cap on the number of "idle" instances in the pool.
    int
    getMaxTotal()
    Returns the cap on the total number of instances from my pool if non-positive.
    long
    getMaxWait()
    Returns the maximum amount of time (in milliseconds) the borrowObject(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 eligable for eviction by the idle object evictor (if any).
    int
    getMinIdle()
    Returns the minimum number of idle objects in pool to maintain (per key)
    int
    getNumActive()
    int
    getNumActive(Object key)
    int
    getNumIdle()
    int
    getNumIdle(Object key)
    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(Object) method.
    boolean
    getTestOnReturn()
    When true, objects will be validated before being returned to the pool within the returnObject(Object,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(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(GenericKeyedObjectPool.Config conf)
    Sets my configuration.
    void
    setFactory(KeyedPoolableObjectFactory factory)
    void
    setMaxActive(int maxActive)
    Sets the cap on the number of active instances from my pool (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 my pool if non-positive.
    void
    setMaxWait(long maxWait)
    Sets the maximum amount of time (in milliseconds) the borrowObject(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 eligable for eviction by the idle object evictor (if any).
    void
    setMinIdle(int poolSize)
    Sets the minimum number of idle objects in pool to maintain (per key)
    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(Object) method.
    void
    setTestOnReturn(boolean testOnReturn)
    When true, objects will be validated before being returned to the pool within the returnObject(Object,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(Object) method is invoked when the pool is exhausted (the maximum number of "active" objects has been reached).

    Methods inherited from class org.apache.commons.pool.BaseKeyedObjectPool

    addObject, borrowObject, clear, clear, close, getNumActive, getNumActive, getNumIdle, getNumIdle, invalidateObject, returnObject, setFactory

    Field Details

    DEFAULT_MAX_ACTIVE

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

    DEFAULT_MAX_IDLE

    public static final int DEFAULT_MAX_IDLE
    The default cap on the number of idle instances in the pool (per key).
    Field Value:
    8

    DEFAULT_MAX_TOTAL

    public static final int DEFAULT_MAX_TOTAL
    The default cap on the the maximum number of objects that can exists at one time.
    Field Value:
    -1

    DEFAULT_MAX_WAIT

    public static final long DEFAULT_MAX_WAIT
    The default maximum amount of time (in millis) the borrowObject(Object) method should block before throwing an exception when the pool is exhausted and the "when exhausted" action is WHEN_EXHAUSTED_BLOCK.
    Field Value:
    -1L

    DEFAULT_MIN_EVICTABLE_IDLE_TIME_MILLIS

    public static final long DEFAULT_MIN_EVICTABLE_IDLE_TIME_MILLIS
    Field Value:
    1800000L

    DEFAULT_MIN_IDLE

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

    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.
    Field Value:
    3

    DEFAULT_TEST_ON_BORROW

    public static final boolean DEFAULT_TEST_ON_BORROW
    The default "test on borrow" value.
    Field Value:
    false

    DEFAULT_TEST_ON_RETURN

    public static final boolean DEFAULT_TEST_ON_RETURN
    The default "test on return" value.
    Field Value:
    false

    DEFAULT_TEST_WHILE_IDLE

    public static final boolean DEFAULT_TEST_WHILE_IDLE
    The default "test while idle" value.
    Field Value:
    false

    DEFAULT_TIME_BETWEEN_EVICTION_RUNS_MILLIS

    public static final long DEFAULT_TIME_BETWEEN_EVICTION_RUNS_MILLIS
    The default "time between eviction runs" value.
    Field Value:
    -1L

    DEFAULT_WHEN_EXHAUSTED_ACTION

    public static final byte DEFAULT_WHEN_EXHAUSTED_ACTION
    The default "when exhausted action" for the pool.
    Field Value:
    1

    WHEN_EXHAUSTED_BLOCK

    public static final byte WHEN_EXHAUSTED_BLOCK
    Field Value:
    1

    WHEN_EXHAUSTED_FAIL

    public static final byte WHEN_EXHAUSTED_FAIL
    Field Value:
    0

    WHEN_EXHAUSTED_GROW

    public static final byte WHEN_EXHAUSTED_GROW
    Field Value:
    2

    Constructor Details

    GenericKeyedObjectPool

    public GenericKeyedObjectPool()
    Create a new GenericKeyedObjectPool..

    GenericKeyedObjectPool

    public GenericKeyedObjectPool(KeyedPoolableObjectFactory factory)
    Create a new GenericKeyedObjectPool using the specified values.
    Parameters:
    factory - the (possibly null)KeyedPoolableObjectFactory to use to create, validate and destroy objects

    GenericKeyedObjectPool

    public GenericKeyedObjectPool(KeyedPoolableObjectFactory factory,
                                  int maxActive)
    Create a new GenericKeyedObjectPool using the specified values.
    Parameters:
    factory - the (possibly null)KeyedPoolableObjectFactory to use to create, validate and destroy objects
    maxActive - the maximum number of objects that can be borrowed from me at one time (per key) (see setMaxActive(int))

    GenericKeyedObjectPool

    public GenericKeyedObjectPool(KeyedPoolableObjectFactory factory,
                                  int maxActive,
                                  byte whenExhaustedAction,
                                  long maxWait)
    Create a new GenericKeyedObjectPool using the specified values.
    Parameters:
    factory - the (possibly null)KeyedPoolableObjectFactory to use to create, validate and destroy objects
    maxActive - the maximum number of objects that can be borrowed from me at one time (per key) (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 an and whenExhaustedAction is WHEN_EXHAUSTED_BLOCK (otherwise ignored) (see setMaxWait(long))

    GenericKeyedObjectPool

    public GenericKeyedObjectPool(KeyedPoolableObjectFactory factory,
                                  int maxActive,
                                  byte whenExhaustedAction,
                                  long maxWait,
                                  boolean testOnBorrow,
                                  boolean testOnReturn)
    Create a new GenericKeyedObjectPool using the specified values.
    Parameters:
    factory - the (possibly null)KeyedPoolableObjectFactory to use to create, validate and destroy objects
    maxActive - the maximum number of objects that can be borrowed from me at one time (per key) (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 an and whenExhaustedAction is WHEN_EXHAUSTED_BLOCK (otherwise ignored) (see setMaxWait(long))
    testOnBorrow - whether or not to validate objects before they are returned by the borrowObject(Object) method (see setTestOnBorrow(boolean))
    testOnReturn - whether or not to validate objects after they are returned to the returnObject(Object,Object) method (see setTestOnReturn(boolean))

    GenericKeyedObjectPool

    public GenericKeyedObjectPool(KeyedPoolableObjectFactory factory,
                                  int maxActive,
                                  byte whenExhaustedAction,
                                  long maxWait,
                                  int maxIdle)
    Create a new GenericKeyedObjectPool using the specified values.
    Parameters:
    factory - the (possibly null)KeyedPoolableObjectFactory to use to create, validate and destroy objects
    maxActive - the maximum number of objects that can be borrowed from me at one time (per key) (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 an and whenExhaustedAction is WHEN_EXHAUSTED_BLOCK (otherwise ignored) (see setMaxWait(long))
    maxIdle - the maximum number of idle objects in my pool (per key) (see setMaxIdle(int))

    GenericKeyedObjectPool

    public GenericKeyedObjectPool(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 (possibly null)KeyedPoolableObjectFactory to use to create, validate and destroy objects
    maxActive - the maximum number of objects that can be borrowed from me at one time (per key) (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 an 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(Object) method (see setTestOnBorrow(boolean))
    testOnReturn - whether or not to validate objects after they are returned to the returnObject(Object,Object) method (see setTestOnReturn(boolean))

    GenericKeyedObjectPool

    public GenericKeyedObjectPool(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 (possibly null)PoolableObjectFactory to use to create, validate and destroy objects
    maxActive - the maximum number of objects that can be borrowed from me at one time (per key) (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 an 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(Object) method (see setTestOnBorrow(boolean))
    testOnReturn - whether or not to validate objects after they are returned to the returnObject(Object,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 eligable for evcition (see setMinEvictableIdleTimeMillis(long))
    testWhileIdle - whether or not to validate objects in the idle object eviction thread, if any (see setTestWhileIdle(boolean))

    GenericKeyedObjectPool

    public GenericKeyedObjectPool(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 (possibly null)PoolableObjectFactory to use to create, validate and destroy objects
    maxActive - the maximum number of objects that can be borrowed from me at one time (per key) (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 an 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(Object) method (see setTestOnBorrow(boolean))
    testOnReturn - whether or not to validate objects after they are returned to the returnObject(Object,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 eligable for evcition (see setMinEvictableIdleTimeMillis(long))
    testWhileIdle - whether or not to validate objects in the idle object eviction thread, if any (see setTestWhileIdle(boolean))

    GenericKeyedObjectPool

    public GenericKeyedObjectPool(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 (possibly null)PoolableObjectFactory to use to create, validate and destroy objects
    maxActive - the maximum number of objects that can be borrowed from me at one time (per key) (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 an 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(Object) method (see setTestOnBorrow(boolean))
    testOnReturn - whether or not to validate objects after they are returned to the returnObject(Object,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 eligable for evcition (see setMinEvictableIdleTimeMillis(long))
    testWhileIdle - whether or not to validate objects in the idle object eviction thread, if any (see setTestWhileIdle(boolean))

    GenericKeyedObjectPool

    public GenericKeyedObjectPool(KeyedPoolableObjectFactory factory,
                                  GenericKeyedObjectPool.Config config)
    Create a new GenericKeyedObjectPool using the specified values.
    Parameters:
    factory - the (possibly null)KeyedPoolableObjectFactory to use to create, validate and destroy objects
    config - a non-null GenericKeyedObjectPool.Config describing my configuration

    Method Details

    addObject

    public void addObject(Object key)
                throws Exception
    Specified by:
    addObject in interface KeyedObjectPool
    Overrides:
    addObject in interface BaseKeyedObjectPool

    borrowObject

    public Object borrowObject(Object key)
                throws Exception
    Specified by:
    borrowObject in interface KeyedObjectPool
    Overrides:
    borrowObject in interface BaseKeyedObjectPool

    clear

    public void clear()
    Specified by:
    clear in interface KeyedObjectPool
    Overrides:
    clear in interface BaseKeyedObjectPool

    clear

    public void clear(Object key)
    Specified by:
    clear in interface KeyedObjectPool
    Overrides:
    clear in interface 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

    close

    public void close()
                throws Exception
    Specified by:
    close in interface KeyedObjectPool
    Overrides:
    close in interface BaseKeyedObjectPool

    evict

    public void evict()
                throws Exception

    getMaxActive

    public int getMaxActive()
    Returns the cap on the number of active instances from my pool (per key).
    Returns:
    the cap on the number of active instances from my pool (per key).

    getMaxIdle

    public int getMaxIdle()
    Returns the cap on the number of "idle" instances in the pool.
    Returns:
    the cap on the number of "idle" instances in the pool.

    getMaxTotal

    public int getMaxTotal()
    Returns the cap on the total number of instances from my pool if non-positive.
    Returns:
    the cap on the total number of instances from my pool if non-positive.

    getMaxWait

    public long getMaxWait()
    Returns the maximum amount of time (in milliseconds) the borrowObject(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 0, the borrowObject(Object) method may block indefinitely.

    getMinEvictableIdleTimeMillis

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

    getMinIdle

    public int getMinIdle()
    Returns the minimum number of idle objects in pool to maintain (per key)
    Returns:
    the minimum number of idle objects in pool to maintain (per key)

    getNumActive

    public int getNumActive()
    Specified by:
    getNumActive in interface KeyedObjectPool
    Overrides:
    getNumActive in interface BaseKeyedObjectPool

    getNumActive

    public int getNumActive(Object key)
    Specified by:
    getNumActive in interface KeyedObjectPool
    Overrides:
    getNumActive in interface BaseKeyedObjectPool

    getNumIdle

    public int getNumIdle()
    Specified by:
    getNumIdle in interface KeyedObjectPool
    Overrides:
    getNumIdle in interface BaseKeyedObjectPool

    getNumIdle

    public int getNumIdle(Object key)
    Specified by:
    getNumIdle in interface KeyedObjectPool
    Overrides:
    getNumIdle in interface BaseKeyedObjectPool

    getNumTestsPerEvictionRun

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

    getTestOnBorrow

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

    getTestOnReturn

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

    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.

    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.

    getWhenExhaustedAction

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

    invalidateObject

    public void invalidateObject(Object key,
                                 Object obj)
                throws Exception
    Specified by:
    invalidateObject in interface KeyedObjectPool
    Overrides:
    invalidateObject in interface BaseKeyedObjectPool

    preparePool

    public void preparePool(Object key,
                            boolean populateImmediately)
    Registers a key for pool control. If populateImmediately is true, the pool will immediately commence a sustain cycle. If populateImmediately is false, the pool will be populated when the next schedules sustain task is run.
    Parameters:
    key - - The key to register for pool control.
    populateImmediately - - If this is true, the pool will start a sustain cycle immediately.

    returnObject

    public void returnObject(Object key,
                             Object obj)
                throws Exception
    Specified by:
    returnObject in interface KeyedObjectPool
    Overrides:
    returnObject in interface BaseKeyedObjectPool

    setConfig

    public void setConfig(GenericKeyedObjectPool.Config conf)
    Sets my configuration.

    setFactory

    public void setFactory(KeyedPoolableObjectFactory factory)
                throws IllegalStateException
    Specified by:
    setFactory in interface KeyedObjectPool
    Overrides:
    setFactory in interface BaseKeyedObjectPool

    setMaxActive

    public void setMaxActive(int maxActive)
    Sets the cap on the number of active instances from my pool (per key).
    Parameters:
    maxActive - The cap on the number of active instances from my pool (per key). Use a negative value for an infinite number of instances.

    setMaxIdle

    public void setMaxIdle(int maxIdle)
    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 number of idle instances.

    setMaxTotal

    public void setMaxTotal(int maxTotal)
    Sets the cap on the total number of instances from my pool if non-positive.
    Parameters:
    maxTotal - The cap on the total number of instances from my pool. Use a non-positive value for an infinite number of instances.

    setMaxWait

    public void setMaxWait(long maxWait)
    Sets the maximum amount of time (in milliseconds) the borrowObject(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 0, the borrowObject(Object) method may block indefinitely.

    setMinEvictableIdleTimeMillis

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

    setMinIdle

    public void setMinIdle(int poolSize)
    Sets the minimum number of idle objects in pool to maintain (per key)
    Parameters:
    poolSize - - The minimum size of the pool

    setNumTestsPerEvictionRun

    public void setNumTestsPerEvictionRun(int numTestsPerEvictionRun)

    setTestOnBorrow

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

    setTestOnReturn

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

    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.

    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.

    setWhenExhaustedAction

    public void setWhenExhaustedAction(byte whenExhaustedAction)
    Sets the action to take when the borrowObject(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

    Copyright © 2001-2003 Apache Software Foundation. Documenation generated March 24 2007.