Class GenericObjectPool<T>

  • Type Parameters:
    T - the type of objects held in this pool
    All Implemented Interfaces:
    ObjectPool<T>

    public class GenericObjectPool<T>
    extends BaseObjectPool<T>
    implements ObjectPool<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: 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.commons.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
    Version:
    $Revision: 1222396 $ $Date: 2011-12-22 14:02:25 -0500 (Thu, 22 Dec 2011) $
    See Also:
    GenericKeyedObjectPool
    • Constructor Summary

      Constructors 
      Constructor 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, 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.
      GenericObjectPool​(PoolableObjectFactory<T> factory, GenericObjectPool.Config config)
      Create a new GenericObjectPool using the specified values.
    • Method Summary

      All Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      void addObject()
      Create an object, and place it into the pool.
      private void addObjectToPool​(T obj, boolean decrementNumActive)
      Adds an object to the pool.
      private void allocate()
      Allocate available instances to latches in the allocation queue.
      T borrowObject()
      Borrows an object from the pool.
      private int calculateDeficit​(boolean incrementInternal)
      This returns the number of objects to create during the pool sustain cycle.
      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.
      (package private) java.lang.String debugInfo()
      Returns pool info including getNumActive(), getNumIdle() and a list of objects idle in the pool with their idle times.
      private void destroy​(java.util.Collection<GenericKeyedObjectPool.ObjectTimestampPair<T>> c, PoolableObjectFactory<T> factory)
      Private method to destroy all the objects in a collection using the supplied object factory.
      private void ensureMinIdle()
      Check to see if we are below our minimum number of objects if so enough to bring us back to our minimum.
      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.
      private int getNumTests()
      Returns the number of tests to be performed in an Evictor run, based on the current value of numTestsPerEvictionRun and the number of idle instances in the 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 java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • 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()
      • 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).
        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)
        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()
      • 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()
      • 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()
      • 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
      • borrowObject

        public T borrowObject()
                       throws java.lang.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:
        java.util.NoSuchElementException - if an instance cannot be returned
        java.lang.Exception - if an instance cannot be obtained from the pool
      • allocate

        private void allocate()
        Allocate available instances to latches in the allocation queue. Then set _mayCreate to true for as many additional latches remaining in queue as _maxActive allows. While it is safe for GOP, for consistency with GKOP this method should not be called from inside a sync block.
      • invalidateObject

        public void invalidateObject​(T obj)
                              throws java.lang.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:
        java.lang.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>
      • destroy

        private void destroy​(java.util.Collection<GenericKeyedObjectPool.ObjectTimestampPair<T>> c,
                             PoolableObjectFactory<T> factory)
        Private method to destroy all the objects in a collection using the supplied object factory. Assumes that objects in the collection are instances of ObjectTimestampPair and that the object instances that they wrap were created by the factory.
        Parameters:
        c - Collection of objects to destroy
        factory - PoolableConnectionFactory used to destroy the objects
      • 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 java.lang.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:
        java.lang.Exception
      • addObjectToPool

        private void addObjectToPool​(T obj,
                                     boolean decrementNumActive)
                              throws java.lang.Exception

        Adds an object to the pool.

        Validates the object if testOnReturn == true and passivates it before returning it to the pool. if validation or passivation fails, or maxIdle is set and there is no room in the pool, the instance is destroyed.

        Calls allocate() on successful completion

        Parameters:
        obj - instance to add to the pool
        decrementNumActive - whether or not to decrement the active count
        Throws:
        java.lang.Exception
      • setFactory

        @Deprecated
        public void setFactory​(PoolableObjectFactory<T> factory)
                        throws java.lang.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:
        java.lang.IllegalStateException - when the factory cannot be set at this time
      • evict

        public void evict()
                   throws java.lang.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:
        java.lang.Exception - if the pool is closed or eviction fails.
      • ensureMinIdle

        private void ensureMinIdle()
                            throws java.lang.Exception
        Check to see if we are below our minimum number of objects if so enough to bring us back to our minimum.
        Throws:
        java.lang.Exception - when addObject() fails.
      • calculateDeficit

        private int calculateDeficit​(boolean incrementInternal)
        This returns the number of objects to create during the pool sustain cycle. This will ensure that the minimum number of idle instances is maintained without going past the maxActive value.
        Parameters:
        incrementInternal - - Should the count of objects currently under some form of internal processing be incremented?
        Returns:
        The number of objects to be created
      • addObject

        public void addObject()
                       throws java.lang.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:
        java.lang.Exception - when PoolableObjectFactory.makeObject() fails.
        java.lang.IllegalStateException - after ObjectPool.close() has been called on this pool.
        java.lang.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.
      • debugInfo

        java.lang.String debugInfo()
        Returns pool info including getNumActive(), getNumIdle() and a list of objects idle in the pool with their idle times.
        Returns:
        string containing debug information
      • getNumTests

        private int getNumTests()
        Returns the number of tests to be performed in an Evictor run, based on the current value of numTestsPerEvictionRun and the number of idle instances in the pool.
        Returns:
        the number of tests for the Evictor to run
        See Also:
        setNumTestsPerEvictionRun(int)