commons-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From simonetrip...@apache.org
Subject svn commit: r1051772 - /commons/proper/pool/trunk/src/java/org/apache/commons/pool2/impl/
Date Wed, 22 Dec 2010 06:56:04 GMT
Author: simonetripodi
Date: Wed Dec 22 06:56:04 2010
New Revision: 1051772

URL: http://svn.apache.org/viewvc?rev=1051772&view=rev
Log:
original comments back from interface to pool implementation classes
first attempt of simplification on javadoc MBean interfaces, stripped @since because the whole interface is marked with @since 2.0

Modified:
    commons/proper/pool/trunk/src/java/org/apache/commons/pool2/impl/GenericKeyedObjectPool.java
    commons/proper/pool/trunk/src/java/org/apache/commons/pool2/impl/GenericKeyedObjectPoolMBean.java
    commons/proper/pool/trunk/src/java/org/apache/commons/pool2/impl/GenericObjectPool.java
    commons/proper/pool/trunk/src/java/org/apache/commons/pool2/impl/GenericObjectPoolMBean.java
    commons/proper/pool/trunk/src/java/org/apache/commons/pool2/impl/StackKeyedObjectPool.java
    commons/proper/pool/trunk/src/java/org/apache/commons/pool2/impl/StackKeyedObjectPoolMBean.java
    commons/proper/pool/trunk/src/java/org/apache/commons/pool2/impl/StackObjectPool.java
    commons/proper/pool/trunk/src/java/org/apache/commons/pool2/impl/StackObjectPoolMBean.java

