commons-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From pste...@apache.org
Subject svn commit: r606732 - /commons/proper/pool/branches/1_4_RELEASE_BRANCH/src/java/org/apache/commons/pool/impl/GenericObjectPool.java
Date Mon, 24 Dec 2007 19:50:00 GMT
Author: psteitz
Date: Mon Dec 24 11:49:57 2007
New Revision: 606732

URL: http://svn.apache.org/viewvc?rev=606732&view=rev
Log:
Javadoc only.
Clarified meaning of several configuration parameters and included
default parameter settings in class javadoc.

Modified:
    commons/proper/pool/branches/1_4_RELEASE_BRANCH/src/java/org/apache/commons/pool/impl/GenericObjectPool.java

Modified: commons/proper/pool/branches/1_4_RELEASE_BRANCH/src/java/org/apache/commons/pool/impl/GenericObjectPool.java
URL: http://svn.apache.org/viewvc/commons/proper/pool/branches/1_4_RELEASE_BRANCH/src/java/org/apache/commons/pool/impl/GenericObjectPool.java?rev=606732&r1=606731&r2=606732&view=diff
==============================================================================
--- commons/proper/pool/branches/1_4_RELEASE_BRANCH/src/java/org/apache/commons/pool/impl/GenericObjectPool.java
(original)
+++ commons/proper/pool/branches/1_4_RELEASE_BRANCH/src/java/org/apache/commons/pool/impl/GenericObjectPool.java
Mon Dec 24 11:49:57 2007
@@ -36,19 +36,22 @@
  * A <tt>GenericObjectPool</tt> provides a number of configurable parameters:
  * <ul>
  *  <li>
