/* * Copyright 1999-2004 The Apache Software Foundation. *  * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at *  *      http://www.apache.org/licenses/LICENSE-2.0 *  * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */package org.apache.commons.pool.impl;import java.util.Iterator;import java.util.NoSuchElementException;import java.util.LinkedList;import java.util.ListIterator;import java.util.Timer;import java.util.TimerTask;import org.apache.commons.pool.BaseObjectPool;import org.apache.commons.pool.ObjectPool;import org.apache.commons.pool.PoolableObjectFactory;import org.apache.commons.pool.impl.GenericKeyedObjectPool.ObjectTimestampPair;/** * A configurable {@link ObjectPool} implementation. * <p> * When coupled with the appropriate {@link PoolableObjectFactory}, * <tt>GenericObjectPool</tt> provides robust pooling functionality for * arbitrary objects. * <p> * A <tt>GenericObjectPool</tt> provides a number of configurable parameters: * <ul> *  <li> *    {@link #setMaxActive <i>maxActive</i>} controls the maximum number of objects that can *    be borrowed from the pool at one time.  When non-positive, there *    is no limit to the number of objects that may be active at one time. *    When {@link #setMaxActive <i>maxActive</i>} is exceeded, the pool is said to be exhausted. *  </li> *  <li> *    {@link #setMaxIdle <i>maxIdle</i>} 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. *  </li> *  <li> *    {@link #setWhenExhaustedAction <i>whenExhaustedAction</i>} specifies the *    behaviour of the {@link #borrowObject} method when the pool is exhausted: *    <ul> *    <li> *      When {@link #setWhenExhaustedAction <i>whenExhaustedAction</i>} is *      {@link #WHEN_EXHAUSTED_FAIL}, {@link #borrowObject} will throw *      a {@link NoSuchElementException} *    </li> *    <li> *      When {@link #setWhenExhaustedAction <i>whenExhaustedAction</i>} is *      {@link #WHEN_EXHAUSTED_GROW}, {@link #borrowObject} will create a new *      object and return it(essentially making {@link #setMaxActive <i>maxActive</i>} *      meaningless.) *    </li> *    <li> *      When {@link #setWhenExhaustedAction <i>whenExhaustedAction</i>} *      is {@link #WHEN_EXHAUSTED_BLOCK}, {@link #borrowObject} will block *      (invoke {@link Object#wait} until a new or idle object is available. *      If a positive {@link #setMaxWait <i>maxWait</i>} *      value is supplied, the {@link #borrowObject} will block for at *      most that many milliseconds, after which a {@link NoSuchElementException} *      will be thrown.  If {@link #setMaxWait <i>maxWait</i>} is non-positive, *      the {@link #borrowObject} method will block indefinitely. *    </li> *    </ul> *  </li> *  <li> *    When {@link #setTestOnBorrow <i>testOnBorrow</i>} is set, the pool will *    attempt to validate each object before it is returned from the *    {@link #borrowObject} method. (Using the provided factory's *    {@link PoolableObjectFactory#validateObject} method.)  Objects that fail *    to validate will be dropped from the pool, and a different object will *    be borrowed. *  </li> *  <li> *    When {@link #setTestOnReturn <i>testOnReturn</i>} is set, the pool will *    attempt to validate each object before it is returned to the pool in the *    {@link #returnObject} method. (Using the provided factory's *    {@link PoolableObjectFactory#validateObject} *    method.)  Objects that fail to validate will be dropped from the pool. *  </li> * </ul> * <p> * Optionally, one may configure the pool to examine and possibly evict objects as they * sit idle in the pool.  This is performed by an "idle object eviction" thread, which * runs asychronously.  The idle object eviction thread may be configured using the * following attributes: * <ul> *  <li> *   {@link #setTimeBetweenEvictionRunsMillis <i>timeBetweenEvictionRunsMillis</i>} *   indicates how long the eviction thread should sleep before "runs" of examining *   idle objects.  When non-positive, no eviction thread will be launched. *  </li> *  <li> *   {@link #setMinEvictableIdleTimeMillis <i>minEvictableIdleTimeMillis</i>} *   specifies the minimum amount of time that an object may sit idle in the pool *   before it is eligable for eviction due to idle time.  When non-positive, no object *   will be dropped from the pool due to idle time alone. *  </li> *  <li> *   {@link #setTestWhileIdle <i>testWhileIdle</i>} indicates whether or not idle *   objects should be validated using the factory's *   {@link PoolableObjectFactory#validateObject} method.  Objects *   that fail to validate will be dropped from the pool. *  </li> * </ul> * <p> * GenericObjectPool is not usable without a {@link PoolableObjectFactory}.  A * non-<code>null</code> factory must be provided either as a constructor argument * or via a call to {@link #setFactory} before the pool is used. * * @see GenericKeyedObjectPool * @author Rodney Waldhoff * @author Dirk Verbeeck * @version $Revision: 1.2 $ $Date: 2006/05/16 01:31:42 $ */public class GenericObjectPool extends BaseObjectPool implements ObjectPool {    //--- public constants -------------------------------------------    /**     * A "when exhausted action" type indicating that when the pool is     * exhausted (i.e., the maximum number of active objects has     * been reached), the {@link #borrowObject}     * method should fail, throwing a {@link NoSuchElementException}.     * @see #WHEN_EXHAUSTED_BLOCK     * @see #WHEN_EXHAUSTED_GROW     * @see #setWhenExhaustedAction     */    public static final byte WHEN_EXHAUSTED_FAIL   = 0;    /**     * A "when exhausted action" type indicating that when the pool     * is exhausted (i.e., the maximum number     * of active objects has been reached), the {@link #borrowObject}     * method should block until a new object is available, or the     * {@link #getMaxWait maximum wait time} has been reached.     * @see #WHEN_EXHAUSTED_FAIL     * @see #WHEN_EXHAUSTED_GROW     * @see #setMaxWait     * @see #getMaxWait     * @see #setWhenExhaustedAction     */    public static final byte WHEN_EXHAUSTED_BLOCK  = 1;    /**     * A "when exhausted action" type indicating that when the pool is     * exhausted (i.e., the maximum number     * of active objects has been reached), the {@link #borrowObject}     * method should simply create a new object anyway.     * @see #WHEN_EXHAUSTED_FAIL     * @see #WHEN_EXHAUSTED_GROW     * @see #setWhenExhaustedAction     */    public static final byte WHEN_EXHAUSTED_GROW   = 2;    /**     * The default cap on the number of "sleeping" instances in the pool.     * @see #getMaxIdle     * @see #setMaxIdle     */    public static final int DEFAULT_MAX_IDLE  = 8;    /**     * The default minimum number of "sleeping" instances in the pool     * before before the evictor thread (if active) spawns new objects.     * @see #getMinIdle     * @see #setMinIdle     */    public static final int DEFAULT_MIN_IDLE = 0;    /**     * The default cap on the total number of active instances from the pool.     * @see #getMaxActive     */    public static final int DEFAULT_MAX_ACTIVE  = 8;    /**     * The default "when exhausted action" for the pool.     * @see #WHEN_EXHAUSTED_BLOCK     * @see #WHEN_EXHAUSTED_FAIL     * @see #WHEN_EXHAUSTED_GROW     * @see #setWhenExhaustedAction     */    public static final byte DEFAULT_WHEN_EXHAUSTED_ACTION = WHEN_EXHAUSTED_BLOCK;    /**     * The default maximum amount of time (in millis) the     * {@link #borrowObject} method should block before throwing     * an exception when the pool is exhausted and the     * {@link #getWhenExhaustedAction "when exhausted" action} is     * {@link #WHEN_EXHAUSTED_BLOCK}.     * @see #getMaxWait     * @see #setMaxWait     */    public static final long DEFAULT_MAX_WAIT = -1L;    /**     * The default "test on borrow" value.     * @see #getTestOnBorrow     * @see #setTestOnBorrow     */    public static final boolean DEFAULT_TEST_ON_BORROW = false;    /**     * The default "test on return" value.     * @see #getTestOnReturn     * @see #setTestOnReturn     */    public static final boolean DEFAULT_TEST_ON_RETURN = false;    /**     * The default "test while idle" value.     * @see #getTestWhileIdle     * @see #setTestWhileIdle     * @see #getTimeBetweenEvictionRunsMillis     * @see #setTimeBetweenEvictionRunsMillis     */    public static final boolean DEFAULT_TEST_WHILE_IDLE = false;    /**     * The default "time between eviction runs" value.     * @see #getTimeBetweenEvictionRunsMillis     * @see #setTimeBetweenEvictionRunsMillis     */    public static final long DEFAULT_TIME_BETWEEN_EVICTION_RUNS_MILLIS = -1L;    /**     * The default number of objects to examine per run in the     * idle object evictor.     * @see #getNumTestsPerEvictionRun     * @see #setNumTestsPerEvictionRun     * @see #getTimeBetweenEvictionRunsMillis     * @see #setTimeBetweenEvictionRunsMillis     */    public static final int DEFAULT_NUM_TESTS_PER_EVICTION_RUN = 3;    /**     * The default value for {@link #getMinEvictableIdleTimeMillis}.     * @see #getMinEvictableIdleTimeMillis     * @see #setMinEvictableIdleTimeMillis     */    public static final long DEFAULT_MIN_EVICTABLE_IDLE_TIME_MILLIS = 1000L * 60L * 30L;    /**     * The default value for {@link #getSoftMinEvictableIdleTimeMillis}.     * @see #getSoftMinEvictableIdleTimeMillis     * @see #setSoftMinEvictableIdleTimeMillis     */    public static final long DEFAULT_SOFT_MIN_EVICTABLE_IDLE_TIME_MILLIS = -1;    //--- package constants -------------------------------------------    /**     * Idle object evition Timer. Shared between all {@link GenericObjectPool}s and {@link GenericKeyedObjectPool} s.     */    static final Timer EVICTION_TIMER = new Timer(true);    //--- constructors -----------------------------------------------    /**     * Create a new <tt>GenericObjectPool</tt>.     */    public GenericObjectPool() {        this(null,DEFAULT_MAX_ACTIVE,DEFAULT_WHEN_EXHAUSTED_ACTION,DEFAULT_MAX_WAIT,DEFAULT_MAX_IDLE,DEFAULT_MIN_IDLE,DEFAULT_TEST_ON_BORROW,DEFAULT_TEST_ON_RETURN,DEFAULT_TIME_BETWEEN_EVICTION_RUNS_MILLIS,DEFAULT_NUM_TESTS_PER_EVICTION_RUN,DEFAULT_MIN_EVICTABLE_IDLE_TIME_MILLIS,DEFAULT_TEST_WHILE_IDLE);    }    /**     * Create a new <tt>GenericObjectPool</tt> using the specified values.     * @param factory the (possibly <tt>null</tt>)PoolableObjectFactory to use to create, validate and destroy objects     */    public GenericObjectPool(PoolableObjectFactory factory) {        this(factory,DEFAULT_MAX_ACTIVE,DEFAULT_WHEN_EXHAUSTED_ACTION,DEFAULT_MAX_WAIT,DEFAULT_MAX_IDLE,DEFAULT_MIN_IDLE,DEFAULT_TEST_ON_BORROW,DEFAULT_TEST_ON_RETURN,DEFAULT_TIME_BETWEEN_EVICTION_RUNS_MILLIS,DEFAULT_NUM_TESTS_PER_EVICTION_RUN,DEFAULT_MIN_EVICTABLE_IDLE_TIME_MILLIS,DEFAULT_TEST_WHILE_IDLE);    }    /**     * Create a new <tt>GenericObjectPool</tt> using the specified values.     * @param factory the (possibly <tt>null</tt>)PoolableObjectFactory to use to create, validate and destroy objects     * @param config a non-<tt>null</tt> {@link GenericObjectPool.Config} describing my configuration     */    public GenericObjectPool(PoolableObjectFactory factory, GenericObjectPool.Config config) {        this(factory,config.maxActive,config.whenExhaustedAction,config.maxWait,config.maxIdle,config.minIdle,config.testOnBorrow,config.testOnReturn,config.timeBetweenEvictionRunsMillis,config.numTestsPerEvictionRun,config.minEvictableIdleTimeMillis,config.testWhileIdle);    }    /**     * Create a new <tt>GenericObjectPool</tt> using the specified values.     * @param factory the (possibly <tt>null</tt>)PoolableObjectFactory to use to create, validate and destroy objects     * @param maxActive the maximum number of objects that can be borrowed from me at one time (see {@link #setMaxActive})     */    public GenericObjectPool(PoolableObjectFactory factory, int maxActive) {        this(factory,maxActive,DEFAULT_WHEN_EXHAUSTED_ACTION,DEFAULT_MAX_WAIT,DEFAULT_MAX_IDLE,DEFAULT_MIN_IDLE,DEFAULT_TEST_ON_BORROW,DEFAULT_TEST_ON_RETURN,DEFAULT_TIME_BETWEEN_EVICTION_RUNS_MILLIS,DEFAULT_NUM_TESTS_PER_EVICTION_RUN,DEFAULT_MIN_EVICTABLE_IDLE_TIME_MILLIS,DEFAULT_TEST_WHILE_IDLE);    }    /**     * Create a new <tt>GenericObjectPool</tt> using the specified values.     * @param factory the (possibly <tt>null</tt>)PoolableObjectFactory to use to create, validate and destroy objects     * @param maxActive the maximum number of objects that can be borrowed from me at one time (see {@link #setMaxActive})     * @param whenExhaustedAction the action to take when the pool is exhausted (see {@link #getWhenExhaustedAction})     * @param maxWait the maximum amount of time to wait for an idle object when the pool is exhausted an and <i>whenExhaustedAction</i> is {@link #WHEN_EXHAUSTED_BLOCK} (otherwise ignored) (see {@link #getMaxWait})     */    public GenericObjectPool(PoolableObjectFactory factory, int maxActive, byte whenExhaustedAction, long maxWait) {        this(factory,maxActive,whenExhaustedAction,maxWait,DEFAULT_MAX_IDLE,DEFAULT_MIN_IDLE,DEFAULT_TEST_ON_BORROW,DEFAULT_TEST_ON_RETURN,DEFAULT_TIME_BETWEEN_EVICTION_RUNS_MILLIS,DEFAULT_NUM_TESTS_PER_EVICTION_RUN,DEFAULT_MIN_EVICTABLE_IDLE_TIME_MILLIS,DEFAULT_TEST_WHILE_IDLE);    }    /**     * Create a new <tt>GenericObjectPool</tt> using the specified values.     * @param factory the (possibly <tt>null</tt>)PoolableObjectFactory to use to create, validate and destroy objects     * @param maxActive the maximum number of objects that can be borrowed from me at one time (see {@link #setMaxActive})     * @param whenExhaustedAction the action to take when the pool is exhausted (see {@link #getWhenExhaustedAction})     * @param maxWait the maximum amount of time to wait for an idle object when the pool is exhausted an and <i>whenExhaustedAction</i> is {@link #WHEN_EXHAUSTED_BLOCK} (otherwise ignored) (see {@link #getMaxWait})     * @param testOnBorrow whether or not to validate objects before they are returned by the {@link #borrowObject} method (see {@link #getTestOnBorrow})     * @param testOnReturn whether or not to validate objects after they are returned to the {@link #returnObject} method (see {@link #getTestOnReturn})     */    public GenericObjectPool(PoolableObjectFactory factory, int maxActive, byte whenExhaustedAction, long maxWait, boolean testOnBorrow, boolean testOnReturn) {        this(factory,maxActive,whenExhaustedAction,maxWait,DEFAULT_MAX_IDLE,DEFAULT_MIN_IDLE,testOnBorrow,testOnReturn,DEFAULT_TIME_BETWEEN_EVICTION_RUNS_MILLIS,DEFAULT_NUM_TESTS_PER_EVICTION_RUN,DEFAULT_MIN_EVICTABLE_IDLE_TIME_MILLIS,DEFAULT_TEST_WHILE_IDLE);    }