Modified: commons/proper/pool/trunk/src/java/org/apache/commons/pool2/impl/GenericKeyedObjectPool.java
URL: http://svn.apache.org/viewvc/commons/proper/pool/trunk/src/java/org/apache/commons/pool2/impl/GenericKeyedObjectPool.java?rev=1051772&r1=1051771&r2=1051772&view=diff
==============================================================================
--- commons/proper/pool/trunk/src/java/org/apache/commons/pool2/impl/GenericKeyedObjectPool.java (original)
+++ commons/proper/pool/trunk/src/java/org/apache/commons/pool2/impl/GenericKeyedObjectPool.java Wed Dec 22 06:56:04 2010
@@ -251,14 +251,29 @@ public class GenericKeyedObjectPool<K,V>
     //--- configuration methods --------------------------------------
 
     /**
-     * {@inheritDoc}
+     * 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.
+     *
+     * @return the cap on the number of active instances per key.
+     * @see #setMaxTotalPerKey
+     * @since 2.0
      */
     public synchronized int getMaxTotalPerKey() {
         return this.maxTotalPerKey;
     }
 
     /**
-     * {@inheritDoc}
+     * Sets the cap on the total number of instances from all pools combined.
+     * 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.
+     *
+     * @param maxTotal The cap on the total number of instances across pools.
+     * Use a negative value for no limit.
+     * @see #getMaxTotal
      */
     public synchronized void setMaxTotalPerKey(int maxTotalPerKey) {
         this.maxTotalPerKey = maxTotalPerKey;
@@ -266,14 +281,26 @@ public class GenericKeyedObjectPool<K,V>
     }
 
     /**
-     * {@inheritDoc}
+     * Returns the overall maximum number of objects (across pools) that can
+     * exist at one time. A negative value indicates no limit.
+     * @return the maximum number of instances in circulation at one time.
+     * @see #setMaxTotal
      */
     public synchronized int getMaxTotal() {
         return this.maxTotal;
     }
 
     /**
-     * {@inheritDoc}
+     * Sets the cap on the total number of instances from all pools combined.
+     * 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.
+     *
+     * @param maxTotal The cap on the total number of instances across pools.
+     * Use a negative value for no limit.
+     * @see #getMaxTotal
      */
     public synchronized void setMaxTotal(int maxTotal) {
         this.maxTotal = maxTotal;
@@ -281,14 +308,25 @@ public class GenericKeyedObjectPool<K,V>
     }
 
     /**
-     * {@inheritDoc}
+     * Returns the action to take when the {@link #borrowObject} method
+     * is invoked when the pool is exhausted (the maximum number
+     * of "active" objects has been reached).
+     *
+     * @return one of {@link WhenExhaustedAction#BLOCK},
+     * {@link WhenExhaustedAction#FAIL} or {@link WhenExhaustedAction#GROW}
+     * @see #setWhenExhaustedAction
      */
     public synchronized WhenExhaustedAction getWhenExhaustedAction() {
         return this.whenExhaustedAction;
     }
 
     /**
-     * {@inheritDoc}
+     * Sets the action to take when the {@link #borrowObject} method
+     * is invoked when the pool is exhausted (the maximum number
+     * of "active" objects has been reached).
+     *
+     * @param whenExhaustedAction the action code
+     * @see #getWhenExhaustedAction
      */
     public synchronized void setWhenExhaustedAction(WhenExhaustedAction whenExhaustedAction) {
         this.whenExhaustedAction = whenExhaustedAction;
@@ -297,28 +335,70 @@ public class GenericKeyedObjectPool<K,V>
 
 
     /**
-     * {@inheritDoc}
+     * Returns the maximum amount of time (in milliseconds) the
+     * {@link #borrowObject} method should block before throwing
+     * an exception when the pool is exhausted and the
+     * {@link #setWhenExhaustedAction "when exhausted" action} is
+     * {@link WhenExhaustedAction#BLOCK}.
+     *
+     * When less than or equal to 0, the {@link #borrowObject} method
+     * may block indefinitely.
+     *
+     * @return the maximum number of milliseconds borrowObject will block.
+     * @see #setMaxWait
+     * @see #setWhenExhaustedAction
+     * @see WhenExhaustedAction#BLOCK
      */
     public synchronized long getMaxWait() {
         return this.maxWait;
     }
 
     /**
-     * {@inheritDoc}
+     * Sets the maximum amount of time (in milliseconds) the
+     * {@link #borrowObject} method should block before throwing
+     * an exception when the pool is exhausted and the
+     * {@link #setWhenExhaustedAction "when exhausted" action} is
+     * {@link WhenExhaustedAction#BLOCK}.
+     *
+     * When less than or equal to 0, the {@link #borrowObject} method
+     * may block indefinitely.
+     *
+     * @param maxWait the maximum number of milliseconds borrowObject will block or negative for indefinitely.
+     * @see #getMaxWait
+     * @see #setWhenExhaustedAction
+     * @see WhenExhaustedAction#BLOCK
      */
     public synchronized void setMaxWait(long maxWait) {
         this.maxWait = maxWait;
     }
 
     /**
-     * {@inheritDoc}
+     * Returns the cap on the number of "idle" instances per key.
+     * @return the maximum number of "idle" instances that can be held
+     * in a given keyed pool.
+     * @see #setMaxIdle
+     *
+     * @since 2.0
      */
     public synchronized int getMaxIdlePerKey() {
         return this.maxIdlePerKey;
     }
 
     /**
-     * {@inheritDoc}
+     * Sets the cap on the number of "idle" instances 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.
+     * @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 #getMaxIdle
+     * @see #DEFAULT_MAX_IDLE_PER_KEY
+     *
+     * @since 2.0
      */
     public synchronized void setMaxIdlePerKey(int maxIdlePerKey) {
         this.maxIdlePerKey = maxIdlePerKey;
@@ -326,56 +406,115 @@ public class GenericKeyedObjectPool<K,V>
     }
 
     /**
-     * {@inheritDoc}
+     * 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.
+     * @param minIdlePerKey - The minimum size of the each keyed pool
+     * @since Pool 1.3
+     * @see #getMinIdle
+     * @see #setTimeBetweenEvictionRunsMillis
+     *
+     * @since 2.0
      */
     public synchronized void setMinIdle(int minIdlePerKey) {
         this.minIdlePerKey = minIdlePerKey;
     }
 
     /**
-     * {@inheritDoc}
+     * 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.
+     * @return minimum size of the each keyed pool
+     * @since Pool 1.3
+     * @see #setTimeBetweenEvictionRunsMillis
+     *
+     * @since 2.0
      */
     public synchronized int getMinIdlePerKey() {
         return this.minIdlePerKey;
     }
 
     /**
-     * {@inheritDoc}
+     * When <code>true</code>, objects will be
+     * {@link org.apache.commons.pool2.PoolableObjectFactory#validateObject validated}
+     * before being returned by the {@link #borrowObject}
+     * method.  If the object fails to validate,
+     * it will be dropped from the pool, and we will attempt
+     * to borrow another.
+     *
+     * @return <code>true</code> if objects are validated before being borrowed.
+     * @see #setTestOnBorrow
      */
     public synchronized boolean getTestOnBorrow() {
         return this.testOnBorrow;
     }
 
     /**
-     * {@inheritDoc}
+     * When <code>true</code>, objects will be
+     * {@link org.apache.commons.pool2.PoolableObjectFactory#validateObject validated}
+     * before being returned by the {@link #borrowObject}
+     * method.  If the object fails to validate,
+     * it will be dropped from the pool, and we will attempt
+     * to borrow another.
+     *
+     * @param testOnBorrow whether object should be validated before being returned by borrowObject.
+     * @see #getTestOnBorrow
      */
     public synchronized void setTestOnBorrow(boolean testOnBorrow) {
         this.testOnBorrow = testOnBorrow;
     }
 
     /**
-     * {@inheritDoc}
+     * When <code>true</code>, objects will be
+     * {@link org.apache.commons.pool2.PoolableObjectFactory#validateObject validated}
+     * before being returned to the pool within the
+     * {@link #returnObject}.
+     *
+     * @return <code>true</code> when objects will be validated before being returned.
+     * @see #setTestOnReturn
      */
     public synchronized boolean getTestOnReturn() {
         return this.testOnReturn;
     }
 
     /**
-     * {@inheritDoc}
+     * When <code>true</code>, objects will be
+     * {@link org.apache.commons.pool2.PoolableObjectFactory#validateObject validated}
+     * before being returned to the pool within the
+     * {@link #returnObject}.
+     *
+     * @param testOnReturn <code>true</code> so objects will be validated before being returned.
+     * @see #getTestOnReturn
      */
     public synchronized void setTestOnReturn(boolean testOnReturn) {
         this.testOnReturn = testOnReturn;
     }
 
     /**
-     * {@inheritDoc}
+     * Returns the number of milliseconds to sleep between runs of the
+     * idle object evictor thread.
+     * When non-positive, no idle object evictor thread will be
+     * run.
+     *
+     * @return milliseconds to sleep between evictor runs.
+     * @see #setTimeBetweenEvictionRunsMillis
      */
     public synchronized long getTimeBetweenEvictionRunsMillis() {
         return this.timeBetweenEvictionRunsMillis;
     }
 
     /**
-     * {@inheritDoc}
+     * Sets the number of milliseconds to sleep between runs of the
+     * idle object evictor thread.
+     * When non-positive, no idle object evictor thread will be
+     * run.
+     *
+     * @param timeBetweenEvictionRunsMillis milliseconds to sleep between evictor runs.
+     * @see #getTimeBetweenEvictionRunsMillis
      */
     public synchronized void setTimeBetweenEvictionRunsMillis(long timeBetweenEvictionRunsMillis) {
         this.timeBetweenEvictionRunsMillis = timeBetweenEvictionRunsMillis;
@@ -383,56 +522,116 @@ public class GenericKeyedObjectPool<K,V>
     }
 
     /**
-     * {@inheritDoc}
+     * Returns the max number of objects to examine during each run of the
+     * idle object evictor thread (if any).
+     *
+     * @return number of objects to examine each eviction run.
+     * @see #setNumTestsPerEvictionRun
+     * @see #setTimeBetweenEvictionRunsMillis
      */
     public synchronized int getNumTestsPerEvictionRun() {
         return this.numTestsPerEvictionRun;
     }
 
     /**
-     * {@inheritDoc}
+     * Sets the max 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>
+     * 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.  When the value is positive, the number of tests
+     * actually performed in each run will be the minimum of this value and the number of instances
+     * idle in the pools.
+     *
+     * @param numTestsPerEvictionRun number of objects to examine each eviction run.
+     * @see #setNumTestsPerEvictionRun
+     * @see #setTimeBetweenEvictionRunsMillis
      */
     public synchronized void setNumTestsPerEvictionRun(int numTestsPerEvictionRun) {
         this.numTestsPerEvictionRun = numTestsPerEvictionRun;
     }
 
     /**
-     * {@inheritDoc}
+     * Returns the minimum amount of time an object may sit idle in the pool
+     * before it is eligible for eviction by the idle object evictor
+     * (if any).
+     *
+     * @return minimum amount of time an object may sit idle in the pool before it is eligible for eviction.
+     * @see #setMinEvictableIdleTimeMillis
+     * @see #setTimeBetweenEvictionRunsMillis
      */
     public synchronized long getMinEvictableIdleTimeMillis() {
         return this.minEvictableIdleTimeMillis;
     }
 
     /**
-     * {@inheritDoc}
+     * Sets the minimum amount of time an object may sit idle in the pool
+     * before it is eligible for eviction by the idle object evictor
+     * (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.
+     * @see #getMinEvictableIdleTimeMillis
+     * @see #setTimeBetweenEvictionRunsMillis
      */
     public synchronized void setMinEvictableIdleTimeMillis(long minEvictableIdleTimeMillis) {
         this.minEvictableIdleTimeMillis = minEvictableIdleTimeMillis;
     }
 
     /**
-     * {@inheritDoc}
+     * When <code>true</code>, objects will be
+     * {@link org.apache.commons.pool2.PoolableObjectFactory#validateObject validated}
+     * by the idle object evictor (if any).  If an object
+     * fails to validate, it will be dropped from the pool.
+     *
+     * @return <code>true</code> when objects are validated when borrowed.
+     * @see #setTestWhileIdle
+     * @see #setTimeBetweenEvictionRunsMillis
      */
     public synchronized boolean getTestWhileIdle() {
         return this.testWhileIdle;
     }
 
     /**
-     * {@inheritDoc}
+     * When <code>true</code>, objects will be
+     * {@link org.apache.commons.pool2.PoolableObjectFactory#validateObject validated}
+     * by the idle object evictor (if any).  If an object
+     * fails to validate, it will be dropped from the pool.
+     *
+     * @param testWhileIdle <code>true</code> so objects are validated when borrowed.
+     * @see #getTestWhileIdle
+     * @see #setTimeBetweenEvictionRunsMillis
      */
     public synchronized void setTestWhileIdle(boolean testWhileIdle) {
         this.testWhileIdle = testWhileIdle;
     }
 
     /**
-     * {@inheritDoc}
+     * Whether or not the idle object pools act as LIFO queues. True means
+     * that borrowObject returns the most recently used ("last in") idle object
+     * in a pool (if there are idle instances available).  False means that
+     * the pools behave as FIFO queues - objects are taken from idle object
+     * pools in the order that they are returned.
+     *
+     * @return <code>true</code> if the pools are configured to act as LIFO queues
+     * @since 1.4
      */
     public synchronized boolean getLifo() {
         return this.lifo;
     }
 
     /**
-     * {@inheritDoc}
+     * Sets the LIFO property of the pools. True means that borrowObject returns
+     * the most recently used ("last in") idle object in a pool (if there are
+     * idle instances available).  False means that the pools behave as FIFO
+     * queues - objects are taken from idle object pools in the order that
+     * they are returned.
+     *
+     * @param lifo the new value for the lifo property
+     * @since 1.4
      */
     public synchronized void setLifo(boolean lifo) {
         this.lifo = lifo;
@@ -872,7 +1071,9 @@ public class GenericKeyedObjectPool<K,V>
     }
 
     /**
-     * {@inheritDoc}
+     * Returns the total number of instances current borrowed from this pool but not yet returned.
+     *
+     * @return the total number of instances currently borrowed from this pool
      */
     @Override
     public synchronized int getNumActive() {
@@ -880,7 +1081,9 @@ public class GenericKeyedObjectPool<K,V>
     }
 
     /**
-     * {@inheritDoc}
+     * Returns the total number of instances currently idle in this pool.
+     *
+     * @return the total number of instances currently idle in this pool
      */
     @Override
     public synchronized int getNumIdle() {
@@ -888,7 +1091,11 @@ public class GenericKeyedObjectPool<K,V>
     }
 
     /**
-     * {@inheritDoc}
+     * Returns the number of instances currently borrowed from but not yet returned
+     * to the pool corresponding to the given <code>key</code>.
+     *
+     * @param key the key to query
+     * @return the number of instances corresponding to the given <code>key</code> currently borrowed in this pool
      */
     @Override
     public synchronized int getNumActive(K key) {
@@ -897,7 +1104,10 @@ public class GenericKeyedObjectPool<K,V>
     }
 
     /**
-     * {@inheritDoc}
+     * Returns the number of instances corresponding to the given <code>key</code> currently idle in this pool.
+     *
+     * @param key the key to query
+     * @return the number of instances corresponding to the given <code>key</code> currently idle in this pool
      */
     @Override
     public synchronized int getNumIdle(K key) {

Modified: commons/proper/pool/trunk/src/java/org/apache/commons/pool2/impl/GenericKeyedObjectPoolMBean.java
URL: http://svn.apache.org/viewvc/commons/proper/pool/trunk/src/java/org/apache/commons/pool2/impl/GenericKeyedObjectPoolMBean.java?rev=1051772&r1=1051771&r2=1051772&view=diff
==============================================================================
--- commons/proper/pool/trunk/src/java/org/apache/commons/pool2/impl/GenericKeyedObjectPoolMBean.java (original)
+++ commons/proper/pool/trunk/src/java/org/apache/commons/pool2/impl/GenericKeyedObjectPoolMBean.java Wed Dec 22 06:56:04 2010
@@ -30,8 +30,6 @@ public interface GenericKeyedObjectPoolM
      * A negative value indicates no limit.
      *
      * @return the cap on the number of active instances per key.
-     * @see #setMaxTotalPerKey
-     * @since 2.0
      */
     int getMaxTotalPerKey();
 
@@ -45,7 +43,6 @@ public interface GenericKeyedObjectPoolM
      *
      * @param maxTotal The cap on the total number of instances across pools.
      * Use a negative value for no limit.
-     * @see #getMaxTotal
      */
     void setMaxTotalPerKey(int maxTotalPerKey);
 
@@ -53,7 +50,6 @@ public interface GenericKeyedObjectPoolM
      * Returns the overall maximum number of objects (across pools) that can
      * exist at one time. A negative value indicates no limit.
      * @return the maximum number of instances in circulation at one time.
-     * @see #setMaxTotal
      */
     int getMaxTotal();
 
@@ -67,7 +63,6 @@ public interface GenericKeyedObjectPoolM
      *
      * @param maxTotal The cap on the total number of instances across pools.
      * Use a negative value for no limit.
-     * @see #getMaxTotal
      */
     void setMaxTotal(int maxTotal);
 
@@ -78,7 +73,6 @@ public interface GenericKeyedObjectPoolM
      *
      * @return one of {@link WhenExhaustedAction#BLOCK},
      * {@link WhenExhaustedAction#FAIL} or {@link WhenExhaustedAction#GROW}
-     * @see #setWhenExhaustedAction
      */
     WhenExhaustedAction getWhenExhaustedAction();
 
@@ -88,7 +82,6 @@ public interface GenericKeyedObjectPoolM
      * of "active" objects has been reached).
      *
      * @param whenExhaustedAction the action code
-     * @see #getWhenExhaustedAction
      */
     void setWhenExhaustedAction(WhenExhaustedAction whenExhaustedAction);
 
@@ -103,9 +96,6 @@ public interface GenericKeyedObjectPoolM
      * may block indefinitely.
      *
      * @return the maximum number of milliseconds borrowObject will block.
-     * @see #setMaxWait
-     * @see #setWhenExhaustedAction
-     * @see WhenExhaustedAction#BLOCK
      */
     long getMaxWait();
 
@@ -120,19 +110,14 @@ public interface GenericKeyedObjectPoolM
      * may block indefinitely.
      *
      * @param maxWait the maximum number of milliseconds borrowObject will block or negative for indefinitely.
-     * @see #getMaxWait
-     * @see #setWhenExhaustedAction
-     * @see WhenExhaustedAction#BLOCK
      */
     void setMaxWait(long maxWait);
 
     /**
      * Returns the cap on the number of "idle" instances per key.
+     *
      * @return the maximum number of "idle" instances that can be held
      * in a given keyed pool.
-     * @see #setMaxIdle
-     *
-     * @since 2.0
      */
     int getMaxIdlePerKey();
 
@@ -145,12 +130,9 @@ public interface GenericKeyedObjectPoolM
      * 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 maxIdlePerKey the maximum number of "idle" instances that can be held
      * in a given keyed pool. Use a negative value for no limit.
-     * @see #getMaxIdle
-     * @see #DEFAULT_MAX_IDLE_PER_KEY
-     *
-     * @since 2.0
      */
     void setMaxIdlePerKey(int maxIdlePerKey);
 
@@ -160,12 +142,8 @@ public interface GenericKeyedObjectPoolM
      * <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.
-     * @param minIdlePerKey - The minimum size of the each keyed pool
-     * @since Pool 1.3
-     * @see #getMinIdle
-     * @see #setTimeBetweenEvictionRunsMillis
      *
-     * @since 2.0
+     * @param minIdlePerKey - The minimum size of the each keyed pool
      */
     void setMinIdle(int minIdlePerKey);
 
@@ -175,11 +153,8 @@ public interface GenericKeyedObjectPoolM
      * <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.
-     * @return minimum size of the each keyed pool
-     * @since Pool 1.3
-     * @see #setTimeBetweenEvictionRunsMillis
      *
-     * @since 2.0
+     * @return minimum size of the each keyed pool
      */
     int getMinIdlePerKey();
 
@@ -192,7 +167,6 @@ public interface GenericKeyedObjectPoolM
      * to borrow another.
      *
      * @return <code>true</code> if objects are validated before being borrowed.
-     * @see #setTestOnBorrow
      */
     boolean getTestOnBorrow();
 
@@ -205,7 +179,6 @@ public interface GenericKeyedObjectPoolM
      * to borrow another.
      *
      * @param testOnBorrow whether object should be validated before being returned by borrowObject.
-     * @see #getTestOnBorrow
      */
     void setTestOnBorrow(boolean testOnBorrow);
 
@@ -216,7 +189,6 @@ public interface GenericKeyedObjectPoolM
      * {@link #returnObject}.
      *
      * @return <code>true</code> when objects will be validated before being returned.
-     * @see #setTestOnReturn
      */
     boolean getTestOnReturn();
 
@@ -227,7 +199,6 @@ public interface GenericKeyedObjectPoolM
      * {@link #returnObject}.
      *
      * @param testOnReturn <code>true</code> so objects will be validated before being returned.
-     * @see #getTestOnReturn
      */
     void setTestOnReturn(boolean testOnReturn);
 
@@ -238,7 +209,6 @@ public interface GenericKeyedObjectPoolM
      * run.
      *
      * @return milliseconds to sleep between evictor runs.
-     * @see #setTimeBetweenEvictionRunsMillis
      */
     long getTimeBetweenEvictionRunsMillis();
 
@@ -249,7 +219,6 @@ public interface GenericKeyedObjectPoolM
      * run.
      *
      * @param timeBetweenEvictionRunsMillis milliseconds to sleep between evictor runs.
-     * @see #getTimeBetweenEvictionRunsMillis
      */
     void setTimeBetweenEvictionRunsMillis(long timeBetweenEvictionRunsMillis);
 
@@ -258,8 +227,6 @@ public interface GenericKeyedObjectPoolM
      * idle object evictor thread (if any).
      *
      * @return number of objects to examine each eviction run.
-     * @see #setNumTestsPerEvictionRun
-     * @see #setTimeBetweenEvictionRunsMillis
      */
     int getNumTestsPerEvictionRun();
 
@@ -275,8 +242,6 @@ public interface GenericKeyedObjectPoolM
      * idle in the pools.
      *
      * @param numTestsPerEvictionRun number of objects to examine each eviction run.
-     * @see #setNumTestsPerEvictionRun
-     * @see #setTimeBetweenEvictionRunsMillis
      */
     void setNumTestsPerEvictionRun(int numTestsPerEvictionRun);
 
@@ -286,8 +251,6 @@ public interface GenericKeyedObjectPoolM
      * (if any).
      *
      * @return minimum amount of time an object may sit idle in the pool before it is eligible for eviction.
-     * @see #setMinEvictableIdleTimeMillis
-     * @see #setTimeBetweenEvictionRunsMillis
      */
     long getMinEvictableIdleTimeMillis();
 
@@ -300,8 +263,6 @@ public interface GenericKeyedObjectPoolM
      *
      * @param minEvictableIdleTimeMillis minimum amount of time an object may sit idle in the pool before
      * it is eligible for eviction.
-     * @see #getMinEvictableIdleTimeMillis
-     * @see #setTimeBetweenEvictionRunsMillis
      */
     void setMinEvictableIdleTimeMillis(long minEvictableIdleTimeMillis);
 
@@ -312,8 +273,6 @@ public interface GenericKeyedObjectPoolM
      * fails to validate, it will be dropped from the pool.
      *
      * @return <code>true</code> when objects are validated when borrowed.
-     * @see #setTestWhileIdle
-     * @see #setTimeBetweenEvictionRunsMillis
      */
     boolean getTestWhileIdle();
 
@@ -324,8 +283,6 @@ public interface GenericKeyedObjectPoolM
      * fails to validate, it will be dropped from the pool.
      *
      * @param testWhileIdle <code>true</code> so objects are validated when borrowed.
-     * @see #getTestWhileIdle
-     * @see #setTimeBetweenEvictionRunsMillis
      */
     void setTestWhileIdle(boolean testWhileIdle);
 
@@ -337,7 +294,6 @@ public interface GenericKeyedObjectPoolM
      * pools in the order that they are returned.
      *
      * @return <code>true</code> if the pools are configured to act as LIFO queues
-     * @since 1.4
      */
     boolean getLifo();
 
@@ -349,7 +305,6 @@ public interface GenericKeyedObjectPoolM
      * they are returned.
      *
      * @param lifo the new value for the lifo property
-     * @since 1.4
      */
     void setLifo(boolean lifo);
 

Modified: commons/proper/pool/trunk/src/java/org/apache/commons/pool2/impl/GenericObjectPool.java
URL: http://svn.apache.org/viewvc/commons/proper/pool/trunk/src/java/org/apache/commons/pool2/impl/GenericObjectPool.java?rev=1051772&r1=1051771&r2=1051772&view=diff
==============================================================================
--- commons/proper/pool/trunk/src/java/org/apache/commons/pool2/impl/GenericObjectPool.java (original)
+++ commons/proper/pool/trunk/src/java/org/apache/commons/pool2/impl/GenericObjectPool.java Wed Dec 22 06:56:04 2010
@@ -233,14 +233,28 @@ public class GenericObjectPool<T> extend
     //--- configuration methods --------------------------------------
 
     /**
-     * {@inheritDoc}
+     * Returns the maximum number of objects that can be allocated by the pool
+     * (checked out to clients, or idle awaiting checkout) at a given time.
+     * When non-positive, there is no limit to the number of objects that can
+     * be managed by the pool at one time.
+     *
+     * @return the cap on the total number of object instances managed by the pool.
+     * @see #expected
+     * @since 2.0
      */
     public synchronized int getMaxTotal() {
         return this.maxTotal;
     }
 
     /**
-     * {@inheritDoc}
+     * Sets the cap on the number of objects that can be allocated by the pool
+     * (checked out to clients, or idle awaiting checkout) at a given time. Use
+     * a negative value for no limit.
+     *
+     * @param maxTotal The cap on the total number of object instances managed by the pool.
+     * Negative values mean that there is no limit to the number of objects allocated
+     * by the pool.
+     * @see #getMaxTotal
      */
     public synchronized void setMaxTotal(int maxTotal) {
         this.maxTotal = maxTotal;
@@ -248,14 +262,26 @@ public class GenericObjectPool<T> extend
     }
 
     /**
-     * {@inheritDoc}
+     * Returns the action to take when the {@link #borrowObject} method
+     * is invoked when the pool is exhausted (the maximum number
+     * of "active" objects has been reached).
+     *
+     * @return one of {@link WhenExhaustedAction#BLOCK}, {@link WhenExhaustedAction#FAIL} or {@link WhenExhaustedAction#GROW}
+     * @see #setWhenExhaustedAction
      */
     public synchronized WhenExhaustedAction getWhenExhaustedAction() {
         return this.whenExhaustedAction;
     }
 
     /**
-     * {@inheritDoc}
+     * Sets the action to take when the {@link #borrowObject} method
+     * is invoked when the pool is exhausted (the maximum number
+     * of "active" objects has been reached).
+     *
+     * @param whenExhaustedAction the action code, which must be one of
+     *        {@link WhenExhaustedAction#BLOCK}, {@link WhenExhaustedAction#FAIL},
+     *        or {@link WhenExhaustedAction#GROW}
+     * @see #getWhenExhaustedAction
      */
     public synchronized void setWhenExhaustedAction(WhenExhaustedAction whenExhaustedAction) {
         this.whenExhaustedAction = whenExhaustedAction;
@@ -264,14 +290,38 @@ public class GenericObjectPool<T> extend
 
 
     /**
-     * {@inheritDoc}
+     * Returns the maximum amount of time (in milliseconds) the
+     * {@link #borrowObject} method should block before throwing
+     * an exception when the pool is exhausted and the
+     * {@link #setWhenExhaustedAction "when exhausted" action} is
+     * {@link WhenExhaustedAction#BLOCK}.
+     *
+     * When less than or equal to 0, the {@link #borrowObject} method
+     * may block indefinitely.
+     *
+     * @return maximum number of milliseconds to block when borrowing an object.
+     * @see #setMaxWait
+     * @see #setWhenExhaustedAction
+     * @see WhenExhaustedAction#BLOCK
      */
     public synchronized long getMaxWait() {
         return this.maxWait;
     }
 
     /**
-     * {@inheritDoc}
+     * Sets the maximum amount of time (in milliseconds) the
+     * {@link #borrowObject} method should block before throwing
+     * an exception when the pool is exhausted and the
+     * {@link #setWhenExhaustedAction "when exhausted" action} is
+     * {@link WhenExhaustedAction#BLOCK}.
+     *
+     * When less than or equal to 0, the {@link #borrowObject} method
+     * may block indefinitely.
+     *
+     * @param maxWait maximum number of milliseconds to block when borrowing an object.
+     * @see #getMaxWait
+     * @see #setWhenExhaustedAction
+     * @see WhenExhaustedAction#BLOCK
      */
     public synchronized void setMaxWait(long maxWait) {
         this.maxWait = maxWait;
@@ -279,14 +329,26 @@ public class GenericObjectPool<T> extend
     }
 
     /**
-     * {@inheritDoc}
+     * Returns the cap on the number of "idle" instances in the pool.
+     * @return the cap on the number of "idle" instances in the pool.
+     * @see #setMaxIdle
      */
     public synchronized int getMaxIdle() {
         return this.maxIdle;
     }
 
     /**
-     * {@inheritDoc}
+     * Sets the cap on the number of "idle" instances 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.
+     * @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.
+     * @see #getMaxIdle
      */
     public synchronized void setMaxIdle(int maxIdle) {
         this.maxIdle = maxIdle;
@@ -294,7 +356,16 @@ public class GenericObjectPool<T> extend
     }
 
     /**
-     * {@inheritDoc}
+     * Sets the minimum number of objects allowed in the pool
+     * before the evictor thread (if active) spawns new objects.
+     * 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) {
         this.minIdle = minIdle;
@@ -302,49 +373,94 @@ public class GenericObjectPool<T> extend
     }
 
     /**
-     * {@inheritDoc}
+     * Returns 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)
+     *
+     * @return The minimum number of objects.
+     * @see #setMinIdle
      */
     public synchronized int getMinIdle() {
         return this.minIdle;
     }
 
     /**
-     * {@inheritDoc}
+     * When <tt>true</tt>, objects will be
+     * {@link PoolableObjectFactory#validateObject validated}
+     * before being returned by the {@link #borrowObject}
+     * method.  If the object fails to validate,
+     * it will be dropped from the pool, and we will attempt
+     * to borrow another.
+     *
+     * @return <code>true</code> if objects are validated before being borrowed.
+     * @see #setTestOnBorrow
      */
     public synchronized boolean getTestOnBorrow() {
         return this.testOnBorrow;
     }
 
     /**
-     * {@inheritDoc}
+     * When <tt>true</tt>, objects will be
+     * {@link PoolableObjectFactory#validateObject validated}
+     * before being returned by the {@link #borrowObject}
+     * method.  If the object fails to validate,
+     * it will be dropped from the pool, and we will attempt
+     * to borrow another.
+     *
+     * @param testOnBorrow <code>true</code> if objects should be validated before being borrowed.
+     * @see #getTestOnBorrow
      */
     public synchronized void setTestOnBorrow(boolean testOnBorrow) {
         this.testOnBorrow = testOnBorrow;
     }
 
     /**
-     * {@inheritDoc}
+     * When <tt>true</tt>, objects will be
+     * {@link PoolableObjectFactory#validateObject validated}
+     * before being returned to the pool within the
+     * {@link #returnObject}.
+     *
+     * @return <code>true</code> when objects will be validated after returned to {@link #returnObject}.
+     * @see #setTestOnReturn
      */
     public synchronized boolean getTestOnReturn() {
         return this.testOnReturn;
     }
 
     /**
-     * {@inheritDoc}
+     * When <tt>true</tt>, objects will be
+     * {@link PoolableObjectFactory#validateObject validated}
+     * before being returned to the pool within the
+     * {@link #returnObject}.
+     *
+     * @param testOnReturn <code>true</code> so objects will be validated after returned to {@link #returnObject}.
+     * @see #getTestOnReturn
      */
     public synchronized void setTestOnReturn(boolean testOnReturn) {
         this.testOnReturn = testOnReturn;
     }
 
     /**
-     * {@inheritDoc}
+     * Returns the number of milliseconds to sleep between runs of the
+     * idle object evictor thread.
+     * When non-positive, no idle object evictor thread will be
+     * run.
+     *
+     * @return number of milliseconds to sleep between evictor runs.
+     * @see #setTimeBetweenEvictionRunsMillis
      */
     public synchronized long getTimeBetweenEvictionRunsMillis() {
         return this.timeBetweenEvictionRunsMillis;
     }
 
     /**
-     * {@inheritDoc}
+     * Sets the number of milliseconds to sleep between runs of the
+     * idle object evictor thread.
+     * When non-positive, no idle object evictor thread will be
+     * run.
+     *
+     * @param timeBetweenEvictionRunsMillis number of milliseconds to sleep between evictor runs.
+     * @see #getTimeBetweenEvictionRunsMillis
      */
     public synchronized void setTimeBetweenEvictionRunsMillis(long timeBetweenEvictionRunsMillis) {
         this.timeBetweenEvictionRunsMillis = timeBetweenEvictionRunsMillis;
@@ -352,74 +468,149 @@ public class GenericObjectPool<T> extend
     }
 
     /**
-     * {@inheritDoc}
+     * Returns the max number of objects to examine during each run of the
+     * idle object evictor thread (if any).
+     *
+     * @return max number of objects to examine during each evictor run.
+     * @see #setNumTestsPerEvictionRun
+     * @see #setTimeBetweenEvictionRunsMillis
      */
     public synchronized int getNumTestsPerEvictionRun() {
         return this.numTestsPerEvictionRun;
     }
 
     /**
-     * {@inheritDoc}
+     * Sets the max number of objects to examine during each run of the
+     * idle object evictor thread (if any).
+     * <p>
+     * When a negative value is supplied, <tt>ceil({@link #getNumIdle})/abs({@link #getNumTestsPerEvictionRun})</tt>
+     * tests will be run.  That is, when the value is <i>-n</i>, roughly one <i>n</i>th of the
+     * idle objects will be tested per run. When the value is positive, the number of tests
+     * actually performed in each run will be the minimum of this value and the number of instances
+     * idle in the pool.
+     *
+     * @param numTestsPerEvictionRun max number of objects to examine during each evictor run.
+     * @see #getNumTestsPerEvictionRun
+     * @see #setTimeBetweenEvictionRunsMillis
      */
     public synchronized void setNumTestsPerEvictionRun(int numTestsPerEvictionRun) {
         this.numTestsPerEvictionRun = numTestsPerEvictionRun;
     }
 
     /**
-     * {@inheritDoc}
+     * Returns the minimum amount of time an object may sit idle in the pool
+     * before it is eligible for eviction by the idle object evictor
+     * (if any).
+     *
+     * @return minimum amount of time an object may sit idle in the pool before it is eligible for eviction.
+     * @see #setMinEvictableIdleTimeMillis
+     * @see #setTimeBetweenEvictionRunsMillis
      */
     public synchronized long getMinEvictableIdleTimeMillis() {
         return this.minEvictableIdleTimeMillis;
     }
 
     /**
-     * {@inheritDoc}
+     * Sets the minimum amount of time an object may sit idle in the pool
+     * before it is eligible for eviction by the idle object evictor
+     * (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.
+     * @see #getMinEvictableIdleTimeMillis
+     * @see #setTimeBetweenEvictionRunsMillis
      */
     public synchronized void setMinEvictableIdleTimeMillis(long minEvictableIdleTimeMillis) {
         this.minEvictableIdleTimeMillis = minEvictableIdleTimeMillis;
     }
 
     /**
-     * {@inheritDoc}
+     * Returns the minimum amount of time an object may sit idle in the pool
+     * 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.
+     *
+     * @return minimum amount of time an object may sit idle in the pool before it is eligible for eviction.
+     * @since Pool 1.3
+     * @see #setSoftMinEvictableIdleTimeMillis
      */
     public synchronized long getSoftMinEvictableIdleTimeMillis() {
         return this.softMinEvictableIdleTimeMillis;
     }
 
     /**
-     * {@inheritDoc}
+     * Sets the minimum amount of time an object may sit idle in the pool
+     * before it is eligible for eviction by the idle object evictor
+     * (if any), with the extra condition that at least
+     * "minIdle" object instances remain in the pool.
+     * 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.
+     * @since Pool 1.3
+     * @see #getSoftMinEvictableIdleTimeMillis
      */
     public synchronized void setSoftMinEvictableIdleTimeMillis(long softMinEvictableIdleTimeMillis) {
         this.softMinEvictableIdleTimeMillis = softMinEvictableIdleTimeMillis;
     }
 
     /**
-     * {@inheritDoc}
+     * When <tt>true</tt>, objects will be
+     * {@link PoolableObjectFactory#validateObject validated}
+     * by the idle object evictor (if any).  If an object
+     * fails to validate, it will be dropped from the pool.
+     *
+     * @return <code>true</code> when objects will be validated by the evictor.
+     * @see #setTestWhileIdle
+     * @see #setTimeBetweenEvictionRunsMillis
      */
     public synchronized boolean getTestWhileIdle() {
         return this.testWhileIdle;
     }
 
     /**
-     * {@inheritDoc}
+     * When <tt>true</tt>, objects will be
+     * {@link PoolableObjectFactory#validateObject validated}
+     * by the idle object evictor (if any).  If an object
+     * fails to validate, it will be dropped from the pool.
+     *
+     * @param testWhileIdle <code>true</code> so objects will be validated by the evictor.
+     * @see #getTestWhileIdle
+     * @see #setTimeBetweenEvictionRunsMillis
      */
     public synchronized void setTestWhileIdle(boolean testWhileIdle) {
         this.testWhileIdle = testWhileIdle;
     }
 
     /**
-     * {@inheritDoc}
+     * Whether or not the idle object pool acts as a LIFO queue. True means
+     * that borrowObject returns the most recently used ("last in") idle object
+     * in the pool (if there are idle instances available).  False means that
+     * the pool behaves as a FIFO queue - objects are taken from the idle object
+     * pool in the order that they are returned to the pool.
+     *
+     * @return <code>true</true> if the pool is configured to act as a LIFO queue
+     * @since 1.4
      */
     public synchronized boolean getLifo() {
         return this.lifo;
     }
 
-    /**
-     * {@inheritDoc}
-     */
-    public synchronized void setLifo(boolean lifo) {
-        this.lifo = lifo;
-    }
+     /**
+      * Sets the LIFO property of the pool. True means that borrowObject returns
+      * the most recently used ("last in") idle object in the pool (if there are
+      * idle instances available).  False means that the pool behaves as a FIFO
+      * queue - objects are taken from the idle object pool in the order that
+      * they are returned to the pool.
+      *
+      * @param lifo the new value for the LIFO property
+      * @since 1.4
+      */
+     public synchronized void setLifo(boolean lifo) {
+         this.lifo = lifo;
+     }
 
     //-- ObjectPool methods ------------------------------------------
 
@@ -727,7 +918,9 @@ public class GenericObjectPool<T> extend
     }
 
     /**
-     * {@inheritDoc}
+     * Return the number of instances currently borrowed from this pool.
+     *
+     * @return the number of instances currently borrowed from this pool
      */
     @Override
     public synchronized int getNumActive() {
@@ -735,7 +928,9 @@ public class GenericObjectPool<T> extend
     }
 
     /**
-     * {@inheritDoc}
+     * Return the number of instances currently idle in this pool.
+     *
+     * @return the number of instances currently idle in this pool
      */
     @Override
     public synchronized int getNumIdle() {

Modified: commons/proper/pool/trunk/src/java/org/apache/commons/pool2/impl/GenericObjectPoolMBean.java
URL: http://svn.apache.org/viewvc/commons/proper/pool/trunk/src/java/org/apache/commons/pool2/impl/GenericObjectPoolMBean.java?rev=1051772&r1=1051771&r2=1051772&view=diff
==============================================================================
--- commons/proper/pool/trunk/src/java/org/apache/commons/pool2/impl/GenericObjectPoolMBean.java (original)
+++ commons/proper/pool/trunk/src/java/org/apache/commons/pool2/impl/GenericObjectPoolMBean.java Wed Dec 22 06:56:04 2010
@@ -33,8 +33,6 @@ public interface GenericObjectPoolMBean<
      * be managed by the pool at one time.
      *
      * @return the cap on the total number of object instances managed by the pool.
-     * @see #expected
-     * @since 2.0
      */
     int getMaxTotal();
 
@@ -46,7 +44,6 @@ public interface GenericObjectPoolMBean<
      * @param maxTotal The cap on the total number of object instances managed by the pool.
      * Negative values mean that there is no limit to the number of objects allocated
      * by the pool.
-     * @see #getMaxTotal
      */
     void setMaxTotal(int maxTotal);
 
@@ -55,8 +52,8 @@ public interface GenericObjectPoolMBean<
      * is invoked when the pool is exhausted (the maximum number
      * of "active" objects has been reached).
      *
-     * @return one of {@link WhenExhaustedAction#BLOCK}, {@link WhenExhaustedAction#FAIL} or {@link WhenExhaustedAction#GROW}
-     * @see #setWhenExhaustedAction
+     * @return one of {@link WhenExhaustedAction#BLOCK},
+     *      {@link WhenExhaustedAction#FAIL} or {@link WhenExhaustedAction#GROW}
      */
     WhenExhaustedAction getWhenExhaustedAction();
 
@@ -68,7 +65,6 @@ public interface GenericObjectPoolMBean<
      * @param whenExhaustedAction the action code, which must be one of
      *        {@link WhenExhaustedAction#BLOCK}, {@link WhenExhaustedAction#FAIL},
      *        or {@link WhenExhaustedAction#GROW}
-     * @see #getWhenExhaustedAction
      */
     void setWhenExhaustedAction(WhenExhaustedAction whenExhaustedAction);
 
@@ -83,9 +79,6 @@ public interface GenericObjectPoolMBean<
      * may block indefinitely.
      *
      * @return maximum number of milliseconds to block when borrowing an object.
-     * @see #setMaxWait
-     * @see #setWhenExhaustedAction
-     * @see WhenExhaustedAction#BLOCK
      */
     long getMaxWait();
 
@@ -100,16 +93,13 @@ public interface GenericObjectPoolMBean<
      * may block indefinitely.
      *
      * @param maxWait maximum number of milliseconds to block when borrowing an object.
-     * @see #getMaxWait
-     * @see #setWhenExhaustedAction
-     * @see WhenExhaustedAction#BLOCK
      */
     void setMaxWait(long maxWait);
 
     /**
      * Returns the cap on the number of "idle" instances in the pool.
+     *
      * @return the cap on the number of "idle" instances in the pool.
-     * @see #setMaxIdle
      */
     int getMaxIdle();
 
@@ -122,9 +112,9 @@ public interface GenericObjectPoolMBean<
      * 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 cap on the number of "idle" instances in the pool.
      * Use a negative value to indicate an unlimited number of idle instances.
-     * @see #getMaxIdle
      */
     void setMaxIdle(int maxIdle);
 
@@ -137,8 +127,6 @@ public interface GenericObjectPoolMBean<
      * (i.e. if <code>timeBetweenEvictionRunsMillis <= 0</code>).
      *
      * @param minIdle The minimum number of objects.
-     * @see #getMinIdle
-     * @see #getTimeBetweenEvictionRunsMillis()
      */
     void setMinIdle(int minIdle);
 
@@ -148,7 +136,6 @@ public interface GenericObjectPoolMBean<
      * (Note no objects are created when: numActive + numIdle >= maxActive)
      *
      * @return The minimum number of objects.
-     * @see #setMinIdle
      */
     int getMinIdle();
 
@@ -161,7 +148,6 @@ public interface GenericObjectPoolMBean<
      * to borrow another.
      *
      * @return <code>true</code> if objects are validated before being borrowed.
-     * @see #setTestOnBorrow
      */
     boolean getTestOnBorrow();
 
@@ -174,7 +160,6 @@ public interface GenericObjectPoolMBean<
      * to borrow another.
      *
      * @param testOnBorrow <code>true</code> if objects should be validated before being borrowed.
-     * @see #getTestOnBorrow
      */
     void setTestOnBorrow(boolean testOnBorrow);
 
@@ -185,7 +170,6 @@ public interface GenericObjectPoolMBean<
      * {@link #returnObject}.
      *
      * @return <code>true</code> when objects will be validated after returned to {@link #returnObject}.
-     * @see #setTestOnReturn
      */
     boolean getTestOnReturn();
 
@@ -196,7 +180,6 @@ public interface GenericObjectPoolMBean<
      * {@link #returnObject}.
      *
      * @param testOnReturn <code>true</code> so objects will be validated after returned to {@link #returnObject}.
-     * @see #getTestOnReturn
      */
     void setTestOnReturn(boolean testOnReturn);
 
@@ -207,7 +190,6 @@ public interface GenericObjectPoolMBean<
      * run.
      *
      * @return number of milliseconds to sleep between evictor runs.
-     * @see #setTimeBetweenEvictionRunsMillis
      */
     long getTimeBetweenEvictionRunsMillis();
 
@@ -218,7 +200,6 @@ public interface GenericObjectPoolMBean<
      * run.
      *
      * @param timeBetweenEvictionRunsMillis number of milliseconds to sleep between evictor runs.
-     * @see #getTimeBetweenEvictionRunsMillis
      */
     void setTimeBetweenEvictionRunsMillis(long timeBetweenEvictionRunsMillis);
 
@@ -227,8 +208,6 @@ public interface GenericObjectPoolMBean<
      * idle object evictor thread (if any).
      *
      * @return max number of objects to examine during each evictor run.
-     * @see #setNumTestsPerEvictionRun
-     * @see #setTimeBetweenEvictionRunsMillis
      */
     int getNumTestsPerEvictionRun();
 
@@ -243,8 +222,6 @@ public interface GenericObjectPoolMBean<
      * idle in the pool.
      *
      * @param numTestsPerEvictionRun max number of objects to examine during each evictor run.
-     * @see #getNumTestsPerEvictionRun
-     * @see #setTimeBetweenEvictionRunsMillis
      */
     void setNumTestsPerEvictionRun(int numTestsPerEvictionRun);
 
@@ -254,8 +231,6 @@ public interface GenericObjectPoolMBean<
      * (if any).
      *
      * @return minimum amount of time an object may sit idle in the pool before it is eligible for eviction.
-     * @see #setMinEvictableIdleTimeMillis
-     * @see #setTimeBetweenEvictionRunsMillis
      */
     long getMinEvictableIdleTimeMillis();
 
@@ -265,10 +240,9 @@ public interface GenericObjectPoolMBean<
      * (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.
-     * @see #getMinEvictableIdleTimeMillis
-     * @see #setTimeBetweenEvictionRunsMillis
      */
     void setMinEvictableIdleTimeMillis(long minEvictableIdleTimeMillis);
 
@@ -279,8 +253,6 @@ public interface GenericObjectPoolMBean<
      * "minIdle" amount of object remain in the pool.
      *
      * @return minimum amount of time an object may sit idle in the pool before it is eligible for eviction.
-     * @since Pool 1.3
-     * @see #setSoftMinEvictableIdleTimeMillis
      */
     long getSoftMinEvictableIdleTimeMillis();
 
@@ -294,8 +266,6 @@ public interface GenericObjectPoolMBean<
      *
      * @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
      */
     void setSoftMinEvictableIdleTimeMillis(long softMinEvictableIdleTimeMillis);
 
@@ -306,8 +276,6 @@ public interface GenericObjectPoolMBean<
      * fails to validate, it will be dropped from the pool.
      *
      * @return <code>true</code> when objects will be validated by the evictor.
-     * @see #setTestWhileIdle
-     * @see #setTimeBetweenEvictionRunsMillis
      */
     boolean getTestWhileIdle();
 
@@ -318,8 +286,6 @@ public interface GenericObjectPoolMBean<
      * fails to validate, it will be dropped from the pool.
      *
      * @param testWhileIdle <code>true</code> so objects will be validated by the evictor.
-     * @see #getTestWhileIdle
-     * @see #setTimeBetweenEvictionRunsMillis
      */
     void setTestWhileIdle(boolean testWhileIdle);
 
@@ -331,7 +297,6 @@ public interface GenericObjectPoolMBean<
      * pool in the order that they are returned to the pool.
      *
      * @return <code>true</true> if the pool is configured to act as a LIFO queue
-     * @since 1.4
      */
     boolean getLifo();
 
@@ -343,7 +308,6 @@ public interface GenericObjectPoolMBean<
      * they are returned to the pool.
      *
      * @param lifo the new value for the LIFO property
-     * @since 1.4
      */
     void setLifo(boolean lifo);
 

Modified: commons/proper/pool/trunk/src/java/org/apache/commons/pool2/impl/StackKeyedObjectPool.java
URL: http://svn.apache.org/viewvc/commons/proper/pool/trunk/src/java/org/apache/commons/pool2/impl/StackKeyedObjectPool.java?rev=1051772&r1=1051771&r2=1051772&view=diff
==============================================================================
--- commons/proper/pool/trunk/src/java/org/apache/commons/pool2/impl/StackKeyedObjectPool.java (original)
+++ commons/proper/pool/trunk/src/java/org/apache/commons/pool2/impl/StackKeyedObjectPool.java Wed Dec 22 06:56:04 2010
@@ -258,7 +258,9 @@ public class StackKeyedObjectPool<K,V> e
     }
 
     /**
-     * {@inheritDoc}
+     * Returns the total number of instances currently idle in this pool.
+     *
+     * @return the total number of instances currently idle in this pool
      */
     @Override
     public synchronized int getNumIdle() {
@@ -266,7 +268,9 @@ public class StackKeyedObjectPool<K,V> e
     }
 
     /**
-     * {@inheritDoc}
+     * Returns the total number of instances current borrowed from this pool but not yet returned.
+     *
+     * @return the total number of instances currently borrowed from this pool
      */
     @Override
     public synchronized int getNumActive() {
@@ -274,7 +278,11 @@ public class StackKeyedObjectPool<K,V> e
     }
 
     /**
-     * {@inheritDoc}
+     * Returns the number of instances currently borrowed from but not yet returned
+     * to the pool corresponding to the given <code>key</code>.
+     *
+     * @param key the key to query
+     * @return the number of instances corresponding to the given <code>key</code> currently borrowed in this pool
      */
     @Override
     public synchronized int getNumActive(K key) {
@@ -282,7 +290,10 @@ public class StackKeyedObjectPool<K,V> e
     }
 
     /**
-     * {@inheritDoc}
+     * Returns the number of instances corresponding to the given <code>key</code> currently idle in this pool.
+     *
+     * @param key the key to query
+     * @return the number of instances corresponding to the given <code>key</code> currently idle in this pool
      */
     @Override
     public synchronized int getNumIdle(K key) {
@@ -442,42 +453,48 @@ public class StackKeyedObjectPool<K,V> e
     }
 
     /**
-     * {@inheritDoc}
+     * @return the cap on the number of "sleeping" instances in <code>each</code> pool.
+     * @since 1.5.5
      */
     public synchronized int getMaxSleeping() {
         return this.maxSleeping;
     }
 
     /**
-     * {@inheritDoc}
+     * Sets the cap on the number of "sleeping" instances in <code>each</code> pool.
+     *
+     * @param maxSleeping
+     * @since 2.0
      */
     public synchronized void setMaxSleeping(int maxSleeping) {
         this.maxSleeping = maxSleeping;
     }
 
     /**
-     * {@inheritDoc}
+     * @return the initial capacity of each pool.
+     * @since 1.5.5
      */
     public synchronized int getInitSleepingCapacity() {
         return this.initIdleCapacity;
     }
 
     /**
-     * {@inheritDoc}
+     * @return the _totActive
      */
     public synchronized int getTotActive() {
         return _totActive;
     }
 
     /**
-     * {@inheritDoc}
+     * @return the _totIdle
      */
     public synchronized int getTotIdle() {
         return _totIdle;
     }
 
     /**
-     * {@inheritDoc}
+     * @return the _activeCount
+     * @since 1.5.5
      */
     public synchronized Map<K,Integer> getActiveCount() {
         return _activeCount;

Modified: commons/proper/pool/trunk/src/java/org/apache/commons/pool2/impl/StackKeyedObjectPoolMBean.java
URL: http://svn.apache.org/viewvc/commons/proper/pool/trunk/src/java/org/apache/commons/pool2/impl/StackKeyedObjectPoolMBean.java?rev=1051772&r1=1051771&r2=1051772&view=diff
==============================================================================
--- commons/proper/pool/trunk/src/java/org/apache/commons/pool2/impl/StackKeyedObjectPoolMBean.java (original)
+++ commons/proper/pool/trunk/src/java/org/apache/commons/pool2/impl/StackKeyedObjectPoolMBean.java Wed Dec 22 06:56:04 2010
@@ -45,7 +45,6 @@ public interface StackKeyedObjectPoolMBe
 
     /**
      * @return the initial capacity of each pool.
-     * @since 1.5.5
      */
     int getInitSleepingCapacity();
 
@@ -61,7 +60,6 @@ public interface StackKeyedObjectPoolMBe
 
     /**
      * @return the _activeCount
-     * @since 1.5.5
      */
     Map<K, Integer> getActiveCount();
 

Modified: commons/proper/pool/trunk/src/java/org/apache/commons/pool2/impl/StackObjectPool.java
URL: http://svn.apache.org/viewvc/commons/proper/pool/trunk/src/java/org/apache/commons/pool2/impl/StackObjectPool.java?rev=1051772&r1=1051771&r2=1051772&view=diff
==============================================================================
--- commons/proper/pool/trunk/src/java/org/apache/commons/pool2/impl/StackObjectPool.java (original)
+++ commons/proper/pool/trunk/src/java/org/apache/commons/pool2/impl/StackObjectPool.java Wed Dec 22 06:56:04 2010
@@ -210,7 +210,10 @@ public class StackObjectPool<T> extends 
     }
 
     /**
-     * {@inheritDoc}
+     * Return the number of instances
+     * currently idle in this pool.
+     *
+     * @return the number of instances currently idle in this pool
      */
     @Override
     public synchronized int getNumIdle() {
@@ -218,7 +221,9 @@ public class StackObjectPool<T> extends 
     }
 
     /**
-     * {@inheritDoc}
+     * Return the number of instances currently borrowed from this pool.
+     *
+     * @return the number of instances currently borrowed from this pool
      */
     @Override
     public synchronized int getNumActive() {
@@ -345,14 +350,20 @@ public class StackObjectPool<T> extends 
     }
 
     /**
-     * {@inheritDoc}
+     * Returns the maximum number of idle instances in the pool.
+     * 
+     * @return maxSleeping
+     * @since 1.5.5
      */
     public synchronized int getMaxSleeping() {
         return this.maxSleeping;
     }
 
     /**
-     * {@inheritDoc}
+     * Sets the maximum number of idle instances in the pool.
+     *
+     * @param maxSleeping
+     * @since 2.0
      */
     public synchronized void setMaxSleeping(int maxSleeping) {
         this.maxSleeping = maxSleeping;

Modified: commons/proper/pool/trunk/src/java/org/apache/commons/pool2/impl/StackObjectPoolMBean.java
URL: http://svn.apache.org/viewvc/commons/proper/pool/trunk/src/java/org/apache/commons/pool2/impl/StackObjectPoolMBean.java?rev=1051772&r1=1051771&r2=1051772&view=diff
==============================================================================
--- commons/proper/pool/trunk/src/java/org/apache/commons/pool2/impl/StackObjectPoolMBean.java (original)
+++ commons/proper/pool/trunk/src/java/org/apache/commons/pool2/impl/StackObjectPoolMBean.java Wed Dec 22 06:56:04 2010
@@ -43,7 +43,6 @@ public interface StackObjectPoolMBean {
      * Returns the maximum number of idle instances in the pool.
      * 
      * @return maxSleeping
-     * @since 1.5.5
      */
     int getMaxSleeping();
 
@@ -51,7 +50,6 @@ public interface StackObjectPoolMBean {
      * Sets the maximum number of idle instances in the pool.
      *
      * @param maxSleeping
-     * @since 2.0
      */
     void setMaxSleeping(int maxSleeping);
 



Mime
View raw message