You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by ma...@apache.org on 2012/05/02 15:44:44 UTC
svn commit: r1333046 - in
/commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/impl:
BaseGenericObjectPool.java GenericKeyedObjectPool.java
Author: markt
Date: Wed May 2 13:44:44 2012
New Revision: 1333046
URL: http://svn.apache.org/viewvc?rev=1333046&view=rev
Log:
Javadoc. Remove duplication.
Modified:
commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/impl/BaseGenericObjectPool.java
commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/impl/GenericKeyedObjectPool.java
Modified: commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/impl/BaseGenericObjectPool.java
URL: http://svn.apache.org/viewvc/commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/impl/BaseGenericObjectPool.java?rev=1333046&r1=1333045&r2=1333046&view=diff
==============================================================================
--- commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/impl/BaseGenericObjectPool.java (original)
+++ commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/impl/BaseGenericObjectPool.java Wed May 2 13:44:44 2012
@@ -288,9 +288,10 @@ public abstract class BaseGenericObjectP
/**
* Returns whether objects borrowed from the pool will be validated before
* being returned from the <code>borrowObject()</code> method. Validation is
- * performed by the factory associated with the pool. If the object fails to
- * validate, it will be removed from the pool and destroyed, and a new
- * attempt will be made to borrow an object from the pool.
+ * performed by the <code>validateObject()</code> method of the factory
+ * associated with the pool. If the object fails to validate, it will be
+ * removed from the pool and destroyed, and a new attempt will be made to
+ * borrow an object from the pool.
*
* @return <code>true</code> if objects are validated before being returned
* from the <code>borrowObject()</code> method
@@ -304,9 +305,10 @@ public abstract class BaseGenericObjectP
/**
* Sets whether objects borrowed from the pool will be validated before
* being returned from the <code>borrowObject()</code> method. Validation is
- * performed by the factory associated with the pool. If the object fails to
- * validate, it will be removed from the pool and destroyed, and a new
- * attempt will be made to borrow an object from the pool.
+ * performed by the <code>validateObject()</code> method of the factory
+ * associated with the pool. If the object fails to validate, it will be
+ * removed from the pool and destroyed, and a new attempt will be made to
+ * borrow an object from the pool.
*
* @param testOnBorrow <code>true</code> if objects should be validated
* before being returned from the
@@ -321,8 +323,9 @@ public abstract class BaseGenericObjectP
/**
* Returns whether objects borrowed from the pool will be validated when
* they are returned to the pool via the <code>returnObject()</code> method.
- * Validation is performed by the factory associated with the pool. If the
- * object fails to it will be destroyed rather then returned the pool.
+ * Validation is performed by the <code>validateObject()</code> method of
+ * the factory associated with the pool. If the object fails to it will be
+ * destroyed rather then returned the pool.
*
* @return <code>true</code> if objects are validated on being returned to
* the pool via the <code>returnObject()</code> method
@@ -336,8 +339,9 @@ public abstract class BaseGenericObjectP
/**
* Sets whether objects borrowed from the pool will be validated when
* they are returned to the pool via the <code>returnObject()</code> method.
- * Validation is performed by the factory associated with the pool. If the
- * object fails to it will be destroyed rather then returned the pool.
+ * Validation is performed by the <code>validateObject()</code> method of
+ * the factory associated with the pool. If the object fails to it will be
+ * destroyed rather then returned the pool.
*
* @param testOnReturn <code>true</code> if objects are validated on being
* returned to the pool via the
@@ -353,8 +357,9 @@ public abstract class BaseGenericObjectP
* Returns whether objects sitting idle in the pool will be validated by the
* idle object evictor (if any - see
* {@link #setTimeBetweenEvictionRunsMillis(long)}). Validation is performed
- * by the factory associated with the pool. If the object fails to validate,
- * it will be removed from the pool and destroyed.
+ * by the <code>validateObject()</code> method of the factory associated
+ * with the pool. If the object fails to validate, it will be removed from
+ * the pool and destroyed.
*
* @return <code>true</code> if objects will be validated by the evictor
*
@@ -369,8 +374,9 @@ public abstract class BaseGenericObjectP
* Returns whether objects sitting idle in the pool will be validated by the
* idle object evictor (if any - see
* {@link #setTimeBetweenEvictionRunsMillis(long)}). Validation is performed
- * by the factory associated with the pool. If the object fails to validate,
- * it will be removed from the pool and destroyed.
+ * by the <code>validateObject()</code> method of the factory associated
+ * with the pool. If the object fails to validate, it will be removed from
+ * the pool and destroyed.
*
* @param testWhileIdle
* <code>true</code> so objects will be validated by the evictor
Modified: commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/impl/GenericKeyedObjectPool.java
URL: http://svn.apache.org/viewvc/commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/impl/GenericKeyedObjectPool.java?rev=1333046&r1=1333045&r2=1333046&view=diff
==============================================================================
--- commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/impl/GenericKeyedObjectPool.java (original)
+++ commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/impl/GenericKeyedObjectPool.java Wed May 2 13:44:44 2012
@@ -42,81 +42,12 @@ import org.apache.commons.pool2.PoolUtil
* When coupled with the appropriate {@link KeyedPoolableObjectFactory},
* <code>GenericKeyedObjectPool</code> provides robust pooling functionality for
* keyed objects. A <code>GenericKeyedObjectPool</code> can be viewed as a map
- * of pools, keyed on the (unique) key values provided to the
+ * of sub-pools, keyed on the (unique) key values provided to the
* {@link #preparePool preparePool}, {@link #addObject addObject} or
* {@link #borrowObject borrowObject} methods. Each time a new key value is
- * provided to one of these methods, a new pool is created under the given key
- * to be managed by the containing <code>GenericKeyedObjectPool.</code>
+ * provided to one of these methods, a sub-new pool is created under the given
+ * key to be managed by the containing <code>GenericKeyedObjectPool.</code>
* </p>
- * <p>A <code>GenericKeyedObjectPool</code> provides a number of configurable
- * parameters:</p>
- * <ul>
- * <li>
- * {@link #setMaxTotalPerKey maxTotalPerKey} controls the maximum number of objects
- * (per key) that can allocated by the pool (checked out to client threads,
- * or idle in the pool) at one time. When non-positive, there is no limit
- * to the number of objects per key. When {@link #setMaxTotalPerKey maxTotalPerKey} is
- * reached, the keyed pool is said to be exhausted. The default setting for
- * this parameter is 8.
- * </li>
- * <li>
- * {@link #setMaxTotal maxTotal} sets a global limit on the number of objects
- * that can be in circulation (active or idle) within the combined set of
- * pools. When non-positive, there is no limit to the total number of
- * objects in circulation. When {@link #setMaxTotal maxTotal} is exceeded,
- * all keyed pools are exhausted. When <code>maxTotal</code> is set to a
- * positive value and {@link #borrowObject borrowObject} is invoked
- * when at the limit with no idle instances available, an attempt is made to
- * create room by clearing the oldest 15% of the elements from the keyed
- * pools. The default setting for this parameter is -1 (no limit).
- * </li>
- * <li>
- * {@link #setMaxIdlePerKey maxIdlePerKey} controls the maximum number of objects that can
- * sit idle in the pool (per key) at any time. When negative, there
- * is no limit to the number of objects that may be idle per key. The
- * default setting for this parameter is 8.
- * </li>
- * <li>
- * {@link #getBlockWhenExhausted} specifies the
- * behavior of the {@link #borrowObject borrowObject} method when a keyed
- * pool is exhausted:
- * <ul>
- * <li>
- * When {@link #getBlockWhenExhausted} is false,
- * {@link #borrowObject borrowObject} will throw
- * a {@link NoSuchElementException}
- * </li>
- * <li>
- * When {@link #getBlockWhenExhausted} is true,
- * {@link #borrowObject borrowObject} will block
- * (invoke {@link Object#wait() wait} until a new or idle object is available.
- * If a non-negative {@link #setMaxWaitMillis(long) maxWait}
- * value is supplied, the {@link #borrowObject borrowObject} will block for at
- * most that many milliseconds, after which a {@link NoSuchElementException}
- * will be thrown. If {@link #setMaxWaitMillis(long) maxWait} is negative,
- * the {@link #borrowObject borrowObject} method will block indefinitely.
- * </li>
- * </ul>
- * The default {@link #getBlockWhenExhausted()} setting is true.
- * </li>
- * <li>
- * When {@link #setTestOnBorrow testOnBorrow} is set, the pool will
- * attempt to validate each object before it is returned from the
- * {@link #borrowObject borrowObject} method. (Using the provided factory's
- * {@link KeyedPoolableObjectFactory#validateObject validateObject} method.)
- * Objects that fail to validate will be dropped from the pool, and a
- * different object will be borrowed. The default setting for this parameter
- * is <code>false.</code>
- * </li>
- * <li>
- * When {@link #setTestOnReturn testOnReturn} is set, the pool will
- * attempt to validate each object before it is returned to the pool in the
- * {@link #returnObject returnObject} method. (Using the provided factory's
- * {@link KeyedPoolableObjectFactory#validateObject validateObject}
- * method.) Objects that fail to validate will be dropped from the pool.
- * The default setting for this parameter is <code>false.</code>
- * </li>
- * </ul>
* <p>
* Optionally, one may configure the pool to examine and possibly evict objects
* as they sit idle in the pool and to ensure that a minimum number of idle
@@ -126,45 +57,6 @@ import org.apache.commons.pool2.PoolUtil
* threads for access to objects in the pool, so if they run too frequently
* performance issues may result. The idle object eviction thread may be
* configured using the following attributes:
- * <ul>
- * <li>
- * {@link #setTimeBetweenEvictionRunsMillis timeBetweenEvictionRunsMillis}
- * indicates how long the eviction thread should sleep before "runs" of examining
- * idle objects. When non-positive, no eviction thread will be launched. The
- * default setting for this parameter is -1 (i.e., by default, idle object
- * eviction is disabled).
- * </li>
- * <li>
- * {@link #setMinEvictableIdleTimeMillis minEvictableIdleTimeMillis}
- * specifies the minimum amount of time that an object may sit idle in the
- * pool before it is eligible for eviction due to idle time. When
- * non-positive, no object will be dropped from the pool due to idle time
- * alone. This setting has no effect unless
- * <code>timeBetweenEvictionRunsMillis > 0.</code> The default setting
- * for this parameter is 30 minutes.
- * </li>
- * <li>
- * {@link #setTestWhileIdle testWhileIdle} indicates whether or not idle
- * objects should be validated using the factory's
- * {@link KeyedPoolableObjectFactory#validateObject validateObject} method
- * during idle object eviction runs. Objects that fail to validate will be
- * dropped from the pool. This setting has no effect unless
- * <code>timeBetweenEvictionRunsMillis > 0.</code> The default setting
- * for this parameter is <code>false.</code>
- * </li>
- * <li>
- * {@link #setMinIdlePerKey minIdlePerKey} sets a target value for the minimum number of
- * idle objects (per key) that should always be available. If this parameter
- * is set to a positive number and
- * <code>timeBetweenEvictionRunsMillis > 0,</code> each time the idle object
- * eviction thread runs, it will try to create enough idle instances so that
- * there will be <code>minIdle</code> idle instances available under each
- * key. This parameter is also used by {@link #preparePool preparePool}
- * if <code>true</code> is provided as that method's
- * <code>populateImmediately</code> parameter. The default setting for this
- * parameter is 0.
- * </li>
- * </ul>
* <p>
* GenericKeyedObjectPool is not usable without a {@link KeyedPoolableObjectFactory}. A
* non-<code>null</code> factory must be provided as a constructor argument
@@ -216,11 +108,12 @@ public class GenericKeyedObjectPool<K,T>
}
/**
- * Returns the cap on the number of object instances allocated by the pool
- * (checked out or idle), per key.
- * A negative value indicates no limit.
+ * Returns the limit on the number of object instances allocated by the pool
+ * (checked out or idle), per key. When the limit is reached, the pool is
+ * said to be exhausted. A negative value indicates no limit.
+ *
+ * @return the limit on the number of active instances per key
*
- * @return the cap on the number of active instances per key.
* @see #setMaxTotalPerKey
*/
@Override
@@ -229,9 +122,11 @@ public class GenericKeyedObjectPool<K,T>
}
/**
- * Sets the cap on the number of object instances managed by the pool per key.
- * @param maxTotalPerKey The cap on the number of object instances per key.
- * Use a negative value for no limit.
+ * Sets the limit on the number of object instances allocated by the pool
+ * (checked out or idle), per key. When the limit is reached, the pool is
+ * said to be exhausted. A negative value indicates no limit.
+ *
+ * @param maxTotalPerKey the limit on the number of active instances per key
*
* @see #getMaxTotalPerKey
*/
@@ -241,9 +136,18 @@ public class GenericKeyedObjectPool<K,T>
/**
- * Returns the cap on the number of "idle" instances per key.
+ * Returns the cap on the number of "idle" instances per key in the pool.
+ * If maxIdle is set too low on heavily loaded systems it is possible you
+ * will see objects being destroyed and almost immediately new objects
+ * being created. This is a result of the active threads momentarily
+ * returning objects faster than they are requesting them them, causing the
+ * number of idle objects to rise above maxIdle. The best value for maxIdle
+ * for heavily loaded system will vary but the default is a good starting
+ * point.
+ *
* @return the maximum number of "idle" instances that can be held
- * in a given keyed pool.
+ * in a given keyed pool or a negative value if there is no limit
+ *
* @see #setMaxIdlePerKey
*/
@Override
@@ -252,7 +156,7 @@ public class GenericKeyedObjectPool<K,T>
}
/**
- * Sets the cap on the number of "idle" instances in the pool.
+ * Sets the cap on the number of "idle" instances per key in the pool.
* If maxIdle is set too low on heavily loaded systems it is possible you
* will see objects being destroyed and almost immediately new objects
* being created. This is a result of the active threads momentarily
@@ -260,47 +164,53 @@ public class GenericKeyedObjectPool<K,T>
* number of idle objects to rise above maxIdle. The best value for maxIdle
* for heavily loaded system will vary but the default is a good starting
* point.
- * @param maxIdle the maximum number of "idle" instances that can be held
- * in a given keyed pool. Use a negative value for no limit.
+ *
+ * @param maxIdlePerKey the maximum number of "idle" instances that can be
+ * held in a given keyed pool. Use a negative value for
+ * no limit
+ *
* @see #getMaxIdlePerKey
*/
- public void setMaxIdlePerKey(int maxIdle) {
- maxIdlePerKey = maxIdle;
+ public void setMaxIdlePerKey(int maxIdlePerKey) {
+ this.maxIdlePerKey = maxIdlePerKey;
}
/**
- * Sets the minimum number of idle objects to maintain in each of the keyed
- * pools. This setting has no effect unless
- * <code>timeBetweenEvictionRunsMillis > 0</code> and attempts to ensure
- * that each pool has the required minimum number of instances are only
- * made during idle object eviction runs.
+ * Sets the target for the minimum number of idle objects to maintain in
+ * each of the keyed sub-pools. This setting only has an effect if it is
+ * positive and {@link #getTimeBetweenEvictionRunsMillis()} is greater than
+ * zero. If this is the case, an attempt is made to ensure that each
+ * sub-pool has the required minimum number of instances during idle object
+ * eviction runs.
* <p>
* If the configured value of minIdlePerKey is greater than the configured
* value for maxIdlePerKey then the value of maxIdlePerKey will be used
* instead.
*
- * @param poolSize - The minimum size of the each keyed pool
- * @since Pool 1.3
+ * @param minIdlePerKey The minimum size of the each keyed pool
+ *
* @see #getMinIdlePerKey
+ * @see #getMaxIdlePerKey()
* @see #setTimeBetweenEvictionRunsMillis
*/
- public void setMinIdlePerKey(int poolSize) {
- minIdlePerKey = poolSize;
+ public void setMinIdlePerKey(int minIdlePerKey) {
+ this.minIdlePerKey = minIdlePerKey;
}
/**
- * Returns the minimum number of idle objects to maintain in each of the keyed
- * pools. This setting has no effect unless
- * <code>timeBetweenEvictionRunsMillis > 0</code> and attempts to ensure
- * that each pool has the required minimum number of instances are only
- * made during idle object eviction runs.
+ * Returns the target for the minimum number of idle objects to maintain in
+ * each of the keyed sub-pools. This setting only has an effect if it is
+ * positive and {@link #getTimeBetweenEvictionRunsMillis()} is greater than
+ * zero. If this is the case, an attempt is made to ensure that each
+ * sub-pool has the required minimum number of instances during idle object
+ * eviction runs.
* <p>
* If the configured value of minIdlePerKey is greater than the configured
* value for maxIdlePerKey then the value of maxIdlePerKey will be used
* instead.
*
* @return minimum size of the each keyed pool
- * @since Pool 1.3
+ *
* @see #setTimeBetweenEvictionRunsMillis
*/
@Override
@@ -1199,7 +1109,7 @@ public class GenericKeyedObjectPool<K,T>
* @throws Exception If there was an error whilst creating the pooled objects.
*/
@Override
- protected void ensureMinIdle() throws Exception {
+ void ensureMinIdle() throws Exception {
int minIdlePerKey = getMinIdlePerKey();
if (minIdlePerKey < 1) {
return;