Return-Path: Delivered-To: apmail-commons-commits-archive@minotaur.apache.org Received: (qmail 92740 invoked from network); 25 May 2009 16:21:16 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (140.211.11.3) by minotaur.apache.org with SMTP; 25 May 2009 16:21:16 -0000 Received: (qmail 93008 invoked by uid 500); 25 May 2009 14:34:48 -0000 Delivered-To: apmail-commons-commits-archive@commons.apache.org Received: (qmail 92930 invoked by uid 500); 25 May 2009 14:34:48 -0000 Mailing-List: contact commits-help@commons.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@commons.apache.org Delivered-To: mailing list commits@commons.apache.org Received: (qmail 92921 invoked by uid 99); 25 May 2009 14:34:48 -0000 Received: from athena.apache.org (HELO athena.apache.org) (140.211.11.136) by apache.org (qpsmtpd/0.29) with ESMTP; Mon, 25 May 2009 14:34:48 +0000 X-ASF-Spam-Status: No, hits=-2000.0 required=10.0 tests=ALL_TRUSTED X-Spam-Check-By: apache.org Received: from [140.211.11.4] (HELO eris.apache.org) (140.211.11.4) by apache.org (qpsmtpd/0.29) with ESMTP; Mon, 25 May 2009 14:34:44 +0000 Received: by eris.apache.org (Postfix, from userid 65534) id 076212388897; Mon, 25 May 2009 14:34:24 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r778428 - /commons/proper/pool/trunk/src/java/org/apache/commons/pool/impl/GenericObjectPool.java Date: Mon, 25 May 2009 14:34:23 -0000 To: commits@commons.apache.org From: psteitz@apache.org X-Mailer: svnmailer-1.0.8 Message-Id: <20090525143424.076212388897@eris.apache.org> X-Virus-Checked: Checked by ClamAV on apache.org Author: psteitz Date: Mon May 25 14:34:21 2009 New Revision: 778428 URL: http://svn.apache.org/viewvc?rev=778428&view=rev Log: Javadoc improvements and source formatting (broke unreadably long lines). No functional code change. Modified: commons/proper/pool/trunk/src/java/org/apache/commons/pool/impl/GenericObjectPool.java Modified: commons/proper/pool/trunk/src/java/org/apache/commons/pool/impl/GenericObjectPool.java URL: http://svn.apache.org/viewvc/commons/proper/pool/trunk/src/java/org/apache/commons/pool/impl/GenericObjectPool.java?rev=778428&r1=778427&r2=778428&view=diff ============================================================================== --- commons/proper/pool/trunk/src/java/org/apache/commons/pool/impl/GenericObjectPool.java (original) +++ commons/proper/pool/trunk/src/java/org/apache/commons/pool/impl/GenericObjectPool.java Mon May 25 14:34:21 2009 @@ -336,18 +336,22 @@ //--- constructors ----------------------------------------------- /** - * Create a new GenericObjectPool. + * Create a new GenericObjectPool with default properties. */ 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); + 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 GenericObjectPool using the specified values. + * Create a new GenericObjectPool using the specified factory. * @param factory the (possibly null)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); + 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); } /** @@ -356,7 +360,10 @@ * @param config a non-null {@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,config.softMinEvictableIdleTimeMillis, config.lifo); + this(factory, config.maxActive, config.whenExhaustedAction, config.maxWait, config.maxIdle, config.minIdle, + config.testOnBorrow, config.testOnReturn, config.timeBetweenEvictionRunsMillis, + config.numTestsPerEvictionRun, config.minEvictableIdleTimeMillis, config.testWhileIdle, + config.softMinEvictableIdleTimeMillis, config.lifo); } /** @@ -365,7 +372,9 @@ * @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); + 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); } /** @@ -373,128 +382,194 @@ * @param factory the (possibly null)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 whenExhaustedAction is {@link #WHEN_EXHAUSTED_BLOCK} (otherwise ignored) (see {@link #getMaxWait}) + * @param maxWait the maximum amount of time to wait for an idle object when the pool is exhausted an and + * whenExhaustedAction 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); + 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 GenericObjectPool using the specified values. * @param factory the (possibly null)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 maxActive the maximum number of objects that can be borrowed 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 whenExhaustedAction 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); + * @param maxWait the maximum amount of time to wait for an idle object when the pool is exhausted an and + * whenExhaustedAction 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); } /** * Create a new GenericObjectPool using the specified values. * @param factory the (possibly null)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 maxActive the maximum number of objects that can be borrowed 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 whenExhaustedAction is {@link #WHEN_EXHAUSTED_BLOCK} (otherwise ignored) (see {@link #getMaxWait}) + * @param maxWait the maximum amount of time to wait for an idle object when the pool is exhausted and + * whenExhaustedAction is {@link #WHEN_EXHAUSTED_BLOCK} (otherwise ignored) (see {@link #getMaxWait}) * @param maxIdle the maximum number of idle objects in my pool (see {@link #getMaxIdle}) */ public GenericObjectPool(PoolableObjectFactory factory, int maxActive, byte whenExhaustedAction, long maxWait, int maxIdle) { - this(factory,maxActive,whenExhaustedAction,maxWait,maxIdle,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); + this(factory, maxActive, whenExhaustedAction, maxWait, maxIdle, 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 GenericObjectPool using the specified values. * @param factory the (possibly null)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 maxActive the maximum number of objects that can be borrowed 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 whenExhaustedAction is {@link #WHEN_EXHAUSTED_BLOCK} (otherwise ignored) (see {@link #getMaxWait}) + * @param maxWait the maximum amount of time to wait for an idle object when the pool is exhausted and + * whenExhaustedAction is {@link #WHEN_EXHAUSTED_BLOCK} (otherwise ignored) (see {@link #getMaxWait}) * @param maxIdle the maximum number of idle objects in my pool (see {@link #getMaxIdle}) - * @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, int maxIdle, boolean testOnBorrow, boolean testOnReturn) { - this(factory,maxActive,whenExhaustedAction,maxWait,maxIdle,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); + * @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, + int maxIdle, boolean testOnBorrow, boolean testOnReturn) { + this(factory, maxActive, whenExhaustedAction, maxWait, maxIdle, 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); } /** * Create a new GenericObjectPool using the specified values. * @param factory the (possibly null)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 maxActive the maximum number of objects that can be borrowed at one time (see {@link #setMaxActive}) * @param whenExhaustedAction the action to take when the pool is exhausted (see {@link #setWhenExhaustedAction}) - * @param maxWait the maximum amount of time to wait for an idle object when the pool is exhausted an and whenExhaustedAction is {@link #WHEN_EXHAUSTED_BLOCK} (otherwise ignored) (see {@link #setMaxWait}) + * @param maxWait the maximum amount of time to wait for an idle object when the pool is exhausted and + * whenExhaustedAction is {@link #WHEN_EXHAUSTED_BLOCK} (otherwise ignored) (see {@link #setMaxWait}) * @param maxIdle the maximum number of idle objects in my pool (see {@link #setMaxIdle}) - * @param testOnBorrow whether or not to validate objects before they are returned by the {@link #borrowObject} method (see {@link #setTestOnBorrow}) - * @param testOnReturn whether or not to validate objects after they are returned to the {@link #returnObject} method (see {@link #setTestOnReturn}) - * @param timeBetweenEvictionRunsMillis the amount of time (in milliseconds) to sleep between examining idle objects for eviction (see {@link #setTimeBetweenEvictionRunsMillis}) - * @param numTestsPerEvictionRun the number of idle objects to examine per run within the idle object eviction thread (if any) (see {@link #setNumTestsPerEvictionRun}) - * @param minEvictableIdleTimeMillis the minimum number of milliseconds an object can sit idle in the pool before it is eligible for eviction (see {@link #setMinEvictableIdleTimeMillis}) - * @param testWhileIdle whether or not to validate objects in the idle object eviction thread, if any (see {@link #setTestWhileIdle}) - */ - public GenericObjectPool(PoolableObjectFactory factory, int maxActive, byte whenExhaustedAction, long maxWait, int maxIdle, boolean testOnBorrow, boolean testOnReturn, long timeBetweenEvictionRunsMillis, int numTestsPerEvictionRun, long minEvictableIdleTimeMillis, boolean testWhileIdle) { - this(factory, maxActive, whenExhaustedAction, maxWait, maxIdle, DEFAULT_MIN_IDLE, testOnBorrow, testOnReturn, timeBetweenEvictionRunsMillis, numTestsPerEvictionRun, minEvictableIdleTimeMillis, testWhileIdle); + * @param testOnBorrow whether or not to validate objects before they are returned by the {@link #borrowObject} + * method (see {@link #setTestOnBorrow}) + * @param testOnReturn whether or not to validate objects after they are returned to the {@link #returnObject} method + * (see {@link #setTestOnReturn}) + * @param timeBetweenEvictionRunsMillis the amount of time (in milliseconds) to sleep between examining idle objects + * for eviction (see {@link #setTimeBetweenEvictionRunsMillis}) + * @param numTestsPerEvictionRun the number of idle objects to examine per run within the idle object eviction thread + * (if any) (see {@link #setNumTestsPerEvictionRun}) + * @param minEvictableIdleTimeMillis the minimum number of milliseconds an object can sit idle in the pool before it + * is eligible for eviction (see {@link #setMinEvictableIdleTimeMillis}) + * @param testWhileIdle whether or not to validate objects in the idle object eviction thread, if any + * (see {@link #setTestWhileIdle}) + */ + public GenericObjectPool(PoolableObjectFactory factory, int maxActive, byte whenExhaustedAction, long maxWait, + int maxIdle, boolean testOnBorrow, boolean testOnReturn, long timeBetweenEvictionRunsMillis, + int numTestsPerEvictionRun, long minEvictableIdleTimeMillis, boolean testWhileIdle) { + this(factory, maxActive, whenExhaustedAction, maxWait, maxIdle, DEFAULT_MIN_IDLE, testOnBorrow, testOnReturn, + timeBetweenEvictionRunsMillis, numTestsPerEvictionRun, minEvictableIdleTimeMillis, testWhileIdle); } /** * Create a new GenericObjectPool using the specified values. * @param factory the (possibly null)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 maxActive the maximum number of objects that can be borrowed at one time (see {@link #setMaxActive}) * @param whenExhaustedAction the action to take when the pool is exhausted (see {@link #setWhenExhaustedAction}) - * @param maxWait the maximum amount of time to wait for an idle object when the pool is exhausted an and whenExhaustedAction is {@link #WHEN_EXHAUSTED_BLOCK} (otherwise ignored) (see {@link #setMaxWait}) + * @param maxWait the maximum amount of time to wait for an idle object when the pool is exhausted and + * whenExhaustedAction is {@link #WHEN_EXHAUSTED_BLOCK} (otherwise ignored) (see {@link #setMaxWait}) * @param maxIdle the maximum number of idle objects in my pool (see {@link #setMaxIdle}) * @param minIdle the minimum number of idle objects in my pool (see {@link #setMinIdle}) - * @param testOnBorrow whether or not to validate objects before they are returned by the {@link #borrowObject} method (see {@link #setTestOnBorrow}) - * @param testOnReturn whether or not to validate objects after they are returned to the {@link #returnObject} method (see {@link #setTestOnReturn}) - * @param timeBetweenEvictionRunsMillis the amount of time (in milliseconds) to sleep between examining idle objects for eviction (see {@link #setTimeBetweenEvictionRunsMillis}) - * @param numTestsPerEvictionRun the number of idle objects to examine per run within the idle object eviction thread (if any) (see {@link #setNumTestsPerEvictionRun}) - * @param minEvictableIdleTimeMillis the minimum number of milliseconds an object can sit idle in the pool before it is eligible for eviction (see {@link #setMinEvictableIdleTimeMillis}) - * @param testWhileIdle whether or not to validate objects in the idle object eviction thread, if any (see {@link #setTestWhileIdle}) - */ - public GenericObjectPool(PoolableObjectFactory factory, int maxActive, byte whenExhaustedAction, long maxWait, int maxIdle, int minIdle, boolean testOnBorrow, boolean testOnReturn, long timeBetweenEvictionRunsMillis, int numTestsPerEvictionRun, long minEvictableIdleTimeMillis, boolean testWhileIdle) { - this(factory, maxActive, whenExhaustedAction, maxWait, maxIdle, minIdle, testOnBorrow, testOnReturn, timeBetweenEvictionRunsMillis, numTestsPerEvictionRun, minEvictableIdleTimeMillis, testWhileIdle, DEFAULT_SOFT_MIN_EVICTABLE_IDLE_TIME_MILLIS); + * @param testOnBorrow whether or not to validate objects before they are returned by the {@link #borrowObject} method + * (see {@link #setTestOnBorrow}) + * @param testOnReturn whether or not to validate objects after they are returned to the {@link #returnObject} method + * (see {@link #setTestOnReturn}) + * @param timeBetweenEvictionRunsMillis the amount of time (in milliseconds) to sleep between examining idle objects + * for eviction (see {@link #setTimeBetweenEvictionRunsMillis}) + * @param numTestsPerEvictionRun the number of idle objects to examine per run within the idle object eviction thread + * (if any) (see {@link #setNumTestsPerEvictionRun}) + * @param minEvictableIdleTimeMillis the minimum number of milliseconds an object can sit idle in the pool before + * it is eligible for eviction (see {@link #setMinEvictableIdleTimeMillis}) + * @param testWhileIdle whether or not to validate objects in the idle object eviction thread, if any + * (see {@link #setTestWhileIdle}) + */ + public GenericObjectPool(PoolableObjectFactory factory, int maxActive, byte whenExhaustedAction, long maxWait, + int maxIdle, int minIdle, boolean testOnBorrow, boolean testOnReturn, long timeBetweenEvictionRunsMillis, + int numTestsPerEvictionRun, long minEvictableIdleTimeMillis, boolean testWhileIdle) { + this(factory, maxActive, whenExhaustedAction, maxWait, maxIdle, minIdle, testOnBorrow, testOnReturn, + timeBetweenEvictionRunsMillis, numTestsPerEvictionRun, minEvictableIdleTimeMillis, testWhileIdle, + DEFAULT_SOFT_MIN_EVICTABLE_IDLE_TIME_MILLIS); } /** * Create a new GenericObjectPool using the specified values. * @param factory the (possibly null)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 maxActive the maximum number of objects that can be borrowed at one time (see {@link #setMaxActive}) * @param whenExhaustedAction the action to take when the pool is exhausted (see {@link #setWhenExhaustedAction}) - * @param maxWait the maximum amount of time to wait for an idle object when the pool is exhausted an and whenExhaustedAction is {@link #WHEN_EXHAUSTED_BLOCK} (otherwise ignored) (see {@link #setMaxWait}) + * @param maxWait the maximum amount of time to wait for an idle object when the pool is exhausted and + * whenExhaustedAction is {@link #WHEN_EXHAUSTED_BLOCK} (otherwise ignored) (see {@link #setMaxWait}) * @param maxIdle the maximum number of idle objects in my pool (see {@link #setMaxIdle}) * @param minIdle the minimum number of idle objects in my pool (see {@link #setMinIdle}) - * @param testOnBorrow whether or not to validate objects before they are returned by the {@link #borrowObject} method (see {@link #setTestOnBorrow}) - * @param testOnReturn whether or not to validate objects after they are returned to the {@link #returnObject} method (see {@link #setTestOnReturn}) - * @param timeBetweenEvictionRunsMillis the amount of time (in milliseconds) to sleep between examining idle objects for eviction (see {@link #setTimeBetweenEvictionRunsMillis}) - * @param numTestsPerEvictionRun the number of idle objects to examine per run within the idle object eviction thread (if any) (see {@link #setNumTestsPerEvictionRun}) - * @param minEvictableIdleTimeMillis the minimum number of milliseconds an object can sit idle in the pool before it is eligible for eviction (see {@link #setMinEvictableIdleTimeMillis}) - * @param testWhileIdle whether or not to validate objects in the idle object eviction thread, if any (see {@link #setTestWhileIdle}) - * @param 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 {@link #setSoftMinEvictableIdleTimeMillis}) + * @param testOnBorrow whether or not to validate objects before they are returned by the {@link #borrowObject} + * method (see {@link #setTestOnBorrow}) + * @param testOnReturn whether or not to validate objects after they are returned to the {@link #returnObject} + * method (see {@link #setTestOnReturn}) + * @param timeBetweenEvictionRunsMillis the amount of time (in milliseconds) to sleep between examining idle objects + * for eviction (see {@link #setTimeBetweenEvictionRunsMillis}) + * @param numTestsPerEvictionRun the number of idle objects to examine per run within the idle object eviction thread + * (if any) (see {@link #setNumTestsPerEvictionRun}) + * @param minEvictableIdleTimeMillis the minimum number of milliseconds an object can sit idle in the pool before + * it is eligible for eviction (see {@link #setMinEvictableIdleTimeMillis}) + * @param testWhileIdle whether or not to validate objects in the idle object eviction thread, if any + * (see {@link #setTestWhileIdle}) + * @param 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 {@link #setSoftMinEvictableIdleTimeMillis}) * @since Pool 1.3 */ - public GenericObjectPool(PoolableObjectFactory 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) { - this(factory, maxActive, whenExhaustedAction, maxWait, maxIdle, minIdle, testOnBorrow, testOnReturn, timeBetweenEvictionRunsMillis, numTestsPerEvictionRun, minEvictableIdleTimeMillis, testWhileIdle, softMinEvictableIdleTimeMillis, DEFAULT_LIFO); + public GenericObjectPool(PoolableObjectFactory 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) { + this(factory, maxActive, whenExhaustedAction, maxWait, maxIdle, minIdle, testOnBorrow, testOnReturn, + timeBetweenEvictionRunsMillis, numTestsPerEvictionRun, minEvictableIdleTimeMillis, testWhileIdle, + softMinEvictableIdleTimeMillis, DEFAULT_LIFO); } /** * Create a new GenericObjectPool using the specified values. * @param factory the (possibly null)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 maxActive the maximum number of objects that can be borrowed at one time (see {@link #setMaxActive}) * @param whenExhaustedAction the action to take when the pool is exhausted (see {@link #setWhenExhaustedAction}) - * @param maxWait the maximum amount of time to wait for an idle object when the pool is exhausted an and whenExhaustedAction is {@link #WHEN_EXHAUSTED_BLOCK} (otherwise ignored) (see {@link #setMaxWait}) + * @param maxWait the maximum amount of time to wait for an idle object when the pool is exhausted and + * whenExhaustedAction is {@link #WHEN_EXHAUSTED_BLOCK} (otherwise ignored) (see {@link #setMaxWait}) * @param maxIdle the maximum number of idle objects in my pool (see {@link #setMaxIdle}) * @param minIdle the minimum number of idle objects in my pool (see {@link #setMinIdle}) - * @param testOnBorrow whether or not to validate objects before they are returned by the {@link #borrowObject} method (see {@link #setTestOnBorrow}) - * @param testOnReturn whether or not to validate objects after they are returned to the {@link #returnObject} method (see {@link #setTestOnReturn}) - * @param timeBetweenEvictionRunsMillis the amount of time (in milliseconds) to sleep between examining idle objects for eviction (see {@link #setTimeBetweenEvictionRunsMillis}) - * @param numTestsPerEvictionRun the number of idle objects to examine per run within the idle object eviction thread (if any) (see {@link #setNumTestsPerEvictionRun}) - * @param minEvictableIdleTimeMillis the minimum number of milliseconds an object can sit idle in the pool before it is eligible for eviction (see {@link #setMinEvictableIdleTimeMillis}) - * @param testWhileIdle whether or not to validate objects in the idle object eviction thread, if any (see {@link #setTestWhileIdle}) - * @param 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 {@link #setSoftMinEvictableIdleTimeMillis}) - * @param lifo whether or not objects are returned in last-in-first-out order from the idle object pool (see {@link #setLifo}) + * @param testOnBorrow whether or not to validate objects before they are returned by the {@link #borrowObject} + * method (see {@link #setTestOnBorrow}) + * @param testOnReturn whether or not to validate objects after they are returned to the {@link #returnObject} + * method (see {@link #setTestOnReturn}) + * @param timeBetweenEvictionRunsMillis the amount of time (in milliseconds) to sleep between examining idle + * objects for eviction (see {@link #setTimeBetweenEvictionRunsMillis}) + * @param numTestsPerEvictionRun the number of idle objects to examine per run within the idle object eviction + * thread (if any) (see {@link #setNumTestsPerEvictionRun}) + * @param minEvictableIdleTimeMillis the minimum number of milliseconds an object can sit idle in the pool before + * it is eligible for eviction (see {@link #setMinEvictableIdleTimeMillis}) + * @param testWhileIdle whether or not to validate objects in the idle object eviction thread, if any + * (see {@link #setTestWhileIdle}) + * @param 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 {@link #setSoftMinEvictableIdleTimeMillis}) + * @param lifo whether or not objects are returned in last-in-first-out order from the idle object pool + * (see {@link #setLifo}) * @since Pool 1.4 */ - public GenericObjectPool(PoolableObjectFactory 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) { + public GenericObjectPool(PoolableObjectFactory 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) { _factory = factory; _maxActive = maxActive; _lifo = lifo; @@ -785,7 +860,7 @@ * idle object evictor thread (if any). *

