GenericObjectPool (Apache Tomcat 7.0.104 API Documentation)

org.apache.tomcat.dbcp.pool.impl

## Class GenericObjectPool<T>

- java.lang.Object
- - org.apache.tomcat.dbcp.pool.BaseObjectPool<T>
  - - org.apache.tomcat.dbcp.pool.impl.GenericObjectPool<T>

- Type Parameters:
    `T` - the type of objects held in this pool
  All Implemented Interfaces:
    ObjectPool<T>
  Direct Known Subclasses:
    AbandonedObjectPool

      public class GenericObjectPool<T>
      extends BaseObjectPool<T>

  A configurable `ObjectPool` implementation.

  When coupled with the appropriate `PoolableObjectFactory`, `GenericObjectPool` provides robust pooling functionality for arbitrary objects.

  A `GenericObjectPool` provides a number of configurable parameters:

  - `maxActive` controls the maximum number of objects that can be allocated by the pool (checked out to clients, or idle awaiting checkout) at a given time. When non-positive, there is no limit to the number of objects that can be managed by the pool at one time. When `maxActive` is reached, the pool is said to be exhausted. The default setting for this parameter is 8.
  - `maxIdle` controls the maximum number of objects that can sit idle in the pool at any time. When negative, there is no limit to the number of objects that may be idle at one time. The default setting for this parameter is 8.
  - `whenExhaustedAction` specifies the behavior of the `borrowObject()` method when the 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 `Object.wait()`) until a new or idle object is available. If a positive `maxWait` value is supplied, then `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` and the default `maxWait` setting is -1. By default, therefore, `borrowObject` will block indefinitely until an idle instance becomes available.
  - 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 `PoolableObjectFactory.validateObject(T)` 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(T)` method. (Using the provided factory's `PoolableObjectFactory.validateObject(T)` 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 are available. 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., idle object eviction is disabled by default).
  - `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 `PoolableObjectFactory.validateObject(T)` method. 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.`
  - `softMinEvictableIdleTimeMillis` specifies 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), with the extra condition that at least "minIdle" object instances remain in the pool. When non-positive, no objects will be evicted from the pool due to idle time alone. This setting has no effect unless `timeBetweenEvictionRunsMillis > 0.` and it is superceded by `minEvictableIdleTimeMillis` (that is, if `minEvictableIdleTimeMillis` is positive, then `softMinEvictableIdleTimeMillis` is ignored). The default setting for this parameter is -1 (disabled).
  - `numTestsPerEvictionRun` determines the number of objects examined in each run of the idle object evictor. This setting has no effect unless `timeBetweenEvictionRunsMillis > 0.` The default setting for this parameter is 3.

  The pool can be configured to behave as a LIFO queue with respect to idle objects - always returning the most recently used object from the pool, or as a FIFO queue, where borrowObject always returns the oldest object in the idle object pool.

  - `lifo` determines whether or not the pool returns idle objects in last-in-first-out order. The default setting for this parameter is `true.`

  GenericObjectPool is not usable without a `PoolableObjectFactory`. A non-`null` factory must be provided either as a constructor argument or via a call to `setFactory(org.apache.tomcat.dbcp.pool.PoolableObjectFactory<T>)` 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
  Author:
    Rodney Waldhoff, Dirk Verbeeck, Sandy McArthur
  See Also:
    `GenericKeyedObjectPool`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `GenericObjectPool.Config` A simple "struct" encapsulating the configuration information for a `GenericObjectPool`.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static boolean` | `DEFAULT_LIFO` The default LIFO status.
    `static int` | `DEFAULT_MAX_ACTIVE` The default cap on the total number of active instances from the pool.
    `static int` | `DEFAULT_MAX_IDLE` The default cap on the number of "sleeping" instances in the pool.
    `static long` | `DEFAULT_MAX_WAIT` The default maximum amount of time (in milliseconds) the `borrowObject()` 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 number of "sleeping" instances in the pool before before the evictor thread (if active) spawns new objects.
    `static int` | `DEFAULT_NUM_TESTS_PER_EVICTION_RUN` The default number of objects to examine per run in the idle object evictor.
    `static long` | `DEFAULT_SOFT_MIN_EVICTABLE_IDLE_TIME_MILLIS` The default value for `getSoftMinEvictableIdleTimeMillis()`.
    `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()` 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()` 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()` method should simply create a new object anyway.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `GenericObjectPool()` Create a new `GenericObjectPool` with default properties.
    `GenericObjectPool(PoolableObjectFactory<T> factory)` Create a new `GenericObjectPool` using the specified factory.
    `GenericObjectPool(PoolableObjectFactory<T> factory, GenericObjectPool.Config config)` Create a new `GenericObjectPool` using the specified values.
    `GenericObjectPool(PoolableObjectFactory<T> factory, int maxActive)` Create a new `GenericObjectPool` using the specified values.
    `GenericObjectPool(PoolableObjectFactory<T> factory, int maxActive, byte whenExhaustedAction, long maxWait)` Create a new `GenericObjectPool` using the specified values.
    `GenericObjectPool(PoolableObjectFactory<T> factory, int maxActive, byte whenExhaustedAction, long maxWait, boolean testOnBorrow, boolean testOnReturn)` Create a new `GenericObjectPool` using the specified values.
    `GenericObjectPool(PoolableObjectFactory<T> factory, int maxActive, byte whenExhaustedAction, long maxWait, int maxIdle)` Create a new `GenericObjectPool` using the specified values.
    `GenericObjectPool(PoolableObjectFactory<T> factory, int maxActive, byte whenExhaustedAction, long maxWait, int maxIdle, boolean testOnBorrow, boolean testOnReturn)` Create a new `GenericObjectPool` using the specified values.
    `GenericObjectPool(PoolableObjectFactory<T> factory, int maxActive, byte whenExhaustedAction, long maxWait, int maxIdle, boolean testOnBorrow, boolean testOnReturn, long timeBetweenEvictionRunsMillis, int numTestsPerEvictionRun, long minEvictableIdleTimeMillis, boolean testWhileIdle)` Create a new `GenericObjectPool` using the specified values.
    `GenericObjectPool(PoolableObjectFactory<T> factory, int maxActive, byte whenExhaustedAction, long maxWait, int maxIdle, int minIdle, boolean testOnBorrow, boolean testOnReturn, long timeBetweenEvictionRunsMillis, int numTestsPerEvictionRun, long minEvictableIdleTimeMillis, boolean testWhileIdle)` Create a new `GenericObjectPool` using the specified values.
    `GenericObjectPool(PoolableObjectFactory<T> factory, int maxActive, byte whenExhaustedAction, long maxWait, int maxIdle, int minIdle, boolean testOnBorrow, boolean testOnReturn, long timeBetweenEvictionRunsMillis, int numTestsPerEvictionRun, long minEvictableIdleTimeMillis, boolean testWhileIdle, long softMinEvictableIdleTimeMillis)` Create a new `GenericObjectPool` using the specified values.
    `GenericObjectPool(PoolableObjectFactory<T> factory, int maxActive, byte whenExhaustedAction, long maxWait, int maxIdle, int minIdle, boolean testOnBorrow, boolean testOnReturn, long timeBetweenEvictionRunsMillis, int numTestsPerEvictionRun, long minEvictableIdleTimeMillis, boolean testWhileIdle, long softMinEvictableIdleTimeMillis, boolean lifo)` Create a new `GenericObjectPool` using the specified values.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addObject()` Create an object, and place it into the pool.
    `T` | `borrowObject()` Borrows an object from the pool.
    `void` | `clear()` Clears any objects sitting idle in the pool by removing them from the idle instance pool and then invoking the configured `PoolableObjectFactory.destroyObject(Object)` method on each idle instance.
    `void` | `close()` Closes the 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 pool acts as a LIFO queue.
    `int` | `getMaxActive()` Returns the maximum number of objects that can be allocated by the pool (checked out to clients, or idle awaiting checkout) at a given time.
    `int` | `getMaxIdle()` Returns the cap on the number of "idle" instances in the pool.
    `long` | `getMaxWait()` Returns the maximum amount of time (in milliseconds) the `borrowObject()` 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 objects allowed in the pool before the evictor thread (if active) spawns new objects.
    `int` | `getNumActive()` Return the number of instances currently borrowed from this pool.
    `int` | `getNumIdle()` Return the number of instances 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).
    `long` | `getSoftMinEvictableIdleTimeMillis()` 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), with the extra condition that at least "minIdle" amount of object remain in the pool.
    `boolean` | `getTestOnBorrow()` When `true`, objects will be `validated` before being returned by the `borrowObject()` method.
    `boolean` | `getTestOnReturn()` When `true`, objects will be `validated` before being returned to the pool within the `returnObject(T)`.
    `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()` method is invoked when the pool is exhausted (the maximum number of "active" objects has been reached).
    `void` | `invalidateObject(T obj)` Invalidates an object from the pool.
    `void` | `returnObject(T obj)` Returns an object instance to the pool.
    `void` | `setConfig(GenericObjectPool.Config conf)` Sets my configuration.
    `void` | `setFactory(PoolableObjectFactory<T> factory)` Deprecated. to be removed in version 2.0
    `void` | `setLifo(boolean lifo)` Sets the LIFO property of the pool.
    `void` | `setMaxActive(int maxActive)` Sets the cap on the number of objects that can be allocated by the pool (checked out to clients, or idle awaiting checkout) at a given time.
    `void` | `setMaxIdle(int maxIdle)` Sets the cap on the number of "idle" instances in the pool.
    `void` | `setMaxWait(long maxWait)` Sets the maximum amount of time (in milliseconds) the `borrowObject()` 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 minIdle)` Sets the minimum number of objects allowed in the pool before the evictor thread (if active) spawns new objects.
    `void` | `setNumTestsPerEvictionRun(int numTestsPerEvictionRun)` Sets the max number of objects to examine during each run of the idle object evictor thread (if any).
    `void` | `setSoftMinEvictableIdleTimeMillis(long softMinEvictableIdleTimeMillis)` 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), with the extra condition that at least "minIdle" object instances remain in the pool.
    `void` | `setTestOnBorrow(boolean testOnBorrow)` When `true`, objects will be `validated` before being returned by the `borrowObject()` method.
    `void` | `setTestOnReturn(boolean testOnReturn)` When `true`, objects will be `validated` before being returned to the pool within the `returnObject(T)`.
    `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()` 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.tomcat.dbcp.pool.BaseObjectPool

      `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()` 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()` 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()` 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 "sleeping" instances in the pool.
      See Also:
        `getMaxIdle()`, `setMaxIdle(int)`, Constant Field Values

    - #### DEFAULT_MIN_IDLE

          public static final int DEFAULT_MIN_IDLE

      The default minimum number of "sleeping" instances in the pool before before the evictor thread (if active) spawns new objects.
      See Also:
        `getMinIdle()`, `setMinIdle(int)`, Constant Field Values

    - #### DEFAULT_MAX_ACTIVE

          public static final int DEFAULT_MAX_ACTIVE

      The default cap on the total number of active instances from the pool.
      See Also:
        `getMaxActive()`, 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_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 the pool (if there are idle instances available). False means that the pool behaves as a FIFO queue - objects are taken from the idle object pool in the order that they are returned to the pool.
      Since:
        1.4
      See Also:
        `setLifo(boolean)`, Constant Field Values

    - #### DEFAULT_MAX_WAIT

          public static final long DEFAULT_MAX_WAIT

      The default maximum amount of time (in milliseconds) the `borrowObject()` 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_SOFT_MIN_EVICTABLE_IDLE_TIME_MILLIS

          public static final long DEFAULT_SOFT_MIN_EVICTABLE_IDLE_TIME_MILLIS

      The default value for `getSoftMinEvictableIdleTimeMillis()`.
      See Also:
        `getSoftMinEvictableIdleTimeMillis()`, `setSoftMinEvictableIdleTimeMillis(long)`, Constant Field Values

  - ### Constructor Detail

    - #### GenericObjectPool

          public GenericObjectPool()

      Create a new `GenericObjectPool` with default properties.

    - #### GenericObjectPool

          public GenericObjectPool(PoolableObjectFactory<T> factory)

      Create a new `GenericObjectPool` using the specified factory.
      Parameters:
        `factory` - the (possibly `null`)PoolableObjectFactory to use to create, validate and destroy objects

    - #### GenericObjectPool

          public GenericObjectPool(PoolableObjectFactory<T> factory,
                           GenericObjectPool.Config config)

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

    - #### GenericObjectPool

          public GenericObjectPool(PoolableObjectFactory<T> factory,
                           int maxActive)

      Create a new `GenericObjectPool` 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 (see `setMaxActive(int)`)

    - #### GenericObjectPool

          public GenericObjectPool(PoolableObjectFactory<T> factory,
                           int maxActive,
                           byte whenExhaustedAction,
                           long maxWait)

      Create a new `GenericObjectPool` 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 (see `setMaxActive(int)`)
        `whenExhaustedAction` - the action to take when the pool is exhausted (see `getWhenExhaustedAction()`)
        `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()`)

    - #### GenericObjectPool

          public GenericObjectPool(PoolableObjectFactory<T> factory,
                           int maxActive,
                           byte whenExhaustedAction,
                           long maxWait,
                           boolean testOnBorrow,
                           boolean testOnReturn)

      Create a new `GenericObjectPool` 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 at one time (see `setMaxActive(int)`)
        `whenExhaustedAction` - the action to take when the pool is exhausted (see `getWhenExhaustedAction()`)
        `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()`)
        `testOnBorrow` - whether or not to validate objects before they are returned by the `borrowObject()` method (see `getTestOnBorrow()`)
        `testOnReturn` - whether or not to validate objects after they are returned to the `returnObject(T)` method (see `getTestOnReturn()`)

    - #### GenericObjectPool

          public GenericObjectPool(PoolableObjectFactory<T> factory,
                           int maxActive,
                           byte whenExhaustedAction,
                           long maxWait,
                           int maxIdle)

      Create a new `GenericObjectPool` 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 at one time (see `setMaxActive(int)`)
        `whenExhaustedAction` - the action to take when the pool is exhausted (see `getWhenExhaustedAction()`)
        `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 `getMaxIdle()`)

    - #### GenericObjectPool

          public GenericObjectPool(PoolableObjectFactory<T> factory,
                           int maxActive,
                           byte whenExhaustedAction,
                           long maxWait,
                           int maxIdle,
                           boolean testOnBorrow,
                           boolean testOnReturn)

      Create a new `GenericObjectPool` 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 at one time (see `setMaxActive(int)`)
        `whenExhaustedAction` - the action to take when the pool is exhausted (see `getWhenExhaustedAction()`)
        `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 `getMaxIdle()`)
        `testOnBorrow` - whether or not to validate objects before they are returned by the `borrowObject()` method (see `getTestOnBorrow()`)
        `testOnReturn` - whether or not to validate objects after they are returned to the `returnObject(T)` method (see `getTestOnReturn()`)

    - #### GenericObjectPool

          public GenericObjectPool(PoolableObjectFactory<T> factory,
                           int maxActive,
                           byte whenExhaustedAction,
                           long maxWait,
                           int maxIdle,
                           boolean testOnBorrow,
                           boolean testOnReturn,
                           long timeBetweenEvictionRunsMillis,
                           int numTestsPerEvictionRun,
                           long minEvictableIdleTimeMillis,
                           boolean testWhileIdle)

      Create a new `GenericObjectPool` using the specified values.
      Parameters:
        `factory` - the (possibly `null`)PoolableObjectFactory to use to create, validate and destroy objects
        `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)`)
        `testOnBorrow` - whether or not to validate objects before they are returned by the `borrowObject()` method (see `setTestOnBorrow(boolean)`)
        `testOnReturn` - whether or not to validate objects after they are returned to the `returnObject(T)` 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)`)

    - #### GenericObjectPool

          public GenericObjectPool(PoolableObjectFactory<T> factory,
                           int maxActive,
                           byte whenExhaustedAction,
                           long maxWait,
                           int maxIdle,
                           int minIdle,
                           boolean testOnBorrow,
                           boolean testOnReturn,
                           long timeBetweenEvictionRunsMillis,
                           int numTestsPerEvictionRun,
                           long minEvictableIdleTimeMillis,
                           boolean testWhileIdle)

      Create a new `GenericObjectPool` using the specified values.
      Parameters:
        `factory` - the (possibly `null`)PoolableObjectFactory to use to create, validate and destroy objects
        `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)`)
        `minIdle` - the minimum number of idle objects in my pool (see `setMinIdle(int)`)
        `testOnBorrow` - whether or not to validate objects before they are returned by the `borrowObject()` method (see `setTestOnBorrow(boolean)`)
        `testOnReturn` - whether or not to validate objects after they are returned to the `returnObject(T)` 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)`)

    - #### GenericObjectPool

          public GenericObjectPool(PoolableObjectFactory<T> factory,
                           int maxActive,
                           byte whenExhaustedAction,
                           long maxWait,
                           int maxIdle,
                           int minIdle,
                           boolean testOnBorrow,
                           boolean testOnReturn,
                           long timeBetweenEvictionRunsMillis,
                           int numTestsPerEvictionRun,
                           long minEvictableIdleTimeMillis,
                           boolean testWhileIdle,
                           long softMinEvictableIdleTimeMillis)

      Create a new `GenericObjectPool` using the specified values.
      Parameters:
        `factory` - the (possibly `null`)PoolableObjectFactory to use to create, validate and destroy objects
        `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)`)
        `minIdle` - the minimum number of idle objects in my pool (see `setMinIdle(int)`)
        `testOnBorrow` - whether or not to validate objects before they are returned by the `borrowObject()` method (see `setTestOnBorrow(boolean)`)
        `testOnReturn` - whether or not to validate objects after they are returned to the `returnObject(T)` 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)`)
        `softMinEvictableIdleTimeMillis` - the minimum number of milliseconds an object can sit idle in the pool before it is eligible for eviction with the extra condition that at least "minIdle" amount of object remain in the pool. (see `setSoftMinEvictableIdleTimeMillis(long)`)
      Since:
        Pool 1.3

    - #### GenericObjectPool

          public GenericObjectPool(PoolableObjectFactory<T> factory,
                           int maxActive,
                           byte whenExhaustedAction,
                           long maxWait,
                           int maxIdle,
                           int minIdle,
                           boolean testOnBorrow,
                           boolean testOnReturn,
                           long timeBetweenEvictionRunsMillis,
                           int numTestsPerEvictionRun,
                           long minEvictableIdleTimeMillis,
                           boolean testWhileIdle,
                           long softMinEvictableIdleTimeMillis,
                           boolean lifo)

      Create a new `GenericObjectPool` 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 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)`)
        `minIdle` - the minimum number of idle objects in my pool (see `setMinIdle(int)`)
        `testOnBorrow` - whether or not to validate objects before they are returned by the `borrowObject()` method (see `setTestOnBorrow(boolean)`)
        `testOnReturn` - whether or not to validate objects after they are returned to the `returnObject(T)` 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)`)
        `softMinEvictableIdleTimeMillis` - the minimum number of milliseconds an object can sit idle in the pool before it is eligible for eviction with the extra condition that at least "minIdle" amount of object remain in the pool. (see `setSoftMinEvictableIdleTimeMillis(long)`)
        `lifo` - whether or not objects are returned in last-in-first-out order from the idle object pool (see `setLifo(boolean)`)
      Since:
        Pool 1.4

  - ### Method Detail

    - #### getMaxActive

          public int getMaxActive()

      Returns the maximum number of objects that can be allocated by the pool (checked out to clients, or idle awaiting checkout) at a given time. When non-positive, there is no limit to the number of objects that can be managed by the pool at one time.
      Returns:
        the cap on the total number of object instances managed by the pool.
      See Also:
        `setMaxActive(int)`

    - #### setMaxActive

          public void setMaxActive(int maxActive)

      Sets the cap on the number of objects that can be allocated by the pool (checked out to clients, or idle awaiting checkout) at a given time. Use a negative value for no limit.
      Parameters:
        `maxActive` - The cap on the total number of object instances managed by the pool. Negative values mean that there is no limit to the number of objects allocated by the pool.
      See Also:
        `getMaxActive()`

    - #### getWhenExhaustedAction

          public byte getWhenExhaustedAction()

      Returns the action to take when the `borrowObject()` 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()` 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()` 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()` method may block indefinitely.
      Returns:
        maximum number of milliseconds to block when borrowing an object.
      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()` 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()` method may block indefinitely.
      Parameters:
        `maxWait` - maximum number of milliseconds to block when borrowing an object.
      See Also:
        `getMaxWait()`, `setWhenExhaustedAction(byte)`, `WHEN_EXHAUSTED_BLOCK`

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

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

    - #### setMinIdle

          public void setMinIdle(int minIdle)

      Sets the minimum number of objects allowed in the pool before the evictor thread (if active) spawns new objects. Note that no objects are created when `numActive + numIdle >= maxActive.` This setting has no effect if the idle object evictor is disabled (i.e. if `timeBetweenEvictionRunsMillis <= 0`).

      If the configured value of minIdle is greater than the configured value for maxIdle then the value of maxIdle will be used instead.

      Parameters:
        `minIdle` - The minimum number of objects.
      See Also:
        `getMinIdle()`, `getTimeBetweenEvictionRunsMillis()`

    - #### getMinIdle

          public int getMinIdle()

      Returns the minimum number of objects allowed in the pool before the evictor thread (if active) spawns new objects. (Note no objects are created when: numActive + numIdle >= maxActive)

      If the configured value of minIdle is greater than the configured value for maxIdle then the value of maxIdle will be used instead.

      Returns:
        The minimum number of objects.
      See Also:
        `setMinIdle(int)`

    - #### getTestOnBorrow

          public boolean getTestOnBorrow()

      When `true`, objects will be `validated` before being returned by the `borrowObject()` 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()` method. If the object fails to validate, it will be dropped from the pool, and we will attempt to borrow another.
      Parameters:
        `testOnBorrow` - `true` if objects should be validated before being borrowed.
      See Also:
        `getTestOnBorrow()`

    - #### getTestOnReturn

          public boolean getTestOnReturn()

      When `true`, objects will be `validated` before being returned to the pool within the `returnObject(T)`.
      Returns:
        `true` when objects will be validated after returned to `returnObject(T)`.
      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(T)`.
      Parameters:
        `testOnReturn` - `true` so objects will be validated after returned to `returnObject(T)`.
      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:
        number of 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` - number of 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:
        max number of objects to examine during each evictor 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. That is, when the value is -n, roughly one nth 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 pool.

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

    - #### getMinEvictableIdleTimeMillis

          public long getMinEvictableIdleTimeMillis()

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

    - #### setMinEvictableIdleTimeMillis

          public void setMinEvictableIdleTimeMillis(long minEvictableIdleTimeMillis)

      Sets the minimum amount of time an object may sit idle in the pool before it is eligible for eviction by the idle object evictor (if any). When non-positive, no objects will be evicted from the pool due to idle time alone.
      Parameters:
        `minEvictableIdleTimeMillis` - minimum amount of time an object may sit idle in the pool before it is eligible for eviction.
      See Also:
        `getMinEvictableIdleTimeMillis()`, `setTimeBetweenEvictionRunsMillis(long)`

    - #### getSoftMinEvictableIdleTimeMillis

          public long getSoftMinEvictableIdleTimeMillis()

      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), with the extra condition that at least "minIdle" amount of object remain in the pool.
      Returns:
        minimum amount of time an object may sit idle in the pool before it is eligible for eviction.
      Since:
        Pool 1.3
      See Also:
        `setSoftMinEvictableIdleTimeMillis(long)`

    - #### setSoftMinEvictableIdleTimeMillis

          public void setSoftMinEvictableIdleTimeMillis(long softMinEvictableIdleTimeMillis)

      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), with the extra condition that at least "minIdle" object instances remain in the pool. When non-positive, no objects will be evicted from the pool due to idle time alone.
      Parameters:
        `softMinEvictableIdleTimeMillis` - minimum amount of time an object may sit idle in the pool before it is eligible for eviction.
      Since:
        Pool 1.3
      See Also:
        `getSoftMinEvictableIdleTimeMillis()`

    - #### 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 will be validated by the evictor.
      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 will be validated by the evictor.
      See Also:
        `getTestWhileIdle()`, `setTimeBetweenEvictionRunsMillis(long)`

    - #### getLifo

          public boolean getLifo()

      Whether or not the idle object pool acts as a LIFO queue. True means that borrowObject returns the most recently used ("last in") idle object in the pool (if there are idle instances available). False means that the pool behaves as a FIFO queue - objects are taken from the idle object pool in the order that they are returned to the pool.
      Returns:
        `true` if the pool is configured to act as a LIFO queue
      Since:
        1.4

    - #### setLifo

          public void setLifo(boolean lifo)

      Sets the LIFO property of the pool. True means that borrowObject returns the most recently used ("last in") idle object in the pool (if there are idle instances available). False means that the pool behaves as a FIFO queue - objects are taken from the idle object pool in the order that they are returned to the pool.
      Parameters:
        `lifo` - the new value for the LIFO property
      Since:
        1.4

    - #### setConfig

          public void setConfig(GenericObjectPool.Config conf)

      Sets my configuration.
      Parameters:
        `conf` - configuration to use.
      See Also:
        `GenericObjectPool.Config`

    - #### borrowObject

          public T borrowObject()
                         throws Exception

      Borrows an object from the pool.

      If there is an idle instance available in the pool, 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, behavior depends on the `maxActive` and (if applicable) `whenExhaustedAction` and `maxWait` properties. If the number of instances checked out from the pool is less than `maxActive,` a new instance is created, activated and (if applicable) validated and returned to the caller.

      If the 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). 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 `ObjectPool<T>`
      Specified by:
        `borrowObject` in class `BaseObjectPool<T>`
      Returns:
        object instance
      Throws:
        `NoSuchElementException` - if an instance cannot be returned
        `Exception` - if an instance cannot be obtained from the pool

    - #### invalidateObject

          public void invalidateObject(T obj)
                                throws Exception

      Invalidates an object from the pool.

      By contract, `obj` must have been obtained using `borrowObject`.

      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 and attempts to destroy the instance.

      Specified by:
        `invalidateObject` in interface `ObjectPool<T>`
      Specified by:
        `invalidateObject` in class `BaseObjectPool<T>`
      Parameters:
        `obj` - a `borrowed` instance to be disposed.
      Throws:
        `Exception` - if the configured `PoolableObjectFactory` throws an exception destroying obj

    - #### 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.destroyObject(Object)` method on each idle instance.

      Implementation notes:

      - This method does not destroy or effect in any way instances that are checked out of the pool 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 `ObjectPool<T>`
      Overrides:
        `clear` in class `BaseObjectPool<T>`

    - #### getNumActive

          public int getNumActive()

      Return the number of instances currently borrowed from this pool.
      Specified by:
        `getNumActive` in interface `ObjectPool<T>`
      Overrides:
        `getNumActive` in class `BaseObjectPool<T>`
      Returns:
        the number of instances currently borrowed from this pool

    - #### getNumIdle

          public int getNumIdle()

      Return the number of instances currently idle in this pool.
      Specified by:
        `getNumIdle` in interface `ObjectPool<T>`
      Overrides:
        `getNumIdle` in class `BaseObjectPool<T>`
      Returns:
        the number of instances currently idle in this pool

    - #### returnObject

          public void returnObject(T obj)
                            throws Exception

      Returns an object instance to the pool.

      If `maxIdle` is set to a positive value and the number of idle instances 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. In this case, if validation fails, the instance is destroyed.

      Note: There is no guard to prevent an object being returned to the pool multiple times. Clients are expected to discard references to returned objects and ensure that an object is not returned to the pool multiple times in sequence (i.e., without being borrowed again between returns). Violating this contract will result in the same object appearing multiple times in the pool and pool counters (numActive, numIdle) returning incorrect values.

      Specified by:
        `returnObject` in interface `ObjectPool<T>`
      Specified by:
        `returnObject` in class `BaseObjectPool<T>`
      Parameters:
        `obj` - instance to return to the pool
      Throws:
        `Exception`

    - #### close

          public void close()
                     throws Exception

      Closes the pool. Once the pool is closed, `borrowObject()` will fail with IllegalStateException, but `returnObject(Object)` and `invalidateObject(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 `ObjectPool<T>`
      Overrides:
        `close` in class `BaseObjectPool<T>`
      Throws:
        `Exception`

    - #### setFactory

          @Deprecated
          public void setFactory(PoolableObjectFactory<T> factory)
                          throws IllegalStateException

      Deprecated. to be removed in version 2.0
      Sets the `factory` this pool uses to create new instances. Trying to change the `factory` while there are borrowed objects will throw an `IllegalStateException`. If there are instances idle in the pool when this method is invoked, these will be destroyed using the original factory.
      Specified by:
        `setFactory` in interface `ObjectPool<T>`
      Overrides:
        `setFactory` in class `BaseObjectPool<T>`
      Parameters:
        `factory` - the `PoolableObjectFactory` used to create new instances.
      Throws:
        `IllegalStateException` - when the factory cannot be set at this time

    - #### 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 in sequence, cycling through objects in oldest-to-youngest order.

      Throws:
        `Exception` - if the pool is closed or eviction fails.

    - #### addObject

          public void addObject()
                         throws Exception

      Create an object, and place it into the pool. addObject() is useful for "pre-loading" a pool with idle objects.
      Specified by:
        `addObject` in interface `ObjectPool<T>`
      Overrides:
        `addObject` in class `BaseObjectPool<T>`
      Throws:
        `Exception` - when `PoolableObjectFactory.makeObject()` fails.
        `IllegalStateException` - after `ObjectPool.close()` has been called on this pool.
        `UnsupportedOperationException` - when this pool cannot add new idle objects.

    - #### startEvictor

          protected void startEvictor(long delay)

      Start the eviction thread or service, or when delay is non-positive, stop it if it is already running.
      Parameters:
        `delay` - milliseconds between evictor runs.

Copyright © 2000-2020 Apache Software Foundation. All Rights Reserved.