Mailing-List: contact commits-help@commons.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@commons.apache.org
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Subject: svn commit: r952050 - in
 /commons/proper/pool/trunk/src/java/org/apache/commons/pool:
 BaseKeyedObjectPool.java BaseObjectPool.java
 impl/GenericKeyedObjectPool.java impl/GenericObjectPool.java
Date: Mon, 07 Jun 2010 01:15:51 -0000
To: commits@commons.apache.org
From: psteitz@apache.org
Message-Id: <20100607011551.24B8923889B3@eris.apache.org>

Author: psteitz
Date: Mon Jun  7 01:15:50 2010
New Revision: 952050

URL: http://svn.apache.org/viewvc?rev=952050&view=rev
Log:
Javadoc only. JIRA: POOL-155.

Modified:
    commons/proper/pool/trunk/src/java/org/apache/commons/pool/BaseKeyedObjectPool.java
    commons/proper/pool/trunk/src/java/org/apache/commons/pool/BaseObjectPool.java
    commons/proper/pool/trunk/src/java/org/apache/commons/pool/impl/GenericKeyedObjectPool.java
    commons/proper/pool/trunk/src/java/org/apache/commons/pool/impl/GenericObjectPool.java

Modified: commons/proper/pool/trunk/src/java/org/apache/commons/pool/BaseKeyedObjectPool.java
URL: http://svn.apache.org/viewvc/commons/proper/pool/trunk/src/java/org/apache/commons/pool/BaseKeyedObjectPool.java?rev=952050&r1=952049&r2=952050&view=diff
==============================================================================
--- commons/proper/pool/trunk/src/java/org/apache/commons/pool/BaseKeyedObjectPool.java (original)
+++ commons/proper/pool/trunk/src/java/org/apache/commons/pool/BaseKeyedObjectPool.java Mon Jun  7 01:15:50 2010
@@ -30,6 +30,21 @@ package org.apache.commons.pool;
 public abstract class BaseKeyedObjectPool implements KeyedObjectPool {
     public abstract Object borrowObject(Object key) throws Exception;
     public abstract void returnObject(Object key, Object obj) throws Exception;
+    
+    /**
+     * <p>Invalidates an object from the pool.</p>
+     * 
+     * <p>By contract, <code>obj</code> <strong>must</strong> have been obtained
+     * using {@link #borrowObject borrowObject} using a <code>key</code> that is
+     * equivalent to the one used to borrow the <code>Object</code> in the first place.</p>
+     *
+     * <p>This method should be used when an object that has been borrowed
+     * is determined (due to an exception or other problem) to be invalid.</p>
+     *
+     * @param key the key used to obtain the object
+     * @param obj a {@link #borrowObject borrowed} instance to be returned.
+     * @throws Exception 
+     */
     public abstract void invalidateObject(Object key, Object obj) throws Exception;
 
     /**

Modified: commons/proper/pool/trunk/src/java/org/apache/commons/pool/BaseObjectPool.java
URL: http://svn.apache.org/viewvc/commons/proper/pool/trunk/src/java/org/apache/commons/pool/BaseObjectPool.java?rev=952050&r1=952049&r2=952050&view=diff
==============================================================================
--- commons/proper/pool/trunk/src/java/org/apache/commons/pool/BaseObjectPool.java (original)
+++ commons/proper/pool/trunk/src/java/org/apache/commons/pool/BaseObjectPool.java Mon Jun  7 01:15:50 2010
@@ -44,15 +44,13 @@ public abstract class BaseObjectPool imp
     public abstract void returnObject(Object obj) throws Exception;
     
     /**
-     * Invalidates an object from the pool.
-     * By contract, <code>obj</code> <strong>must</strong> have been obtained
-     * using {@link #borrowObject borrowObject}
-     * or a related method as defined in an implementation
-     * or sub-interface.
-     * <p>
-     * This method should be used when an object that has been borrowed
-     * is determined (due to an exception or other problem) to be invalid.
-     * </p>
+     * <p>Invalidates an object from the pool.</p>
+     * 
+     * <p>By contract, <code>obj</code> <strong>must</strong> have been obtained
+     * using {@link #borrowObject borrowObject}.<p>
+     * 
+     * <p>This method should be used when an object that has been borrowed
+     * is determined (due to an exception or other problem) to be invalid.</p>
      *
      * @param obj a {@link #borrowObject borrowed} instance to be disposed.
      * @throws Exception 

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=952050&r1=952049&r2=952050&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 Mon Jun  7 01:15:50 2010
@@ -34,6 +34,7 @@ import org.apache.commons.pool.BaseKeyed
 import org.apache.commons.pool.KeyedObjectPool;
 import org.apache.commons.pool.KeyedPoolableObjectFactory;
 import org.apache.commons.pool.PoolUtils;
+import org.apache.commons.pool.PoolableObjectFactory;
 
 /**
  * A configurable <code>KeyedObjectPool</code> implementation.
@@ -1323,7 +1324,7 @@ public class GenericKeyedObjectPool exte
     
     /**
      * Clears any objects sitting idle in the pool by removing them from the
-     * idle instance pool and then invoking the configured 
+     * idle instance pool and then invoking the configured PoolableObjectFactory's
      * {@link KeyedPoolableObjectFactory#destroyObject(Object, Object)} method on
      * each idle instance.
      *  
@@ -1333,7 +1334,8 @@ public class GenericKeyedObjectPool exte
      * <li>Invoking this method does not prevent objects being
      * returned to the idle instance pool, even during its execution. It locks
      * the pool only during instance removal. Additional instances may be returned
-     * while removed items are being destroyed.</li></ul></p>
+     * while removed items are being destroyed.</li>
+     * <li>Exceptions encountered destroying idle instances are swallowed.</li></ul></p>
      */
     public void clear() {
         Map toDestroy = new HashMap();
@@ -1640,8 +1642,9 @@ public class GenericKeyedObjectPool exte
     }
 
     /**
-     * <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>
+     * {@inheritDoc}
+     * <p>Activation of this method decrements the active count associated with the given keyed pool 
+     * and attempts to destroy <code>obj.</code></p>
      * 
      * @param key pool key
      * @param obj instance to invalidate

Modified: commons/proper/pool/trunk/src/java/org/apache/commons/pool/impl/GenericObjectPool.java
URL: http://svn.apache.org/viewvc/commons/proper/pool/trunk/src/java/org/apache/commons/pool/impl/GenericObjectPool.java?rev=952050&r1=952049&r2=952050&view=diff
==============================================================================
--- commons/proper/pool/trunk/src/java/org/apache/commons/pool/impl/GenericObjectPool.java (original)
+++ commons/proper/pool/trunk/src/java/org/apache/commons/pool/impl/GenericObjectPool.java Mon Jun  7 01:15:50 2010
@@ -1247,11 +1247,10 @@ public class GenericObjectPool extends B
     }
 
     /**
-     * <p>Invalidates the given object instance.  Decrements the active count
-     * and destroys the instance.</p>
+     * {@inheritDoc}
+     * <p>Activation of this method decrements the active count and attempts to destroy the instance.</p>
      * 
-     * @param obj instance to invalidate
-     * @throws Exception if an exception occurs destroying the object
+     * @throws Exception if the configured {@link PoolableObjectFactory} throws an exception destroying obj
      */
     public void invalidateObject(Object obj) throws Exception {
         try {
@@ -1278,7 +1277,8 @@ public class GenericObjectPool extends B
      * <li>Invoking this method does not prevent objects being
      * returned to the idle instance pool, even during its execution. It locks
      * the pool only during instance removal. Additional instances may be returned
-     * while removed items are being destroyed.</li></ul></p>
+     * while removed items are being destroyed.</li>
+     * <li>Exceptions encountered destroying idle instances are swallowed.</li></ul></p>
      */
     public void clear() {
         List toDestroy = new ArrayList();