Return-Path: 
 <commons-dev-return-90337-apmail-jakarta-commons-dev-archive=jakarta.apache.org@jakarta.apache.org>
Delivered-To: apmail-jakarta-commons-dev-archive@www.apache.org
Received: (qmail 80424 invoked from network); 20 Jun 2006 16:36:44 -0000
Received: from hermes.apache.org (HELO mail.apache.org) (209.237.227.199)
  by minotaur.apache.org with SMTP; 20 Jun 2006 16:36:44 -0000
Received: (qmail 69054 invoked by uid 500); 20 Jun 2006 16:36:42 -0000
Delivered-To: apmail-jakarta-commons-dev-archive@jakarta.apache.org
Received: (qmail 68646 invoked by uid 500); 20 Jun 2006 16:36:41 -0000
Mailing-List: contact commons-dev-help@jakarta.apache.org; run by ezmlm
Precedence: bulk
List-Unsubscribe: <mailto:commons-dev-unsubscribe@jakarta.apache.org>
List-Help: <mailto:commons-dev-help@jakarta.apache.org>
List-Post: <mailto:commons-dev@jakarta.apache.org>
List-Id: "Jakarta Commons Developers List" <commons-dev.jakarta.apache.org>
Reply-To: "Jakarta Commons Developers List" <commons-dev@jakarta.apache.org>
Delivered-To: mailing list commons-dev@jakarta.apache.org
Received: (qmail 68635 invoked by uid 500); 20 Jun 2006 16:36:40 -0000
Received: (qmail 68632 invoked by uid 99); 20 Jun 2006 16:36:40 -0000
Received: from asf.osuosl.org (HELO asf.osuosl.org) (140.211.166.49)
    by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 20 Jun 2006 09:36:40 -0700
X-ASF-Spam-Status: No, hits=-9.4 required=10.0
	tests=ALL_TRUSTED,NO_REAL_NAME
X-Spam-Check-By: apache.org
Received-SPF: pass (asf.osuosl.org: local policy)
Received: from [140.211.166.113] (HELO eris.apache.org) (140.211.166.113)
    by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 20 Jun 2006 09:36:38 -0700
Received: by eris.apache.org (Postfix, from userid 65534)
	id 39B551A983A; Tue, 20 Jun 2006 09:36:18 -0700 (PDT)
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Subject: svn commit: r415726 -
 /jakarta/commons/proper/pool/trunk/src/java/org/apache/commons/pool/PoolUtils.java
Date: Tue, 20 Jun 2006 16:36:17 -0000
To: commons-cvs@jakarta.apache.org
From: sandymac@apache.org
X-Mailer: svnmailer-1.0.8
Message-Id: <20060620163618.39B551A983A@eris.apache.org>
X-Virus-Checked: Checked by ClamAV on apache.org
X-Spam-Rating: minotaur.apache.org 1.6.2 0/1000/N

Author: sandymac
Date: Tue Jun 20 09:36:14 2006
New Revision: 415726

URL: http://svn.apache.org/viewvc?rev=415726&view=rev
Log:
Applied patch from POOL-81 correcting Javadoc text.
Added caution note to the synchronizedPool methods about a potential deadlock
when used with pool implementations that provide a wait behavior.

Modified:
    jakarta/commons/proper/pool/trunk/src/java/org/apache/commons/pool/PoolUtils.java

Modified: jakarta/commons/proper/pool/trunk/src/java/org/apache/commons/pool/PoolUtils.java
URL: http://svn.apache.org/viewvc/jakarta/commons/proper/pool/trunk/src/java/org/apache/commons/pool/PoolUtils.java?rev=415726&r1=415725&r2=415726&view=diff
==============================================================================
--- jakarta/commons/proper/pool/trunk/src/java/org/apache/commons/pool/PoolUtils.java (original)
+++ jakarta/commons/proper/pool/trunk/src/java/org/apache/commons/pool/PoolUtils.java Tue Jun 20 09:36:14 2006
@@ -25,7 +25,8 @@
 import java.util.TimerTask;
 
 /**
- * This class consists exclusively of static methods that operate on or return keyedPool related interfaces.
+ * This class consists exclusively of static methods that operate on or return ObjectPool
+ * or KeyedObjectPool related interfaces.
  *
  * @author Sandy McArthur
  * @version $Revision$ $Date$
@@ -124,8 +125,8 @@
      * The key is ignored.
      *
      * @param pool the {@link ObjectPool} to delegate to.
-     * @return a {@link KeyedObjectPool} that delegates to <code>keyedPool</code> ignoring the key.
-     * @throws IllegalArgumentException when <code>keyedPool</code> is <code>null</code>.
+     * @return a {@link KeyedObjectPool} that delegates to <code>pool</code> ignoring the key.
+     * @throws IllegalArgumentException when <code>pool</code> is <code>null</code>.
      * @since Pool 1.3
      */
     public static KeyedObjectPool adapt(final ObjectPool pool) throws IllegalArgumentException {
@@ -133,10 +134,10 @@
     }
 
     /**
-     * Wraps an <code>ObjectPool</code> and dynamically checks the type of objects borrowed and returned to the keyedPool.
-     * If an object is passed to the keyedPool that isn't of type <code>type</code> a {@link ClassCastException} will be thrown.
+     * Wraps an <code>ObjectPool</code> and dynamically checks the type of objects borrowed and returned to the pool.
+     * If an object is passed to the pool that isn't of type <code>type</code> a {@link ClassCastException} will be thrown.
      *
-     * @param pool the keyedPool to enforce type safety on
+     * @param pool the pool to enforce type safety on
      * @return an <code>ObjectPool</code> that will only allow objects of <code>type</code>
      * @since Pool 1.3
      */
