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 PoolableObjectFactory.validateObject(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 PoolableObjectFactory.validateObject(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: 1.26 $ $Date: 2004/02/28 11:46:33 $

    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_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, GenericKeyedObjectPool.Config config)
    Create a new GenericKeyedObjectPool using the specified values.

    Method Summary

    void
    addObject(Object key)
    Create an object using my factory or other implementation dependent mechanism, and place it into the pool.
    Object
    borrowObject(Object key)
    Obtain an instance from my pool for the specified key.
    void
    clear()
    Clears my pool, removing all pooled instances (optional operation).
    void
    clear(Object key)
    Clears the specified pool, removing all pooled instances corresponding to the given key (optional operation).
    void
    close()
    Close this pool, and free any resources associated with it.
    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.
    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
    getNumActive()
    Returns the total number of instances current borrowed from my pool but not yet returned (optional operation).
    int
    getNumActive(Object key)
    Returns the number of instances currently borrowed from but not yet returned to my pool corresponding to the given key (optional operation).
    int
    getNumIdle()
    Returns the total number of instances currently idle in my pool (optional operation).
    int
    getNumIdle(Object key)
    Returns the number of instances corresponding to the given key currently idle in my pool (optional operation).
    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)
    Invalidates an object from the pool By contract, obj MUST have been obtained using borrowObject or a related method as defined in an implementation or sub-interface using a key that is equivalent to the one used to borrow the Object in the first place.
    void
    returnObject(Object key, Object obj)
    Return an instance to my pool.
    void
    setConfig(GenericKeyedObjectPool.Config conf)
    Sets my configuration.
    void
    setFactory(KeyedPoolableObjectFactory factory)
    Sets the factory I use to create new instances (optional operation).
    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.
    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
    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

    See Also:
    getMaxActive(), setMaxActive(int)


    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

    See Also:
    getMaxIdle(), setMaxIdle(int)


    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

    See Also:
    getMaxTotal(), setMaxTotal(int)


    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

    See Also:
    getMaxWait(), setMaxWait(long)


    DEFAULT_MIN_EVICTABLE_IDLE_TIME_MILLIS

    public static final long DEFAULT_MIN_EVICTABLE_IDLE_TIME_MILLIS

    Field Value:
    1800000L

    See Also:
    getMinEvictableIdleTimeMillis(), setMinEvictableIdleTimeMillis(long)


    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

    See Also:
    getNumTestsPerEvictionRun(), setNumTestsPerEvictionRun(int), getTimeBetweenEvictionRunsMillis(), setTimeBetweenEvictionRunsMillis(long)


    DEFAULT_TEST_ON_BORROW

    public static final boolean DEFAULT_TEST_ON_BORROW
    The default "test on borrow" value.

    Field Value:
    false

    See Also:
    getTestOnBorrow(), setTestOnBorrow(boolean)


    DEFAULT_TEST_ON_RETURN

    public static final boolean DEFAULT_TEST_ON_RETURN
    The default "test on return" value.

    Field Value:
    false

    See Also:
    getTestOnReturn(), setTestOnReturn(boolean)


    DEFAULT_TEST_WHILE_IDLE

    public static final boolean DEFAULT_TEST_WHILE_IDLE
    The default "test while idle" value.

    Field Value:
    false

    See Also:
    getTestWhileIdle(), setTestWhileIdle(boolean), getTimeBetweenEvictionRunsMillis(), setTimeBetweenEvictionRunsMillis(long)


    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

    See Also:
    getTimeBetweenEvictionRunsMillis(), setTimeBetweenEvictionRunsMillis(long)


    DEFAULT_WHEN_EXHAUSTED_ACTION

    public static final byte DEFAULT_WHEN_EXHAUSTED_ACTION
    The default "when exhausted action" for the pool.

    Field Value:
    1

    See Also:
    WHEN_EXHAUSTED_BLOCK, WHEN_EXHAUSTED_FAIL, WHEN_EXHAUSTED_GROW, setWhenExhaustedAction(byte)


    WHEN_EXHAUSTED_BLOCK

    public static final byte WHEN_EXHAUSTED_BLOCK

    Field Value:
    1

    See Also:
    WHEN_EXHAUSTED_FAIL, WHEN_EXHAUSTED_GROW, setMaxWait(long), getMaxWait(), setWhenExhaustedAction(byte)


    WHEN_EXHAUSTED_FAIL

    public static final byte WHEN_EXHAUSTED_FAIL

    Field Value:
    0

    See Also:
    WHEN_EXHAUSTED_BLOCK, WHEN_EXHAUSTED_GROW, setWhenExhaustedAction(byte)


    WHEN_EXHAUSTED_GROW

    public static final byte WHEN_EXHAUSTED_GROW

    Field Value:
    2

    See Also:
    WHEN_EXHAUSTED_FAIL, WHEN_EXHAUSTED_GROW, setWhenExhaustedAction(byte)

    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,
                                  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
    Create an object using my factory or other implementation dependent mechanism, and place it into the pool. addObject() is useful for "pre-loading" a pool with idle objects. (Optional operation).
    Specified by:
    addObject in interface KeyedObjectPool
    Overrides:
    addObject in interface BaseKeyedObjectPool


    borrowObject

    public Object borrowObject(Object key)
                throws Exception
    Obtain an instance from my pool for the specified key. By contract, clients MUST return the borrowed object using returnObject, or a related method as defined in an implementation or sub-interface, using a key that is equivalent to the one used to borrow the instance in the first place.
    Specified by:
    borrowObject in interface KeyedObjectPool
    Overrides:
    borrowObject in interface BaseKeyedObjectPool

    Parameters:
    key - the key used to obtain the object

    Returns:
    an instance from my pool.


    clear

    public void clear()
    Clears my pool, removing all pooled instances (optional operation). Throws UnsupportedOperationException if the pool cannot be cleared.
    Specified by:
    clear in interface KeyedObjectPool
    Overrides:
    clear in interface BaseKeyedObjectPool


    clear

    public void clear(Object key)
    Clears the specified pool, removing all pooled instances corresponding to the given key (optional operation). Throws UnsupportedOperationException if the pool cannot be cleared.
    Specified by:
    clear in interface KeyedObjectPool
    Overrides:
    clear in interface BaseKeyedObjectPool

    Parameters:
    key - the key to clear


    close

    public void close()
                throws Exception
    Close this pool, and free any resources associated with it.
    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).

    See Also:
    setMaxActive(int)


    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.

    See Also:
    setMaxIdle(int)


    getMaxTotal

    public int getMaxTotal()
    Returns the cap on the total number of instances from my pool.

    Returns:
    the cap on the total number of instances from my pool.

    See Also:
    setMaxTotal(int)


    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.

    See Also:
    setMaxWait(long), setWhenExhaustedAction(byte), WHEN_EXHAUSTED_BLOCK


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

    See Also:
    setMinEvictableIdleTimeMillis(long), setTimeBetweenEvictionRunsMillis(long)


    getNumActive

    public int getNumActive()
    Returns the total number of instances current borrowed from my pool but not yet returned (optional operation). Throws UnsupportedOperationException if this information is not available.
    Specified by:
    getNumActive in interface KeyedObjectPool
    Overrides:
    getNumActive in interface BaseKeyedObjectPool

    Returns:
    the total number of instances currently borrowed from my pool


    getNumActive

    public int getNumActive(Object key)
    Returns the number of instances currently borrowed from but not yet returned to my pool corresponding to the given key (optional operation). Throws UnsupportedOperationException if this information is not available.
    Specified by:
    getNumActive in interface KeyedObjectPool
    Overrides:
    getNumActive in interface BaseKeyedObjectPool

    Parameters:
    key - the key

    Returns:
    the number of instances corresponding to the given key currently borrowed in my pool


    getNumIdle

    public int getNumIdle()
    Returns the total number of instances currently idle in my pool (optional operation). Throws UnsupportedOperationException if this information is not available.
    Specified by:
    getNumIdle in interface KeyedObjectPool
    Overrides:
    getNumIdle in interface BaseKeyedObjectPool

    Returns:
    the total number of instances currently idle in my pool


    getNumIdle

    public int getNumIdle(Object key)
    Returns the number of instances corresponding to the given key currently idle in my pool (optional operation). Throws UnsupportedOperationException if this information is not available.
    Specified by:
    getNumIdle in interface KeyedObjectPool
    Overrides:
    getNumIdle in interface BaseKeyedObjectPool

    Parameters:
    key - the key

    Returns:
    the number of instances corresponding to the given key currently idle in my pool


    getNumTestsPerEvictionRun

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

    See Also:
    setNumTestsPerEvictionRun(int), setTimeBetweenEvictionRunsMillis(long)


    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.

    See Also:
    setTestOnBorrow(boolean)


    getTestOnReturn

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

    See Also:
    setTestOnReturn(boolean)


    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.

    See Also:
    setTestWhileIdle(boolean), setTimeBetweenEvictionRunsMillis(long)


    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.

    See Also:
    setTimeBetweenEvictionRunsMillis(long)


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

    Returns:
    one of WHEN_EXHAUSTED_BLOCK, WHEN_EXHAUSTED_FAIL or WHEN_EXHAUSTED_GROW

    See Also:
    setWhenExhaustedAction(byte)


    invalidateObject

    public void invalidateObject(Object key,
                                 Object obj)
                throws Exception
    Invalidates an object from the pool By contract, obj MUST have been obtained using borrowObject or a related method as defined in an implementation or sub-interface using a key that is equivalent to the one used to borrow the Object in the first place.

    This method should be used when an object that has been borrowed is determined (due to an exception or other problem) to be invalid. If the connection should be validated before or after borrowing, then the PoolableObjectFactory.validateObject(Object) method should be used instead.

    Specified by:
    invalidateObject in interface KeyedObjectPool
    Overrides:
    invalidateObject in interface BaseKeyedObjectPool

    Parameters:
    obj - a borrowed instance to be returned.


    returnObject

    public void returnObject(Object key,
                             Object obj)
                throws Exception
    Return an instance to my pool. By contract, obj MUST have been obtained using borrowObject or a related method as defined in an implementation or sub-interface using a key that is equivalent to the one used to borrow the Object in the first place.
    Specified by:
    returnObject in interface KeyedObjectPool
    Overrides:
    returnObject in interface BaseKeyedObjectPool

    Parameters:
    key - the key used to obtain the object
    obj - a borrowed instance to be returned.


    setConfig

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

    See Also:
    GenericKeyedObjectPool.Config


    setFactory

    public void setFactory(KeyedPoolableObjectFactory factory)
                throws IllegalStateException
    Sets the factory I use to create new instances (optional operation).
    Specified by:
    setFactory in interface KeyedObjectPool
    Overrides:
    setFactory in interface BaseKeyedObjectPool

    Parameters:
    factory - the KeyedPoolableObjectFactory I use to create new instances.


    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.

    See Also:
    getMaxActive()


    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.

    See Also:
    getMaxIdle()


    setMaxTotal

    public void setMaxTotal(int maxTotal)
    Sets the cap on the total number of instances from my pool.

    Parameters:
    maxTotal - The cap on the total number of instances from my pool. Use a negative value for an infinite number of instances.

    See Also:
    getMaxTotal()


    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.

    See Also:
    getMaxWait(), setWhenExhaustedAction(byte), WHEN_EXHAUSTED_BLOCK


    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.

    See Also:
    getMinEvictableIdleTimeMillis(), setTimeBetweenEvictionRunsMillis(long)


    setNumTestsPerEvictionRun

    public void setNumTestsPerEvictionRun(int numTestsPerEvictionRun)

    See Also:
    getNumTestsPerEvictionRun(), setTimeBetweenEvictionRunsMillis(long)


    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.

    See Also:
    getTestOnBorrow()


    setTestOnReturn

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

    See Also:
    getTestOnReturn()


    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.

    See Also:
    getTestWhileIdle(), 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.

    See Also:
    getTimeBetweenEvictionRunsMillis()


    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). WHEN_EXHAUSTED_BLOCK, WHEN_EXHAUSTED_FAIL, or WHEN_EXHAUSTED_GROW

    Parameters:
    whenExhaustedAction - the action code, which must be one of

    See Also:
    getWhenExhaustedAction()


    Copyright © 2001-2003 Apache Software Foundation. Documenation generated May 21 2005.