Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.apache.commons.pool.impl
Class GenericKeyedObjectPool

    java.lang.Object
      org.apache.commons.pool.BaseKeyedObjectPool
          org.apache.commons.pool.impl.GenericKeyedObjectPool

All 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 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:

- `maxActive` controls the maximum number of objects (per key) that can allocated by the pool (checked out to client threads, or idle in the pool) at one time. When non-positive, there is no limit to the number of objects per key. When `maxActive` is reached, the keyed pool is said to be exhausted. The default setting for this parameter is 8.
- `maxTotal` sets a global limit on the number of objects that can be in circulation (active or idle) within the combined set of pools. When non-positive, there is no limit to the total number of objects in circulation. When `maxTotal` is exceeded, all keyed pools are exhausted. 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. The default setting for this parameter is -1 (no limit).
- `maxIdle` controls the maximum number of objects that can sit idle in the pool (per key) at any time. When negative, there is no limit to the number of objects that may be idle per key. The default setting for this parameter is 8.
- `whenExhaustedAction` specifies the behavior of the `borrowObject` method when a keyed pool is exhausted:
  - When `whenExhaustedAction` is `WHEN_EXHAUSTED_FAIL`, `borrowObject` will throw a `NoSuchElementException`
  - When `whenExhaustedAction` is `WHEN_EXHAUSTED_GROW`, `borrowObject` will create a new object and return it (essentially making `maxActive` meaningless.)
  - When `whenExhaustedAction` is `WHEN_EXHAUSTED_BLOCK`, `borrowObject` will block (invoke `wait` until a new or idle object is available. If a positive `maxWait` value is supplied, the `borrowObject` will block for at most that many milliseconds, after which a `NoSuchElementException` will be thrown. If `maxWait` is non-positive, the `borrowObject` method will block indefinitely.
  The default `whenExhaustedAction` setting is `WHEN_EXHAUSTED_BLOCK`.
- When `testOnBorrow` is set, the pool will attempt to validate each object before it is returned from the `borrowObject` method. (Using the provided factory's `validateObject` method.) Objects that fail to validate will be dropped from the pool, and a different object will be borrowed. The default setting for this parameter is `false.`
- When `testOnReturn` is set, the pool will attempt to validate each object before it is returned to the pool in the `returnObject` method. (Using the provided factory's `validateObject` method.) Objects that fail to validate will be dropped from the pool. The default setting for this parameter is `false.`

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 contend with client threads for access to objects in the pool, so if they run too frequently performance issues may result. The idle object eviction thread may be configured using the following attributes:

- `timeBetweenEvictionRunsMillis` indicates how long the eviction thread should sleep before "runs" of examining idle objects. When non-positive, no eviction thread will be launched. The default setting for this parameter is -1 (i.e., by default, idle object eviction is disabled).
- `minEvictableIdleTimeMillis` specifies the minimum amount of time that an object may sit idle in the pool before it is eligible for eviction due to idle time. When non-positive, no object will be dropped from the pool due to idle time alone. This setting has no effect unless `timeBetweenEvictionRunsMillis > 0.` The default setting for this parameter is 30 minutes.
- `testWhileIdle` indicates whether or not idle objects should be validated using the factory's `validateObject` method during idle object eviction runs. Objects that fail to validate will be dropped from the pool. This setting has no effect unless `timeBetweenEvictionRunsMillis > 0.` The default setting for this parameter is `false.`
- `minIdle` sets a target value for the minimum number of idle objects (per key) that should always be available. If this parameter is set to a positive number and `timeBetweenEvictionRunsMillis > 0,` each time the idle object eviction thread runs, it will try to create enough idle instances so that there will be `minIdle` idle instances available under each key. This parameter is also used by `preparePool` if `true` is provided as that method's `populateImmediately` parameter. The default setting for this parameter is 0.

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.

- `Lifo` determines whether or not the pools return idle objects in last-in-first-out order. The default setting for this parameter is `true.`

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.

Implementation note: To prevent possible deadlocks, care has been taken to ensure that no call to a factory method will occur within a synchronization block. See POOL-125 and DBCP-44 for more information.

Since:
  Pool 1.0
Version:
  $Revision: 1086190 $ $Date: 2011-03-28 04:22:08 -0700 (Mon, 28 Mar 2011) $
Author:
  Rodney Waldhoff, Dirk Verbeeck, Sandy McArthur
See Also:
  `GenericObjectPool`

Nested Class Summary
`static class` | `GenericKeyedObjectPool.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
`GenericKeyedObjectPool()` Create a new `GenericKeyedObjectPool` with no factory.
`GenericKeyedObjectPool(KeyedPoolableObjectFactory factory)` Create a new `GenericKeyedObjectPool` using the specified values.
`GenericKeyedObjectPool(KeyedPoolableObjectFactory factory, GenericKeyedObjectPool.Config config)` 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, 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)` Borrows an object from the keyed pool associated with the given key.
`void` | `clear()` Clears any objects sitting idle in the pool by removing them from the idle instance pool and then invoking the configured PoolableObjectFactory's `KeyedPoolableObjectFactory.destroyObject(Object, Object)` method on each idle instance.
`void` | `clear(Object key)` Clears the specified pool, removing all pooled instances corresponding to the given `key`.
`void` | `clearOldest()` Clears oldest 15% of objects in pool.
`void` | `close()` Closes the keyed object pool.
`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 object instances allocated by the pool (checked out or idle), 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 max 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)` Invalidates an object from the pool.
`void` | `preparePool(Object key, boolean populateImmediately)` Registers a key for pool control.
`void` | `returnObject(Object key, Object obj)` Returns an object to a keyed pool.
`void` | `setConfig(GenericKeyedObjectPool.Config conf)` Sets the configuration.
`void` | `setFactory(KeyedPoolableObjectFactory factory)` Deprecated. to be removed in version 2.0
`void` | `setLifo(boolean lifo)` Sets the LIFO property of the pools.
`void` | `setMaxActive(int maxActive)` Sets the cap on the number of object instances managed by the 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 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 max 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

### GenericKeyedObjectPool

    public GenericKeyedObjectPool()

  Create a new `GenericKeyedObjectPool` with no factory.

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

### GenericKeyedObjectPool

    public GenericKeyedObjectPool(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`

### GenericKeyedObjectPool

    public GenericKeyedObjectPool(KeyedPoolableObjectFactory factory,
                                  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

### GenericKeyedObjectPool

    public GenericKeyedObjectPool(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)`)

### GenericKeyedObjectPool

    public GenericKeyedObjectPool(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)`)

### 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 `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)`)

### GenericKeyedObjectPool

    public GenericKeyedObjectPool(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)`)

### 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 `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)`)

### 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 `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)`)

### 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 `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)`)

### 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 `KeyedPoolableObjectFactory` to use to create, validate, and destroy objects if not `null`
    `maxActive` - the maximum number of objects that can be borrowed 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

### 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,
                                  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 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 object instances allocated by the pool (checked out or idle), 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 object instances managed by the pool per key.

  Parameters:
    `maxActive` - The cap on the number of object 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. If maxIdle is set too low on heavily loaded systems it is possible you will see objects being destroyed and almost immediately new objects being created. This is a result of the active threads momentarily returning objects faster than they are requesting them them, causing the number of idle objects to rise above maxIdle. The best value for maxIdle for heavily loaded system will vary but the default is a good starting point.

  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 max 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 max 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 `n`th of the idle objects will be tested per run. When the value is positive, the number of tests actually performed in each run will be the minimum of this value and the number of instances idle in the pools.

  Parameters:
    `numTestsPerEvictionRun` - number of objects to examine each eviction run.
  See Also:
    `setNumTestsPerEvictionRun(int)`, `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(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

  Borrows an object from the keyed pool associated with the given key.

  If there is an idle instance available in the pool associated with the given key, then either the most-recently returned (if `lifo` == true) or "oldest" (lifo == false) instance sitting idle in the pool will be activated and returned. If activation fails, or `testOnBorrow` is set to true and validation fails, the instance is destroyed and the next available instance is examined. This continues until either a valid instance is returned or there are no more idle instances available.

  If there are no idle instances available in the pool associated with the given key, behavior depends on the `maxActive`, `maxTotal`, and (if applicable) `whenExhaustedAction` and `maxWait` properties. If the number of instances checked out from the pool under the given key is less than `maxActive` and the total number of instances in circulation (under all keys) is less than `maxTotal`, a new instance is created, activated and (if applicable) validated and returned to the caller.

  If the associated keyed pool is exhausted (no available idle instances and no capacity to create new ones), this method will either block (`WHEN_EXHAUSTED_BLOCK`), throw a `NoSuchElementException` (`WHEN_EXHAUSTED_FAIL`), or grow (`WHEN_EXHAUSTED_GROW` - ignoring maxActive, maxTotal properties). The length of time that this method will block when `whenExhaustedAction == WHEN_EXHAUSTED_BLOCK` is determined by the `maxWait` property.

  When the pool is exhausted, multiple calling threads may be simultaneously blocked waiting for instances to become available. As of pool 1.5, a "fairness" algorithm has been implemented to ensure that threads receive available instances in request arrival order.

  Specified by:
    `borrowObject` in interface `KeyedObjectPool`
  Specified by:
    `borrowObject` in class `BaseKeyedObjectPool`
  Parameters:
    `key` - pool key
  Returns:
    object instance from the keyed pool
  Throws:
    `NoSuchElementException` - if a keyed object instance cannot be returned.
    `IllegalStateException` - after `close` has been called on this pool
    `Exception` - when `makeObject` throws an exception

### clear

    public void clear()

  Clears any objects sitting idle in the pool by removing them from the idle instance pool and then invoking the configured PoolableObjectFactory's `KeyedPoolableObjectFactory.destroyObject(Object, Object)` method on each idle instance.

  Implementation notes:

  - This method does not destroy or effect in any way instances that are checked out when it is invoked.
  - Invoking this method does not prevent objects being returned to the idle instance pool, even during its execution. It locks the pool only during instance removal. Additional instances may be returned while removed items are being destroyed.
  - Exceptions encountered destroying idle instances are swallowed.

  Specified by:
    `clear` in interface `KeyedObjectPool`
  Overrides:
    `clear` in class `BaseKeyedObjectPool`

### clearOldest

    public void clearOldest()

  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 `KeyedObjectPool`
  Overrides:
    `clear` in class `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 `KeyedObjectPool`
  Overrides:
    `getNumActive` in class `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 `KeyedObjectPool`
  Overrides:
    `getNumIdle` in class `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 `KeyedObjectPool`
  Overrides:
    `getNumActive` in class `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 `KeyedObjectPool`
  Overrides:
    `getNumIdle` in class `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

  Returns an object to a keyed pool.

  For the pool to function correctly, the object instance must have been borrowed from the pool (under the same key) and not yet returned. Repeated `returnObject` calls on the same object/key pair (with no `borrowObject` calls in between) will result in multiple references to the object in the idle instance pool.

  If `maxIdle` is set to a positive value and the number of idle instances under the given key has reached this value, the returning instance is destroyed.

  If `testOnReturn` == true, the returning instance is validated before being returned to the idle instance pool under the given key. In this case, if validation fails, the instance is destroyed.

  Specified by:
    `returnObject` in interface `KeyedObjectPool`
  Specified by:
    `returnObject` in class `BaseKeyedObjectPool`
  Parameters:
    `key` - pool key
    `obj` - instance to return to the keyed pool
  Throws:
    `Exception`

### 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` 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.

  Activation of this method decrements the active count associated with the given keyed pool and attempts to destroy `obj.`

  Specified by:
    `invalidateObject` in interface `KeyedObjectPool`
  Specified by:
    `invalidateObject` in class `BaseKeyedObjectPool`
  Parameters:
    `key` - pool key
    `obj` - instance to invalidate
  Throws:
    `Exception` - if an exception occurs destroying the object

### 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 `KeyedObjectPool`
  Overrides:
    `addObject` in class `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

  Closes the keyed object pool. Once the pool is closed, `borrowObject(Object)` will fail with IllegalStateException, but `returnObject(Object, Object)` and `invalidateObject(Object, Object)` will continue to work, with returned objects destroyed on return.

  Destroys idle instances in the pool by invoking `clear()`.

  Specified by:
    `close` in interface `KeyedObjectPool`
  Overrides:
    `close` in class `BaseKeyedObjectPool`
  Throws:
    `Exception`

### setFactory

    public void setFactory(KeyedPoolableObjectFactory factory)
                    throws IllegalStateException

  Deprecated. to be removed in version 2.0

  Sets the keyed poolable object factory associated with this pool.

  If this method is called when objects are checked out of any of the keyed pools, an IllegalStateException is thrown. Calling this method also has the side effect of destroying any idle instances in existing keyed pools, using the original factory.

  Specified by:
    `setFactory` in interface `KeyedObjectPool`
  Overrides:
    `setFactory` in class `BaseKeyedObjectPool`
  Parameters:
    `factory` - KeyedPoolableObjectFactory to use when creating keyed object pool instances
  Throws:
    `IllegalStateException` - if there are active (checked out) instances associated with this keyed object pool

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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2001-2011 The Apache Software Foundation. All Rights Reserved.