@@ -151,11 +152,11 @@
     }
 
     /**
-     * Wraps an <code>KeyedObjectPool</code> and dynamically checks the type of objects borrowed and returned to the keyedPool.
+     * Wraps a <code>KeyedObjectPool</code> and dynamically checks the type of objects borrowed and returned to the keyedPool.
      * If an object is passed to the keyedPool that isn't of type <code>type</code> a {@link ClassCastException} will be thrown.
      *
      * @param keyedPool the keyedPool to enforce type safety on
-     * @return an <code>KeyedObjectPool</code> that will only allow objects of <code>type</code>
+     * @return a <code>KeyedObjectPool</code> that will only allow objects of <code>type</code>
      * @since Pool 1.3
      */
     public static KeyedObjectPool checkedPool(final KeyedObjectPool keyedPool, final Class type) {
@@ -169,15 +170,15 @@
     }
 
     /**
-     * Periodically check the idle object count for the keyedPool. At most one idle object will be added per period.
+     * Periodically check the idle object count for the pool. At most one idle object will be added per period.
      * If there is an exception when calling {@link ObjectPool#addObject()} then no more checks will be performed.
      *
-     * @param pool the keyedPool to check periodically.
+     * @param pool the pool to check periodically.
      * @param minIdle if the {@link ObjectPool#getNumIdle()} is less than this then add an idle object.
-     * @param period the frequency to check the number of idle objects in a keyedPool, see
+     * @param period the frequency to check the number of idle objects in a pool, see
      *      {@link Timer#schedule(TimerTask, long, long)}.
      * @return the {@link TimerTask} that will periodically check the pools idle object count.
-     * @throws IllegalArgumentException when <code>keyedPool</code> is <code>null</code> or
+     * @throws IllegalArgumentException when <code>pool</code> is <code>null</code> or
      *      when <code>minIdle</code> is negative or when <code>period</code> isn't
      *      valid for {@link Timer#schedule(TimerTask, long, long)}.
      * @since Pool 1.3
@@ -256,17 +257,17 @@
     }
 
     /**
-     * Call <code>addObject()</code> on <code>keyedPool</code> <code>count</code> number of times.
+     * Call <code>addObject()</code> on <code>pool</code> <code>count</code> number of times.
      *
-     * @param pool the keyedPool to prefill.
+     * @param pool the pool to prefill.
      * @param count the number of idle objects to add.
      * @throws Exception when {@link ObjectPool#addObject()} fails.
-     * @throws IllegalArgumentException when <code>keyedPool</code> is <code>null</code>.
+     * @throws IllegalArgumentException when <code>pool</code> is <code>null</code>.
      * @since Pool 1.3
      */
     public static void prefill(final ObjectPool pool, final int count) throws Exception, IllegalArgumentException {
         if (pool == null) {
-            throw new IllegalArgumentException("keyedPool must not be null.");
+            throw new IllegalArgumentException("pool must not be null.");
         }
         for (int i = 0; i < count; i++) {
             pool.addObject();
@@ -323,6 +324,13 @@
     /**
      * Returns a synchronized (thread-safe) ObjectPool backed by the specified ObjectPool.
      *
+     * <p><b>Note:</b>
+     * This should not be used on pool implementations that already provide proper synchronization
+     * such as the pools provided in the Commons Pool library. Wrapping a pool that
+     * {@link #wait waits} for poolable objects to be returned before allowing another one to be
+     * borrowed with another layer of synchronization will cause a deadlock.
+     * </p>
+     *
      * @param pool the ObjectPool to be "wrapped" in a synchronized ObjectPool.
      * @return a synchronized view of the specified ObjectPool.
      * @since Pool 1.3
@@ -334,6 +342,13 @@
     /**
      * Returns a synchronized (thread-safe) KeyedObjectPool backed by the specified KeyedObjectPool.
      *
+     * <p><b>Note:</b>
+     * This should not be used on pool implementations that already provide proper synchronization
+     * such as the pools provided in the Commons Pool library. Wrapping a pool that
+     * {@link #wait waits} for poolable objects to be returned before allowing another one to be
+     * borrowed with another layer of synchronization will cause a deadlock.
+     * </p>
+     *
      * @param keyedPool the KeyedObjectPool to be "wrapped" in a synchronized KeyedObjectPool.
      * @return a synchronized view of the specified KeyedObjectPool.
      * @since Pool 1.3
@@ -527,7 +542,7 @@
 
         KeyedObjectPoolAdaptor(final ObjectPool pool) throws IllegalArgumentException {
             if (pool == null) {
-                throw new IllegalArgumentException("keyedPool must not be null.");
+                throw new IllegalArgumentException("pool must not be null.");
             }
             this.pool = pool;
         }
@@ -583,7 +598,7 @@
         public String toString() {
             final StringBuffer sb = new StringBuffer();
             sb.append("KeyedObjectPoolAdaptor");
-            sb.append("{keyedPool=").append(pool);
+            sb.append("{pool=").append(pool);
             sb.append('}');
             return sb.toString();
         }
@@ -657,7 +672,7 @@
             final StringBuffer sb = new StringBuffer();
             sb.append("CheckedObjectPool");
             sb.append("{type=").append(type);
-            sb.append(", keyedPool=").append(pool);
+            sb.append(", pool=").append(pool);
             sb.append('}');
             return sb.toString();
         }
@@ -755,7 +770,7 @@
 
         ObjectPoolMinIdleTimerTask(final ObjectPool pool, final int minIdle) throws IllegalArgumentException {
             if (pool == null) {
-                throw new IllegalArgumentException("poll must not be null.");
+                throw new IllegalArgumentException("pool must not be null.");
             }
             this.pool = pool;
             this.minIdle = minIdle;
@@ -784,7 +799,7 @@
             final StringBuffer sb = new StringBuffer();
             sb.append("ObjectPoolMinIdleTimerTask");
             sb.append("{minIdle=").append(minIdle);
-            sb.append(", keyedPool=").append(pool);
+            sb.append(", pool=").append(pool);
             sb.append('}');
             return sb.toString();
         }
@@ -793,13 +808,13 @@
     private static class KeyedObjectPoolMinIdleTimerTask extends TimerTask {
         private final int minIdle;
         private final Object key;
-        private final KeyedObjectPool pool;
+        private final KeyedObjectPool keyedPool;
 
-        KeyedObjectPoolMinIdleTimerTask(final KeyedObjectPool pool, final Object key, final int minIdle) throws IllegalArgumentException {
-            if (pool == null) {
+        KeyedObjectPoolMinIdleTimerTask(final KeyedObjectPool keyedPool, final Object key, final int minIdle) throws IllegalArgumentException {
+            if (keyedPool == null) {
                 throw new IllegalArgumentException("keyedPool must not be null.");
             }
-            this.pool = pool;
+            this.keyedPool = keyedPool;
             this.key = key;
             this.minIdle = minIdle;
         }
@@ -807,8 +822,8 @@
         public void run() {
             boolean success = false;
             try {
-                if (pool.getNumIdle(key) < minIdle) {
-                    pool.addObject(key);
+                if (keyedPool.getNumIdle(key) < minIdle) {
+                    keyedPool.addObject(key);
                 }
                 success = true;
 
@@ -828,7 +843,7 @@
             sb.append("KeyedObjectPoolMinIdleTimerTask");
             sb.append("{minIdle=").append(minIdle);
             sb.append(", key=").append(key);
-            sb.append(", keyedPool=").append(pool);
+            sb.append(", keyedPool=").append(keyedPool);
             sb.append('}');
             return sb.toString();
         }
@@ -840,7 +855,7 @@
 
         SynchronizedObjectPool(final ObjectPool pool) throws IllegalArgumentException {
             if (pool == null) {
-                throw new IllegalArgumentException("keyedPool must not be null.");
+                throw new IllegalArgumentException("pool must not be null.");
             }
             this.pool = pool;
             lock = new Object();
@@ -903,7 +918,7 @@
         public String toString() {
             final StringBuffer sb = new StringBuffer();
             sb.append("SynchronizedObjectPool");
-            sb.append("{keyedPool=").append(pool);
+            sb.append("{pool=").append(pool);
             sb.append('}');
             return sb.toString();
         }



---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org