Package org.apache.commons.pool.impl

Class GenericKeyedObjectPool<K,​V>

  • Type Parameters:
    K - the type of keys in this pool
    V - the type of objects held in this pool
    All Implemented Interfaces:
    KeyedObjectPool<K,​V>
    public class GenericKeyedObjectPool<K,​V>
extends BaseKeyedObjectPool<K,​V>
implements KeyedObjectPool<K,​V>
    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: 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: 1222396 $ $Date: 2011-12-22 14:02:25 -0500 (Thu, 22 Dec 2011) $
    Author:
    Rodney Waldhoff, Dirk Verbeeck, Sandy McArthur
    See Also:
    GenericObjectPool

    • Constructor Detail

      • GenericKeyedObjectPool

        public GenericKeyedObjectPool​(KeyedPoolableObjectFactory<K,​V> 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<K,​V> 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<K,​V> 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<K,​V> 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(K) method (see setTestOnBorrow(boolean))
        testOnReturn - whether or not to validate objects after they are returned to the returnObject(K, V) method (see setTestOnReturn(boolean))

      • GenericKeyedObjectPool

        public GenericKeyedObjectPool​(KeyedPoolableObjectFactory<K,​V> 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<K,​V> 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(K) method (see setTestOnBorrow(boolean))
        testOnReturn - whether or not to validate objects after they are returned to the returnObject(K, V) method (see setTestOnReturn(boolean))

      • GenericKeyedObjectPool

        public GenericKeyedObjectPool​(KeyedPoolableObjectFactory<K,​V> 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(K) method (see setTestOnBorrow(boolean))
        testOnReturn - whether or not to validate objects after they are returned to the returnObject(K, V) 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<K,​V> 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(K) method (see setTestOnBorrow(boolean))
        testOnReturn - whether or not to validate objects after they are returned to the returnObject(K, V) 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<K,​V> 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(K) method (see setTestOnBorrow(boolean))
        testOnReturn - whether or not to validate objects after they are returned to the returnObject(K, V) 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<K,​V> 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(K) method (see setTestOnBorrow(boolean))
        testOnReturn - whether or not to validate objects after they are returned to the returnObject(K, V) 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()

      • 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(K) 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(K) 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(K, V).
        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(K, V).
        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()

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

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

      • 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 V borrowObject​(K 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<K,​V>
        Specified by:
        borrowObject in class BaseKeyedObjectPool<K,​V>
        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<K,​V>
        Overrides:
        clear in class BaseKeyedObjectPool<K,​V>

      • 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​(K key)
        Clears the specified pool, removing all pooled instances corresponding to the given key.
        Specified by:
        clear in interface KeyedObjectPool<K,​V>
        Overrides:
        clear in class BaseKeyedObjectPool<K,​V>
        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<K,​V>
        Overrides:
        getNumActive in class BaseKeyedObjectPool<K,​V>
        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<K,​V>
        Overrides:
        getNumIdle in class BaseKeyedObjectPool<K,​V>
        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<K,​V>
        Overrides:
        getNumActive in class BaseKeyedObjectPool<K,​V>
        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<K,​V>
        Overrides:
        getNumIdle in class BaseKeyedObjectPool<K,​V>
        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​(K key,
                         V 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<K,​V>
        Specified by:
        returnObject in class BaseKeyedObjectPool<K,​V>
        Parameters:
        key - pool key
        obj - instance to return to the keyed pool
        Throws:
        Exception

      • invalidateObject

        public void invalidateObject​(K key,
                             V 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<K,​V>
        Specified by:
        invalidateObject in class BaseKeyedObjectPool<K,​V>
        Parameters:
        key - pool key
        obj - instance to invalidate
        Throws:
        Exception - if an exception occurs destroying the object

      • preparePool

        public void preparePool​(K 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

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