You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by ps...@apache.org on 2009/05/24 21:28:07 UTC
svn commit: r778217 -
/commons/proper/pool/trunk/src/java/org/apache/commons/pool/impl/GenericKeyedObjectPool.java
Author: psteitz
Date: Sun May 24 19:28:07 2009
New Revision: 778217
URL: http://svn.apache.org/viewvc?rev=778217&view=rev
Log:
Javadoc improvements and code formatting (mostly eiliminating unreadably long lines). No functional code change.
Modified:
commons/proper/pool/trunk/src/java/org/apache/commons/pool/impl/GenericKeyedObjectPool.java
Modified: commons/proper/pool/trunk/src/java/org/apache/commons/pool/impl/GenericKeyedObjectPool.java
URL: http://svn.apache.org/viewvc/commons/proper/pool/trunk/src/java/org/apache/commons/pool/impl/GenericKeyedObjectPool.java?rev=778217&r1=778216&r2=778217&view=diff
==============================================================================
--- commons/proper/pool/trunk/src/java/org/apache/commons/pool/impl/GenericKeyedObjectPool.java (original)
+++ commons/proper/pool/trunk/src/java/org/apache/commons/pool/impl/GenericKeyedObjectPool.java Sun May 24 19:28:07 2009
@@ -357,166 +357,257 @@
* @see #setFactory(KeyedPoolableObjectFactory)
*/
public GenericKeyedObjectPool() {
- this(null,DEFAULT_MAX_ACTIVE,DEFAULT_WHEN_EXHAUSTED_ACTION,DEFAULT_MAX_WAIT,DEFAULT_MAX_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_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 <code>GenericKeyedObjectPool</code> using the specified values.
- * @param factory the <code>KeyedPoolableObjectFactory</code> to use to create, validate, and destroy objects if not <code>null</code>
+ * @param factory the <code>KeyedPoolableObjectFactory</code> to use to create, validate, and destroy
+ * objects if not <code>null</code>
*/
public GenericKeyedObjectPool(KeyedPoolableObjectFactory factory) {
- this(factory,DEFAULT_MAX_ACTIVE,DEFAULT_WHEN_EXHAUSTED_ACTION,DEFAULT_MAX_WAIT,DEFAULT_MAX_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_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 <code>GenericKeyedObjectPool</code> using the specified values.
- * @param factory the <code>KeyedPoolableObjectFactory</code> to use to create, validate, and destroy objects if not <code>null</code>
+ * @param factory the <code>KeyedPoolableObjectFactory</code> to use to create, validate, and destroy objects
+ * if not <code>null</code>
* @param config a non-<code>null</code> {@link GenericKeyedObjectPool.Config} describing the configuration
*/
public GenericKeyedObjectPool(KeyedPoolableObjectFactory factory, GenericKeyedObjectPool.Config config) {
- this(factory,config.maxActive,config.whenExhaustedAction,config.maxWait,config.maxIdle,config.maxTotal, config.minIdle,config.testOnBorrow,config.testOnReturn,config.timeBetweenEvictionRunsMillis,config.numTestsPerEvictionRun,config.minEvictableIdleTimeMillis,config.testWhileIdle,config.lifo);
+ this(factory, config.maxActive, config.whenExhaustedAction, config.maxWait, config.maxIdle, config.maxTotal,
+ config.minIdle, config.testOnBorrow, config.testOnReturn, config.timeBetweenEvictionRunsMillis,
+ config.numTestsPerEvictionRun, config.minEvictableIdleTimeMillis, config.testWhileIdle, config.lifo);
}
/**
* Create a new <code>GenericKeyedObjectPool</code> using the specified values.
- * @param factory the <code>KeyedPoolableObjectFactory</code> to use to create, validate, and destroy objects if not <code>null</code>
+ * @param factory the <code>KeyedPoolableObjectFactory</code> to use to create, validate, and destroy objects
+ * if not <code>null</code>
* @param maxActive the maximum number of objects that can be borrowed from me at one time (see {@link #setMaxActive})
*/
public GenericKeyedObjectPool(KeyedPoolableObjectFactory factory, int maxActive) {
- this(factory,maxActive,DEFAULT_WHEN_EXHAUSTED_ACTION,DEFAULT_MAX_WAIT,DEFAULT_MAX_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_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 <code>GenericKeyedObjectPool</code> using the specified values.
- * @param factory the <code>KeyedPoolableObjectFactory</code> to use to create, validate, and destroy objects if not <code>null</code>
+ * @param factory the <code>KeyedPoolableObjectFactory</code> to use to create, validate, and destroy objects
+ * if not <code>null</code>
* @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 #setWhenExhaustedAction})
- * @param maxWait the maximum amount of time to wait for an idle object when the pool is exhausted and <code>whenExhaustedAction</code> 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
+ * <code>whenExhaustedAction</code> is {@link #WHEN_EXHAUSTED_BLOCK} (otherwise ignored) (see {@link #setMaxWait})
*/
- public GenericKeyedObjectPool(KeyedPoolableObjectFactory factory, int maxActive, byte whenExhaustedAction, long maxWait) {
- this(factory,maxActive,whenExhaustedAction,maxWait,DEFAULT_MAX_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);
+ public GenericKeyedObjectPool(KeyedPoolableObjectFactory factory, int maxActive, byte whenExhaustedAction,
+ long maxWait) {
+ this(factory, maxActive, whenExhaustedAction, maxWait, DEFAULT_MAX_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 <code>GenericKeyedObjectPool</code> using the specified values.
- * @param factory the <code>KeyedPoolableObjectFactory</code> to use to create, validate, and destroy objects if not <code>null</code>
+ * @param factory the <code>KeyedPoolableObjectFactory</code> to use to create, validate, and destroy objects
+ * if not <code>null</code>
* @param maxActive the maximum number of objects that can be borrowed from me at one time (see {@link #setMaxActive})
- * @param maxWait the maximum amount of time to wait for an idle object when the pool is exhausted and <code>whenExhaustedAction</code> 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
+ * <code>whenExhaustedAction</code> is {@link #WHEN_EXHAUSTED_BLOCK} (otherwise ignored) (see {@link #setMaxWait})
* @param whenExhaustedAction the action to take when the pool is exhausted (see {@link #setWhenExhaustedAction})
- * @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})
- */
- public GenericKeyedObjectPool(KeyedPoolableObjectFactory factory, int maxActive, byte whenExhaustedAction, long maxWait, boolean testOnBorrow, boolean testOnReturn) {
- this(factory,maxActive,whenExhaustedAction,maxWait,DEFAULT_MAX_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 #setTestOnBorrow})
+ * @param testOnReturn whether or not to validate objects after they are returned to the {@link #returnObject}
+ * method (see {@link #setTestOnReturn})
+ */
+ public GenericKeyedObjectPool(KeyedPoolableObjectFactory factory, int maxActive, byte whenExhaustedAction,
+ long maxWait, boolean testOnBorrow, boolean testOnReturn) {
+ this(factory, maxActive, whenExhaustedAction, maxWait, DEFAULT_MAX_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 <code>GenericKeyedObjectPool</code> using the specified values.
- * @param factory the <code>KeyedPoolableObjectFactory</code> to use to create, validate, and destroy objects if not <code>null</code>
- * @param maxActive the maximum number of objects that can be borrowed from me at one time (see {@link #setMaxActive})
+ * @param factory the <code>KeyedPoolableObjectFactory</code> to use to create, validate, and destroy objects
+ * if not <code>null</code>
+ * @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 #setWhenExhaustedAction})
- * @param maxWait the maximum amount of time to wait for an idle object when the pool is exhausted and <code>whenExhaustedAction</code> 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
+ * <code>whenExhaustedAction</code> is {@link #WHEN_EXHAUSTED_BLOCK} (otherwise ignored) (see {@link #setMaxWait})
* @param maxIdle the maximum number of idle objects in my pool (see {@link #setMaxIdle})
*/
- public GenericKeyedObjectPool(KeyedPoolableObjectFactory factory, int maxActive, byte whenExhaustedAction, long maxWait, int maxIdle) {
- this(factory,maxActive,whenExhaustedAction,maxWait,maxIdle,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);
+ public GenericKeyedObjectPool(KeyedPoolableObjectFactory factory, int maxActive, byte whenExhaustedAction,
+ long maxWait, int maxIdle) {
+ this(factory, maxActive, whenExhaustedAction, maxWait, maxIdle, 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 <code>GenericKeyedObjectPool</code> using the specified values.
- * @param factory the <code>KeyedPoolableObjectFactory</code> to use to create, validate, and destroy objects if not <code>null</code>
- * @param maxActive the maximum number of objects that can be borrowed from me at one time (see {@link #setMaxActive})
+ * @param factory the <code>KeyedPoolableObjectFactory</code> to use to create, validate, and destroy objects
+ * if not <code>null</code>
+ * @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 #setWhenExhaustedAction})
- * @param maxWait the maximum amount of time to wait for an idle object when the pool is exhausted and <code>whenExhaustedAction</code> 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
+ * <code>whenExhaustedAction</code> is {@link #WHEN_EXHAUSTED_BLOCK} (otherwise ignored) (see {@link #getMaxWait})
* @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})
- */
- public GenericKeyedObjectPool(KeyedPoolableObjectFactory factory, int maxActive, byte whenExhaustedAction, long maxWait, int maxIdle, boolean testOnBorrow, boolean testOnReturn) {
- this(factory,maxActive,whenExhaustedAction,maxWait,maxIdle,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 #setTestOnBorrow})
+ * @param testOnReturn whether or not to validate objects after they are returned to the {@link #returnObject}
+ * method (see {@link #setTestOnReturn})
+ */
+ public GenericKeyedObjectPool(KeyedPoolableObjectFactory factory, int maxActive, byte whenExhaustedAction,
+ long maxWait, int maxIdle, boolean testOnBorrow, boolean testOnReturn) {
+ this(factory, maxActive, whenExhaustedAction, maxWait, maxIdle, 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 <code>GenericKeyedObjectPool</code> using the specified values.
- * @param factory the <code>KeyedPoolableObjectFactory</code> to use to create, validate, and destroy objects if not <code>null</code>
- * @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 #setWhenExhaustedAction})
- * @param maxWait the maximum amount of time to wait for an idle object when the pool is exhausted and <code>whenExhaustedAction</code> is {@link #WHEN_EXHAUSTED_BLOCK} (otherwise ignored) (see {@link #setMaxWait})
+ * @param factory the <code>KeyedPoolableObjectFactory</code> to use to create, validate, and destroy objects
+ * if not <code>null</code>
+ * @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 #setWhenExhaustedAction})
+ * @param maxWait the maximum amount of time to wait for an idle object when the pool is exhausted and
+ * <code>whenExhaustedAction</code> 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 GenericKeyedObjectPool(KeyedPoolableObjectFactory 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, GenericKeyedObjectPool.DEFAULT_MAX_TOTAL, 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 GenericKeyedObjectPool(KeyedPoolableObjectFactory 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, GenericKeyedObjectPool.DEFAULT_MAX_TOTAL,
+ testOnBorrow, testOnReturn, timeBetweenEvictionRunsMillis, numTestsPerEvictionRun,
+ minEvictableIdleTimeMillis, testWhileIdle);
}
/**
* Create a new <code>GenericKeyedObjectPool</code> using the specified values.
- * @param factory the <code>KeyedPoolableObjectFactory</code> to use to create, validate, and destroy objects if not <code>null</code>
- * @param maxActive the maximum number of objects that can be borrowed from me at one time (see {@link #setMaxActive})
+ * @param factory the <code>KeyedPoolableObjectFactory</code> to use to create, validate, and destroy objects
+ * if not <code>null</code>
+ * @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 #setWhenExhaustedAction})
- * @param maxWait the maximum amount of time to wait for an idle object when the pool is exhausted and <code>whenExhaustedAction</code> 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
+ * <code>whenExhaustedAction</code> 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 maxTotal the maximum number of objects that can exists at one time (see {@link #setMaxTotal})
- * @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 GenericKeyedObjectPool(KeyedPoolableObjectFactory factory, int maxActive, byte whenExhaustedAction, long maxWait, int maxIdle, int maxTotal, boolean testOnBorrow, boolean testOnReturn, long timeBetweenEvictionRunsMillis, int numTestsPerEvictionRun, long minEvictableIdleTimeMillis, boolean testWhileIdle) {
- this(factory, maxActive, whenExhaustedAction, maxWait, maxIdle, maxTotal, GenericKeyedObjectPool.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 GenericKeyedObjectPool(KeyedPoolableObjectFactory factory, int maxActive, byte whenExhaustedAction,
+ long maxWait, int maxIdle, int maxTotal, boolean testOnBorrow, boolean testOnReturn,
+ long timeBetweenEvictionRunsMillis, int numTestsPerEvictionRun, long minEvictableIdleTimeMillis,
+ boolean testWhileIdle) {
+ this(factory, maxActive, whenExhaustedAction, maxWait, maxIdle, maxTotal,
+ GenericKeyedObjectPool.DEFAULT_MIN_IDLE, testOnBorrow, testOnReturn, timeBetweenEvictionRunsMillis,
+ numTestsPerEvictionRun, minEvictableIdleTimeMillis, testWhileIdle);
}
/**
* Create a new <code>GenericKeyedObjectPool</code> using the specified values.
- * @param factory the <code>KeyedPoolableObjectFactory</code> to use to create, validate, and destroy objects if not <code>null</code>
- * @param maxActive the maximum number of objects that can be borrowed from me at one time (see {@link #setMaxActive})
+ * @param factory the <code>KeyedPoolableObjectFactory</code> to use to create, validate, and destroy objects
+ * if not <code>null</code>
+ * @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 and <code>whenExhaustedAction</code> 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
+ * <code>whenExhaustedAction</code> 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 maxTotal the maximum number of objects that can exists at one time (see {@link #setMaxTotal})
* @param minIdle the minimum number of idle objects to have in the pool at any one time (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 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})
* @since Pool 1.3
*/
- public GenericKeyedObjectPool(KeyedPoolableObjectFactory factory, int maxActive, byte whenExhaustedAction, long maxWait, int maxIdle, int maxTotal, int minIdle, boolean testOnBorrow, boolean testOnReturn, long timeBetweenEvictionRunsMillis, int numTestsPerEvictionRun, long minEvictableIdleTimeMillis, boolean testWhileIdle) {
- this(factory, maxActive, whenExhaustedAction, maxWait, maxIdle, maxTotal, minIdle, testOnBorrow, testOnReturn, timeBetweenEvictionRunsMillis, numTestsPerEvictionRun, minEvictableIdleTimeMillis, testWhileIdle, DEFAULT_LIFO);
+ public GenericKeyedObjectPool(KeyedPoolableObjectFactory factory, int maxActive, byte whenExhaustedAction,
+ long maxWait, int maxIdle, int maxTotal, int minIdle, boolean testOnBorrow, boolean testOnReturn,
+ long timeBetweenEvictionRunsMillis, int numTestsPerEvictionRun, long minEvictableIdleTimeMillis,
+ boolean testWhileIdle) {
+ this(factory, maxActive, whenExhaustedAction, maxWait, maxIdle, maxTotal, minIdle, testOnBorrow, testOnReturn,
+ timeBetweenEvictionRunsMillis, numTestsPerEvictionRun, minEvictableIdleTimeMillis, testWhileIdle,
+ DEFAULT_LIFO);
}
/**
* Create a new <code>GenericKeyedObjectPool</code> using the specified values.
- * @param factory the <code>KeyedPoolableObjectFactory</code> to use to create, validate, and destroy objects if not <code>null</code>
- * @param maxActive the maximum number of objects that can be borrowed from me at one time (see {@link #setMaxActive})
+ * @param factory the <code>KeyedPoolableObjectFactory</code> to use to create, validate, and destroy objects
+ * if not <code>null</code>
+ * @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 and <code>whenExhaustedAction</code> 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
+ * <code>whenExhaustedAction</code> 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 maxTotal the maximum number of objects that can exists at one time (see {@link #setMaxTotal})
* @param minIdle the minimum number of idle objects to have in the pool at any one time (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 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 lifo whether or not the pools behave as LIFO (last in first out) queues (see {@link #setLifo})
* @since Pool 1.4
*/
- public GenericKeyedObjectPool(KeyedPoolableObjectFactory factory, int maxActive, byte whenExhaustedAction, long maxWait, int maxIdle, int maxTotal, int minIdle, boolean testOnBorrow, boolean testOnReturn, long timeBetweenEvictionRunsMillis, int numTestsPerEvictionRun, long minEvictableIdleTimeMillis, boolean testWhileIdle, boolean lifo) {
+ public GenericKeyedObjectPool(KeyedPoolableObjectFactory factory, int maxActive, byte whenExhaustedAction,
+ long maxWait, int maxIdle, int maxTotal, int minIdle, boolean testOnBorrow, boolean testOnReturn,
+ long timeBetweenEvictionRunsMillis, int numTestsPerEvictionRun, long minEvictableIdleTimeMillis,
+ boolean testWhileIdle, boolean lifo) {
_factory = factory;
_maxActive = maxActive;
_lifo = lifo;
- switch(whenExhaustedAction) {
+ switch (whenExhaustedAction) {
case WHEN_EXHAUSTED_BLOCK:
case WHEN_EXHAUSTED_FAIL:
case WHEN_EXHAUSTED_GROW:
@@ -829,7 +920,8 @@
* Sets the number of objects to examine during each run of the
* idle object evictor thread (if any).
* <p>
- * When a negative value is supplied, <code>ceil({@link #getNumIdle()})/abs({@link #getNumTestsPerEvictionRun})</code>
+ * When a negative value is supplied,
+ * <code>ceil({@link #getNumIdle()})/abs({@link #getNumTestsPerEvictionRun})</code>
* tests will be run. I.e., when the value is <code>-n</code>, roughly one <code>n</code>th of the
* idle objects will be tested per run.
*
@@ -861,7 +953,8 @@
* 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
*/
@@ -947,7 +1040,38 @@
//-- ObjectPool methods ------------------------------------------
- public Object borrowObject(Object key) throws Exception {
+ /**
+ * <p>Borrows an object from the keyed pool associated with the given key.</p>
+ *
+ * <p>If there is an idle instance available in the pool associated with the given key, 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.</p>
+ *
+ * <p>If there are no idle instances available in the pool associated with the given key, behavior
+ * deponds on the {@link #getMaxActive() maxActive}, {@link #getMaxTotal() maxTotal}, and (if applicable)
+ * {@link #getWhenExhaustedAction() whenExhaustedAction} and {@link #getMaxWait() maxWait} properties. If the
+ * number of instances checked out from the pool under the given key is less than <code>maxActive</code> and
+ * the total number of instances in circulation (under all keys) is less than <code>maxTotal</code>, a new instance
+ * is created, activated and (if applicable) validated and returned to the caller.</p>
+ *
+ * <p>If the associated keyed 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 <code>NoSuchElementException</code>
+ * ({@link #WHEN_EXHAUSTED_FAIL}), or grow ({@link #WHEN_EXHAUSTED_GROW} - ignoring maxActive, maxTotal properties).
+ * The length of time that this method will block when <code>whenExhaustedAction == WHEN_EXHAUSTED_BLOCK</code>
+ * is determined by the {@link #getMaxWait() maxWait} property.</p>
+ *
+ * <p>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.</p>
+ *
+ * @param key pool key
+ * @return object instance from the keyed pool
+ * @throws NoSuchElementException if a keyed object instance cannot be returned.
+ */
+ public Object borrowObject(Object key) throws Exception {
long starttime = System.currentTimeMillis();
Latch latch = new Latch(key);
byte whenExhaustedAction;
@@ -990,7 +1114,7 @@
case WHEN_EXHAUSTED_BLOCK:
try {
synchronized (latch) {
- if(maxWait <= 0) {
+ if (maxWait <= 0) {
latch.wait();
} else {
// this code may be executed again after a notify then continue cycle
@@ -1007,13 +1131,14 @@
Thread.currentThread().interrupt();
throw e;
}
- if(maxWait > 0 && ((System.currentTimeMillis() - starttime) >= maxWait)) {
+ if (maxWait > 0 && ((System.currentTimeMillis() - starttime) >= maxWait)) {
throw new NoSuchElementException("Timeout waiting for idle object");
} else {
continue; // keep looping
}
default:
- throw new IllegalArgumentException("whenExhaustedAction " + whenExhaustedAction + " not recognized.");
+ throw new IllegalArgumentException("whenExhaustedAction " + whenExhaustedAction +
+ " not recognized.");
}
}
}
@@ -1060,10 +1185,10 @@
_allocationQueue.add(0, latch);
allocate();
}
- if(newlyCreated) {
+ if (newlyCreated) {
throw new NoSuchElementException(
- "Could not create a validated object, cause: "
- + e.getMessage());
+ "Could not create a validated object, cause: " +
+ e.getMessage());
}
else {
continue; // keep looping
@@ -1085,7 +1210,7 @@
// First use any objects in the pool to clear the queue
Latch latch = (Latch) _allocationQueue.getFirst();
ObjectQueue pool = (ObjectQueue)(_poolMap.get(latch.getkey()));
- if(null == pool) {
+ if (null == pool) {
pool = new ObjectQueue();
_poolMap.put(latch.getkey(), pool);
_poolList.add(latch.getkey());
@@ -1106,8 +1231,8 @@
// If there is a totalMaxActive and we are at the limit then
// we have to make room
- if ((_maxTotal > 0)
- && (_totalActive + _totalIdle + _totalInternalProcessing >= _maxTotal)) {
+ if ((_maxTotal > 0) &&
+ (_totalActive + _totalIdle + _totalInternalProcessing >= _maxTotal)) {
clearOldest();
}
@@ -1151,8 +1276,9 @@
}
/**
- * Method clears oldest 15% of objects in pool. The method sorts the
- * objects into a TreeMap and then iterates the first 15% for removal
+ * Clears oldest 15% of objects in pool. The method sorts the
+ * objects into a TreeMap and then iterates the first 15% for removal.
+ *
* @since Pool 1.3
*/
public void clearOldest() {
@@ -1234,9 +1360,11 @@
destroy(toDestroy);
}
- /*
+ /**
* Assuming Map<Object,Collection<ObjectTimestampPair>>, destroy all
* ObjectTimestampPair.value
+ *
+ * @param m Map containing keyed pools to clear
*/
private void destroy(Map m) {
for (Iterator keys = m.keySet().iterator(); keys.hasNext();) {
@@ -1300,6 +1428,24 @@
return pool != null ? pool.queue.size() : 0;
}
+ /**
+ * <p>Returns an object to a keyed pool.</p>
+ *
+ * <p>For the pool to function correctly, the object instance <strong>must</strong> have been borrowed
+ * from the pool (under the same key) and not yet returned. Repeated <code>returnObject</code> calls on
+ * the same object/key pair (with no <code>borrowObject</code> calls in between) will result in multiple
+ * references to the object in the idle instance pool.</p>
+ *
+ * <p>If {@link #getMaxIdle() maxIdle} is set to a positive value and the number of idle instances under the given
+ * key has reached this value, the returning instance is destroyed.</p>
+ *
+ * <p>If {@link #getTestOnReturn() testOnReturn} == true, the returning instance is validated before being returned
+ * to the idle instance pool under the given key. In this case, if validation fails, the instance is destroyed.</p>
+ *
+ * @param key pool key
+ * @param obj instance to return to the keyed pool
+ * @throws Exception
+ */
public void returnObject(Object key, Object obj) throws Exception {
try {
addObjectToPool(key, obj, true);
@@ -1312,7 +1458,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.
ObjectQueue pool = (ObjectQueue) (_poolMap.get(key));
if (pool != null) {
synchronized(this) {
@@ -1324,12 +1470,26 @@
}
}
+ /**
+ * <p>Adds an object to the keyed pool.</p>
+ *
+ * <p>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.</p>
+ *
+ * <p>Calls {@link #allocate()} on successful completion</p>
+ *
+ * @param key pool key
+ * @param obj instance to add to the keyed pool
+ * @param decrementNumActive whether or not to decrement the active count associated with the keyed pool
+ * @throws Exception
+ */
private void addObjectToPool(Object key, Object obj,
boolean decrementNumActive) throws Exception {
// if we need to validate this object, do so
boolean success = true; // whether or not this object passed validation
- if(_testOnReturn && !_factory.validateObject(key, obj)) {
+ if (_testOnReturn && !_factory.validateObject(key, obj)) {
success = false;
} else {
_factory.passivateObject(key, obj);
@@ -1344,7 +1504,7 @@
// grab the pool (list) of objects associated with the given key
pool = (ObjectQueue) (_poolMap.get(key));
// if it doesn't exist, create it
- if(null == pool) {
+ if (null == pool) {
pool = new ObjectQueue();
_poolMap.put(key, pool);
_poolList.add(key);
@@ -1354,9 +1514,9 @@
} else {
// if there's no space in the pool, flag the object for destruction
// else if we passivated successfully, return it to the pool
- if(_maxIdle >= 0 && (pool.queue.size() >= _maxIdle)) {
+ if (_maxIdle >= 0 && (pool.queue.size() >= _maxIdle)) {
shouldDestroy = true;
- } else if(success) {
+ } else if (success) {
// borrowObject always takes the first element from the queue,
// so for LIFO, push on top, FIFO add to end
if (_lifo) {
@@ -1374,7 +1534,7 @@
}
// Destroy the instance if necessary
- if(shouldDestroy) {
+ if (shouldDestroy) {
try {
_factory.destroyObject(key, obj);
} catch(Exception e) {
@@ -1390,13 +1550,21 @@
}
}
+ /**
+ * <p>Invalidates the object instance associated with the given key. Decrements the active count
+ * associated with the given keyed pool and destroys the instance.</p>
+ *
+ * @param key pool key
+ * @param obj instance to invalidate
+ * @throws Exception if an exception occurs destroying the object
+ */
public void invalidateObject(Object key, Object obj) throws Exception {
try {
_factory.destroyObject(key, obj);
} finally {
synchronized (this) {
ObjectQueue pool = (ObjectQueue) (_poolMap.get(key));
- if(null == pool) {
+ if (null == pool) {
pool = new ObjectQueue();
_poolMap.put(key, pool);
_poolList.add(key);
@@ -1414,7 +1582,8 @@
*
* @param key the key a new instance should be added to
* @throws Exception when {@link KeyedPoolableObjectFactory#makeObject} fails.
- * @throws IllegalStateException when no {@link #setFactory factory} has been set or after {@link #close} has been called on this pool.
+ * @throws IllegalStateException when no {@link #setFactory factory} has been set or after {@link #close} has been
+ * called on this pool.
*/
public void addObject(Object key) throws Exception {
assertOpen();
@@ -1466,15 +1635,24 @@
}
}
+ /**
+ * Closes the keyed object pool. Once the pool is closed, {@link #borrowObject(Object)}
+ * will fail with IllegalStateException, but {@link #returnObject(Object, Object)} and
+ * {@link #invalidateObject(Object, 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) {
clear();
- if(null != _evictionCursor) {
+ if (null != _evictionCursor) {
_evictionCursor.close();
_evictionCursor = null;
}
- if(null != _evictionKeyCursor) {
+ if (null != _evictionKeyCursor) {
_evictionKeyCursor.close();
_evictionKeyCursor = null;
}
@@ -1482,11 +1660,21 @@
}
}
+ /**
+ * <p>Sets the keyed poolable object factory associated with this pool.</p>
+ *
+ * <p>If this method is called when objects are checked out of any of the keyed pools,
+ * an IllegalStateException is thrown. Calling this method also has the side effect of
+ * destroying any idle instances in existing keyed pools.</p>
+ *
+ * @param factory KeyedPoolableObjectFactory to use when creating keyed object pool instances
+ * @throws IllegalStateException if there are active (checked out) instances associated with this keyed object pool
+ */
public void setFactory(KeyedPoolableObjectFactory factory) throws IllegalStateException {
Map toDestroy = new HashMap();
synchronized (this) {
assertOpen();
- if(0 < getNumActive()) {
+ if (0 < getNumActive()) {
throw new IllegalStateException("Objects are already active");
} else {
for (Iterator it = _poolMap.keySet().iterator(); it.hasNext();) {
@@ -1541,7 +1729,7 @@
}
}
- for (int i=0,m=getNumTests(); i<m; i++) {
+ for (int i=0, m=getNumTests(); i<m; i++) {
final ObjectTimestampPair pair;
synchronized (this) {
// make sure pool map is not empty; otherwise do nothing
@@ -1579,7 +1767,7 @@
// If eviction cursor is exhausted, try to move
// to the next key and reset
- if((_lifo && !_evictionCursor.hasPrevious()) ||
+ if ((_lifo && !_evictionCursor.hasPrevious()) ||
(!_lifo && !_evictionCursor.hasNext())) {
if (_evictionKeyCursor != null) {
if (_evictionKeyCursor.hasNext()) {
@@ -1597,7 +1785,7 @@
}
}
- if((_lifo && !_evictionCursor.hasPrevious()) ||
+ if ((_lifo && !_evictionCursor.hasPrevious()) ||
(!_lifo && !_evictionCursor.hasNext())) {
continue; // reset failed, do nothing
}
@@ -1613,12 +1801,12 @@
}
boolean removeObject=false;
- if((minEvictableIdleTimeMillis > 0) &&
+ if ((minEvictableIdleTimeMillis > 0) &&
(System.currentTimeMillis() - pair.tstamp >
minEvictableIdleTimeMillis)) {
removeObject=true;
}
- if(testWhileIdle && removeObject == false) {
+ if (testWhileIdle && removeObject == false) {
boolean active = false;
try {
_factory.activateObject(key,pair.value);
@@ -1626,8 +1814,8 @@
} catch(Exception e) {
removeObject=true;
}
- if(active) {
- if(!_factory.validateObject(key,pair.value)) {
+ if (active) {
+ if (!_factory.validateObject(key,pair.value)) {
removeObject=true;
} else {
try {
@@ -1639,7 +1827,7 @@
}
}
- if(removeObject) {
+ if (removeObject) {
try {
_factory.destroyObject(key, pair.value);
} catch(Exception e) {
@@ -1665,7 +1853,7 @@
}
}
synchronized (this) {
- if(!removeObject) {
+ if (!removeObject) {
_evictionCursor.add(pair);
_totalIdle++;
if (_lifo) {
@@ -1788,11 +1976,11 @@
* @param delay milliseconds between evictor runs.
*/
protected synchronized void startEvictor(long delay) {
- if(null != _evictor) {
+ if (null != _evictor) {
EvictionTimer.cancel(_evictor);
_evictor = null;
}
- if(delay > 0) {
+ if (delay > 0) {
_evictor = new Evictor();
EvictionTimer.schedule(_evictor, delay, delay);
}
@@ -1803,14 +1991,14 @@
buf.append("Active: ").append(getNumActive()).append("\n");
buf.append("Idle: ").append(getNumIdle()).append("\n");
Iterator it = _poolMap.keySet().iterator();
- while(it.hasNext()) {
+ while (it.hasNext()) {
buf.append("\t").append(_poolMap.get(it.next())).append("\n");
}
return buf.toString();
}
private synchronized int getNumTests() {
- if(_numTestsPerEvictionRun >= 0) {
+ if (_numTestsPerEvictionRun >= 0) {
return _numTestsPerEvictionRun;
} else {
return(int)(Math.ceil(_totalIdle/Math.abs((double)_numTestsPerEvictionRun)));
@@ -1820,14 +2008,9 @@
/**
* This returns the number of objects to create during the pool
* sustain cycle. This will ensure that the minimum number of idle
- * connections is maintained without going past the maxPool value.
- * <p>
- * This method has been left public so derived classes can override
- * the way the defecit is calculated. ie... Increase/decrease the pool
- * size at certain times of day to accommodate for usage patterns.
- *
- * @param key - The key of the pool to calculate the number of
- * objects to be re-created
+ * instances is maintained without going past the maxActive value.
+ *
+ * @param pool the ObjectPool to calculate the deficit for
* @param incrementInternal - Should the count of objects currently under
* some form of internal processing be
* incremented?
@@ -1863,10 +2046,16 @@
* A "struct" that keeps additional information about the actual queue of pooled objects.
*/
private class ObjectQueue {
+ /** Number of instances checked out to clients from this queue */
private int activeCount = 0;
+
+ /** Idle instance queue */
private final CursorableLinkedList queue = new CursorableLinkedList();
+
+ /** Number of instances in process of being created */
private int internalProcessingCount = 0;
+ /** Increment the active count for this queue */
void incrementActiveCount() {
synchronized (GenericKeyedObjectPool.this) {
_totalActive++;
@@ -1874,6 +2063,7 @@
activeCount++;
}
+ /** Decrement the active count for this queue */
void decrementActiveCount() {
synchronized (GenericKeyedObjectPool.this) {
_totalActive--;
@@ -1883,6 +2073,7 @@
}
}
+ /** Record the fact that one more instance is queued for creation */
void incrementInternalProcessingCount() {
synchronized (GenericKeyedObjectPool.this) {
_totalInternalProcessing++;
@@ -1890,6 +2081,7 @@
internalProcessingCount++;
}
+ /** Decrement the number of instances in process of being created */
void decrementInternalProcessingCount() {
synchronized (GenericKeyedObjectPool.this) {
_totalInternalProcessing--;
@@ -1906,26 +2098,58 @@
* This is also used by {@link GenericObjectPool}.
*/
static class ObjectTimestampPair implements Comparable {
+
+ /** Object instance */
Object value;
+
+ /** timestamp */
long tstamp;
+ /**
+ * Create a new ObjectTimestampPair using the given object and the current system time.
+ * @param val object instance
+ */
ObjectTimestampPair(Object val) {
this(val, System.currentTimeMillis());
}
+ /**
+ * Create a new ObjectTimeStampPair using the given object and timestamp value.
+ * @param val object instance
+ * @param time long representation of timestamp
+ */
ObjectTimestampPair(Object val, long time) {
value = val;
tstamp = time;
}
+ /**
+ * Returns a string representation.
+ *
+ * @return String representing this ObjectTimestampPair
+ */
public String toString() {
return value + ";" + tstamp;
}
+ /**
+ * Compares this to another object by casting the argument to an
+ * ObjectTimestampPair.
+ *
+ * @param obj object to cmpare
+ * @return result of comparison
+ */
public int compareTo(Object obj) {
return compareTo((ObjectTimestampPair) obj);
}
+ /**
+ * Compares this to another ObjectTimestampPair, using the timestamp as basis for comparison.
+ * Implementation is consistent with equals.
+ *
+ * @param other object to compare
+ * @return result of comparison
+ */
public int compareTo(ObjectTimestampPair other) {
final long tstampdiff = this.tstamp - other.tstamp;
if (tstampdiff == 0) {
@@ -1955,7 +2179,7 @@
// case error is recoverable
oome.printStackTrace(System.err);
}
- //Re-create the connections.
+ //Re-create idle instances.
try {
ensureMinIdle();
} catch (Exception e) {
@@ -2027,40 +2251,87 @@
/**
* Latch used to control allocation order of objects to threads to ensure
- * fairness. ie objects are allocated to threads in the order that threads
+ * fairness. That is, objects are allocated to threads in the order that threads
* request objects.
+ *
+ * @since 1.5
*/
private static final class Latch {
+
+ /** key of associated pool */
private Object _key;
+
+ /** keyed pool associated with this latch */
private ObjectQueue _pool;
+
+ /** holds an ObjectTimestampPair when this latch has been allocated an instance */
private ObjectTimestampPair _pair;
+
+ /** indicates that this latch can create an instance */
private boolean _mayCreate = false;
+ /**
+ * Create a latch with the given key
+ * @param key key of the pool associated with this latch
+ */
private Latch(Object key) {
_key = key;
}
+ /**
+ * Retuns the key of the associated pool
+ * @return associated pool key
+ */
private synchronized Object getkey() {
return _key;
}
+ /**
+ * Returns the pool associated with this latch
+ * @return pool
+ */
private synchronized ObjectQueue getPool() {
return _pool;
}
+
+ /**
+ * Sets the pool associated with this latch
+ * @param pool the pool
+ */
private synchronized void setPool(ObjectQueue pool) {
_pool = pool;
}
+ /**
+ * Gets the ObjectTimestampPair allocated to this latch.
+ * Returns null of this latch does not have an instance allocated to it.
+ * @return the associated ObjectTimestampPair
+ */
private synchronized ObjectTimestampPair getPair() {
return _pair;
}
+
+ /**
+ * Allocate an ObjectTimestampPair to this latch.
+ * @param pair ObjectTimestampPair on this latch
+ */
private synchronized void setPair(ObjectTimestampPair pair) {
_pair = pair;
}
+ /**
+ * Whether or not this latch can create an instance
+ * @return true if this latch has an instance creation permit
+ */
private synchronized boolean mayCreate() {
return _mayCreate;
}
+
+ /**
+ * Sets the mayCreate property
+ *
+ * @param mayCreate true means this latch can create an instance
+ */
private synchronized void setMayCreate(boolean mayCreate) {
_mayCreate = mayCreate;
}
@@ -2244,7 +2515,10 @@
*/
private CursorableLinkedList _poolList = null;
+ /** Eviction cursor (over instances within-key) */
private CursorableLinkedList.Cursor _evictionCursor = null;
+
+ /** Eviction cursor (over keys) */
private CursorableLinkedList.Cursor _evictionKeyCursor = null;
/** Whether or not the pools behave as LIFO queues (last in first out) */