- *    {@link #setMaxActive <i>maxActive</i>} controls the maximum number of objects
that can
- *    be borrowed from the pool at one time.  When non-positive, there
- *    is no limit to the number of objects that may be active at one time.
- *    When {@link #setMaxActive <i>maxActive</i>} is exceeded, the pool is said
to be exhausted.
+ *    {@link #setMaxActive <i>maxActive</i>} controls the maximum number of
+ *    objects that can be borrowed from the pool at one time.  When
+ *    non-positive, there is no limit to the number of objects that may be
+ *    active at one time. When {@link #setMaxActive <i>maxActive</i>} is
+ *    exceeded, the pool is said to be exhausted. The default setting for this
+ *    parameter is 8.
  *  </li>
  *  <li>
- *    {@link #setMaxIdle <i>maxIdle</i>} controls the maximum number of objects
that can
- *    sit idle in the pool at any time.  When negative, there
- *    is no limit to the number of objects that may be idle at one time.
+ *    {@link #setMaxIdle <i>maxIdle</i>} controls the maximum number of objects
+ *    that can sit idle in the pool at any time.  When negative, there is no
+ *    limit to the number of objects that may be idle at one time. The default
+ *    setting for this parameter is 8.
  *  </li>
  *  <li>
  *    {@link #setWhenExhaustedAction <i>whenExhaustedAction</i>} specifies the
- *    behaviour of the {@link #borrowObject} method when the pool is exhausted:
+ *    behavior of the {@link #borrowObject} method when the pool is exhausted:
  *    <ul>
  *    <li>
  *      When {@link #setWhenExhaustedAction <i>whenExhaustedAction</i>} is
@@ -72,6 +75,10 @@
  *      the {@link #borrowObject} method will block indefinitely.
  *    </li>
  *    </ul>
+ *    The default <code>whenExhaustedAction</code> setting is
+ *    {@link #WHEN_EXHAUSTED_BLOCK} and the default <code>maxWait</code>
+ *    setting is -1. By default, therefore, <code>borrowObject</code> will
+ *    block indefinitely until an idle instance becomes available.
  *  </li>
  *  <li>
  *    When {@link #setTestOnBorrow <i>testOnBorrow</i>} is set, the pool will
@@ -79,7 +86,8 @@
  *    {@link #borrowObject} method. (Using the provided factory's
  *    {@link PoolableObjectFactory#validateObject} method.)  Objects that fail
  *    to validate will be dropped from the pool, and a different object will
- *    be borrowed.
+ *    be borrowed. The default setting for this parameter is
+ *    <code>false.</code>
  *  </li>
  *  <li>
  *    When {@link #setTestOnReturn <i>testOnReturn</i>} is set, the pool will
@@ -87,30 +95,42 @@
  *    {@link #returnObject} method. (Using the provided factory's
  *    {@link PoolableObjectFactory#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.  This is performed by an "idle object eviction" thread, which
- * runs asynchronously.  The idle object eviction thread may be configured using the
- * following attributes:
+ * Optionally, one may configure the pool to examine and possibly evict objects
+ * as they sit idle in the pool and to ensure that a minimum number of idle
+ * objects are available. This is performed by an "idle object eviction"
+ * thread, which runs asynchronously. Caution should be used when configuring
+ * this optional feature. Eviction runs require an exclusive synchronization
+ * lock on the pool, so if they run too frequently and / or incur excessive
+ * latency when creating, destroying or validating object instances,
+ * performance issues may result.  The idle object eviction thread may be
+ * configured using the following attributes:
  * <ul>
  *  <li>
  *   {@link #setTimeBetweenEvictionRunsMillis <i>timeBetweenEvictionRunsMillis</i>}
  *   indicates how long the eviction thread should sleep before "runs" of examining
- *   idle objects.  When non-positive, no eviction thread will be launched.
+ *   idle objects.  When non-positive, no eviction thread will be launched. The
+ *   default setting for this parameter is -1 (i.e., idle object eviction is
+ *   disabled by default).
  *  </li>
  *  <li>
  *   {@link #setMinEvictableIdleTimeMillis <i>minEvictableIdleTimeMillis</i>}
  *   specifies the minimum amount of time that an object may sit idle in the pool
  *   before it is eligible for eviction due to idle time.  When non-positive, no object
- *   will be dropped from the pool due to idle time alone.
+ *   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 <i>testWhileIdle</i>} indicates whether or not
idle
  *   objects should be validated using the factory's
- *   {@link PoolableObjectFactory#validateObject} method.  Objects
- *   that fail to validate will be dropped from the pool.
+ *   {@link PoolableObjectFactory#validateObject} method. 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 #setSoftMinEvictableIdleTimeMillis <i>softMinEvictableIdleTimeMillis</i>}

@@ -118,7 +138,16 @@
  *   before it is eligible for eviction by the idle object evictor
  *   (if any), with the extra condition that at least "minIdle" amount of object 
  *   remain in the pool.  When non-positive, no objects will be evicted from the pool
- *   due to idle time alone.
+ *   due to idle time alone. This setting has no effect unless
+ *   <code>timeBetweenEvictionRunsMillis > 0.</code>  The default setting
for
+ *   this parameter is -1 (disabled).
+ *  </li>
+ *  <li>
+ *   {@link #setNumTestsPerEvictionRun <i>numTestsPerEvictionRun</i>}
+ *   determines the number of objects examined in each run of the idle object
+ *   evictor. This setting has no effect unless 
+ *   <code>timeBetweenEvictionRunsMillis > 0.</code>  The default setting
for
+ *   this parameter is 3.  
  *  </li>
  * </ul>
  * <p>
@@ -131,7 +160,8 @@
  *  <li>
  *   {@link #setLifo <i>lifo</i>}
  *   determines whether or not the pool returns idle objects in 
- *   last-in-first-out order.
+ *   last-in-first-out order. The default setting for this parameter is
+ *   <code>true.</code>
  *  </li>
  * </ul>
  * <p>
@@ -228,7 +258,7 @@
     public static final boolean DEFAULT_LIFO = true;
 
     /**
-     * The default maximum amount of time (in millis) the
+     * The default maximum amount of time (in milliseconds) the
      * {@link #borrowObject} method should block before throwing
      * an exception when the pool is exhausted and the
      * {@link #getWhenExhaustedAction "when exhausted" action} is
@@ -486,8 +516,8 @@
     //--- configuration methods --------------------------------------
 
     /**
-     * Returns the cap on the total number of active instances from my pool.
-     * @return the cap on the total number of active instances from my pool.
+     * Returns the cap on the total number of active instances from the pool.
+     * @return the cap on the total number of active instances from the pool.
      * @see #setMaxActive
      */
     public synchronized int getMaxActive() {
@@ -495,9 +525,9 @@
     }
 
     /**
-     * Sets the cap on the total number of active instances from my pool.
-     * @param maxActive The cap on the total number of active instances from my pool.
-     *                  Use a negative value for an infinite number of instances.
+     * Sets the cap on the total number of active instances from the pool.
+     * @param maxActive The cap on the total number of active instances from the pool.
+     * Use a negative value for no limit.
      * @see #getMaxActive
      */
     public synchronized void setMaxActive(int maxActive) {
@@ -592,8 +622,7 @@
     /**
      * Sets the cap on the number of "idle" instances in the pool.
      * @param maxIdle The cap on the number of "idle" instances in the pool.
-     *                Use a negative value to indicate an unlimited number
-     *                of idle instances.
+     * Use a negative value to indicate an unlimited number of idle instances.
      * @see #getMaxIdle
      */
     public synchronized void setMaxIdle(int maxIdle) {
@@ -604,10 +633,14 @@
     /**
      * Sets the minimum number of objects allowed in the pool
      * before the evictor thread (if active) spawns new objects.
-     * (Note no objects are created when: numActive + numIdle >= maxActive)
+     * Note that no objects are created when 
+     * <code>numActive + numIdle >= maxActive.</code>
+     * This setting has no effect if the idle object evictor is disabled
+     * (i.e. if <code>timeBetweenEvictionRunsMillis <= 0</code>).
      *
      * @param minIdle The minimum number of objects.
      * @see #getMinIdle
+     * @see #getTimeBetweenEvictionRunsMillis()
      */
     public synchronized void setMinIdle(int minIdle) {
         _minIdle = minIdle;



Mime
View raw message