* When a negative value is supplied, ceil({@link #getNumIdle})/abs({@link #getNumTestsPerEvictionRun}) - * tests will be run. I.e., when the value is -n, roughly one nth of the + * tests will be run. That is, when the value is -n, roughly one nth of the * idle objects will be tested per run. * * @param numTestsPerEvictionRun max number of objects to examine during each evictor run. @@ -815,7 +890,8 @@ * (if any). * When non-positive, no objects will be evicted from the pool * due to idle time alone. - * @param minEvictableIdleTimeMillis minimum amount of time an object may sit idle in the pool before it is eligible for eviction. + * @param minEvictableIdleTimeMillis minimum amount of time an object may sit idle in the pool before + * it is eligible for eviction. * @see #getMinEvictableIdleTimeMillis * @see #setTimeBetweenEvictionRunsMillis */ @@ -845,7 +921,8 @@ * When non-positive, no objects will be evicted from the pool * due to idle time alone. * - * @param softMinEvictableIdleTimeMillis minimum amount of time an object may sit idle in the pool before it is eligible for eviction. + * @param softMinEvictableIdleTimeMillis minimum amount of time an object may sit idle in the pool before + * it is eligible for eviction. * @since Pool 1.3 * @see #getSoftMinEvictableIdleTimeMillis */ @@ -934,6 +1011,33 @@ //-- ObjectPool methods ------------------------------------------ + /** + *

Borrows an object from the pool.

+ * + *

If there is an idle instance available in the pool, then either the most-recently returned + * (if {@link #getLifo() lifo} == true) or "oldest" (lifo == false) instance sitting idle in the pool + * will be activated and returned. If activation fails, or {@link #getTestOnBorrow() 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 {@link #getMaxActive() maxActive} + * and (if applicable) {@link #getWhenExhaustedAction() whenExhaustedAction} and {@link #getMaxWait() 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 ({@link #WHEN_EXHAUSTED_BLOCK}), throw a NoSuchElementException + * ({@link #WHEN_EXHAUSTED_FAIL}), or grow ({@link #WHEN_EXHAUSTED_GROW} - ignoring maxActive). + * The length of time that this method will block when whenExhaustedAction == WHEN_EXHAUSTED_BLOCK + * is determined by the {@link #getMaxWait() 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.

+ * + * @return object instance + * @throws NoSuchElementException if an instance cannot be returned + */ public Object borrowObject() throws Exception { long starttime = System.currentTimeMillis(); Latch latch = new Latch(); @@ -1005,7 +1109,8 @@ continue; // keep looping } default: - throw new IllegalArgumentException("WhenExhaustedAction property " + whenExhaustedAction + " not recognized."); + throw new IllegalArgumentException("WhenExhaustedAction property " + whenExhaustedAction + + " not recognized."); } } } @@ -1100,6 +1205,13 @@ } } + /** + *

Invalidates the given object instance. Decrements the active count + * and destroys the instance.

+ * + * @param obj instance to invalidate + * @throws Exception if an exception occurs destroying the object + */ public void invalidateObject(Object obj) throws Exception { try { if (_factory != null) { @@ -1127,9 +1239,11 @@ destroy(toDestroy); } - /* + /** * Private method to destroy all the objects in a collection. Assumes * objects in the collection are instances of ObjectTimestampPair + * + * @param c Collection of objects to destroy */ private void destroy(Collection c) { for (Iterator it = c.iterator(); it.hasNext();) { @@ -1165,7 +1279,14 @@ } /** - * {@inheritDoc} + *

Returns an object instance to the pool.

+ * + *

If {@link #getMaxIdle() maxIdle} is set to a positive value and the number of idle instances + * has reached this value, the returning instance is destroyed.

+ * + *

If {@link #getTestOnReturn() 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 @@ -1173,6 +1294,8 @@ * 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.

+ * + * @param obj instance to return to the pool */ public void returnObject(Object obj) throws Exception { try { @@ -1186,7 +1309,7 @@ } // TODO: Correctness here depends on control in addObjectToPool. // These two methods should be refactored, removing the - // "behavior flag",decrementNumActive, from addObjectToPool. + // "behavior flag", decrementNumActive, from addObjectToPool. synchronized(this) { _numActive--; allocate(); @@ -1195,6 +1318,19 @@ } } + /** + *

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 {@link #allocate()} on successful completion

+ * + * @param obj instance to add to the pool + * @param decrementNumActive whether or not to decrement the active count + * @throws Exception + */ private void addObjectToPool(Object obj, boolean decrementNumActive) throws Exception { boolean success = true; if(_testOnReturn && !(_factory.validateObject(obj))) { @@ -1247,6 +1383,15 @@ } + /** + * Closes the pool. Once the pool is closed, {@link #borrowObject()} + * will fail with IllegalStateException, but {@link #returnObject(Object)} and + * {@link #invalidateObject(Object)} will continue to work. This method does not + * {@link #clear()} the pool. The method is idempotent - that is, it is OK to call it on a closed + * pool. + * + * @throws Exception + */ public void close() throws Exception { super.close(); synchronized (this) { @@ -1323,12 +1468,12 @@ boolean removeObject = false; final long idleTimeMilis = System.currentTimeMillis() - pair.tstamp; - if ((getMinEvictableIdleTimeMillis() > 0) - && (idleTimeMilis > getMinEvictableIdleTimeMillis())) { + if ((getMinEvictableIdleTimeMillis() > 0) && + (idleTimeMilis > getMinEvictableIdleTimeMillis())) { removeObject = true; - } else if ((getSoftMinEvictableIdleTimeMillis() > 0) - && (idleTimeMilis > getSoftMinEvictableIdleTimeMillis()) - && ((getNumIdle() + 1)> getMinIdle())) { // +1 accounts for object we are processing + } else if ((getSoftMinEvictableIdleTimeMillis() > 0) && + (idleTimeMilis > getSoftMinEvictableIdleTimeMillis()) && + ((getNumIdle() + 1)> getMinIdle())) { // +1 accounts for object we are processing removeObject = true; } if(getTestWhileIdle() && !removeObject) { @@ -1397,6 +1542,16 @@ } } + /** + * 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. + * + * @param incrementInternal - Should the count of objects currently under + * some form of internal processing be + * incremented? + * @return The number of objects to be created + */ private synchronized int calculateDeficit(boolean incrementInternal) { int objectDeficit = getMinIdle() - getNumIdle(); if (_maxActive > 0) { @@ -1503,7 +1658,8 @@ /** * A simple "struct" encapsulating the * configuration information for a {@link GenericObjectPool}. - * @see GenericObjectPool#GenericObjectPool(org.apache.commons.pool.PoolableObjectFactory,org.apache.commons.pool.impl.GenericObjectPool.Config) + * @see GenericObjectPool#GenericObjectPool(org.apache.commons.pool.PoolableObjectFactory, + * org.apache.commons.pool.impl.GenericObjectPool.Config) * @see GenericObjectPool#setConfig */ public static class Config { @@ -1568,19 +1724,41 @@ * threads request objects. */ private static final class Latch { + + /** object timestamp pair allocated to this latch */ private ObjectTimestampPair _pair; + + /** Wheter or not this latch may create an object instance */ private boolean _mayCreate = false; + /** + * Returns ObjectTimestampPair allocated to this latch + * @return ObjectTimestampPair allocated to this latch + */ private synchronized ObjectTimestampPair getPair() { return _pair; } + + /** + * Sets ObjectTimestampPair on this latch + * @param pair ObjectTimestampPair allocated to this latch + */ private synchronized void setPair(ObjectTimestampPair pair) { _pair = pair; } + /** + * Whether or not this latch may create an object instance + * @return true if this latch has an instance creation permit + */ private synchronized boolean mayCreate() { return _mayCreate; } + + /** + * Sets the mayCreate property + * @param mayCreate new value for mayCreate + */ private synchronized void setMayCreate(boolean mayCreate) { _mayCreate = mayCreate; }