commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From sandy...@apache.org
Subject svn commit: r384428 - /jakarta/commons/proper/pool/trunk/src/java/org/apache/commons/pool/
Date Thu, 09 Mar 2006 04:43:48 GMT
Author: sandymac
Date: Wed Mar  8 20:43:46 2006
New Revision: 384428

URL: http://svn.apache.org/viewcvs?rev=384428&view=rev
Log:
Edited all JavaDocs in the pool package. 
Fixed spelling mistakes. Improved consistancy.
Updated examples. Clarified expectations. etc.

Modified:
    jakarta/commons/proper/pool/trunk/src/java/org/apache/commons/pool/BaseKeyedObjectPool.java
    jakarta/commons/proper/pool/trunk/src/java/org/apache/commons/pool/BaseKeyedPoolableObjectFactory.java
    jakarta/commons/proper/pool/trunk/src/java/org/apache/commons/pool/BaseObjectPool.java
    jakarta/commons/proper/pool/trunk/src/java/org/apache/commons/pool/BasePoolableObjectFactory.java
    jakarta/commons/proper/pool/trunk/src/java/org/apache/commons/pool/KeyedObjectPool.java
    jakarta/commons/proper/pool/trunk/src/java/org/apache/commons/pool/KeyedPoolableObjectFactory.java
    jakarta/commons/proper/pool/trunk/src/java/org/apache/commons/pool/ObjectPool.java
    jakarta/commons/proper/pool/trunk/src/java/org/apache/commons/pool/PoolableObjectFactory.java

Modified: jakarta/commons/proper/pool/trunk/src/java/org/apache/commons/pool/BaseKeyedObjectPool.java
URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/pool/trunk/src/java/org/apache/commons/pool/BaseKeyedObjectPool.java?rev=384428&r1=384427&r2=384428&view=diff
==============================================================================
--- jakarta/commons/proper/pool/trunk/src/java/org/apache/commons/pool/BaseKeyedObjectPool.java
(original)
+++ jakarta/commons/proper/pool/trunk/src/java/org/apache/commons/pool/BaseKeyedObjectPool.java
Wed Mar  8 20:43:46 2006
@@ -86,12 +86,13 @@
     }
 
     /**
-     * Does nothing this base implementation.
+     * Close this pool.
+     * This affects the behavior of <code>isClosed</code> and <code>assertOpen</code>.
      */
     public void close() throws Exception {
+        closed = true;
     }
 
-
     /**
      * Not supported in this base implementation.
      * Always throws an {@link UnsupportedOperationException},
@@ -101,4 +102,24 @@
         throw new UnsupportedOperationException();
     }
 
+    /**
+     * Has this pool instance been closed.
+     * @return <code>true</code> when this pool has been closed.
+     */
+    protected final boolean isClosed() {
+        return closed;
+    }
+
+    /**
+     * Throws an <code>IllegalStateException</code> when this pool has been closed.
+     * @throws IllegalStateException when this pool has been closed.
+     * @see #isClosed()
+     */
+    protected final void assertOpen() throws IllegalStateException {
+        if(isClosed()) {
+            throw new IllegalStateException("Pool not open");
+        }
+    }
+
+    private volatile boolean closed = false;
 }

Modified: jakarta/commons/proper/pool/trunk/src/java/org/apache/commons/pool/BaseKeyedPoolableObjectFactory.java
URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/pool/trunk/src/java/org/apache/commons/pool/BaseKeyedPoolableObjectFactory.java?rev=384428&r1=384427&r2=384428&view=diff
==============================================================================
--- jakarta/commons/proper/pool/trunk/src/java/org/apache/commons/pool/BaseKeyedPoolableObjectFactory.java
(original)
+++ jakarta/commons/proper/pool/trunk/src/java/org/apache/commons/pool/BaseKeyedPoolableObjectFactory.java
Wed Mar  8 20:43:46 2006
@@ -17,7 +17,7 @@
 package org.apache.commons.pool;
 
 /**
- * A base implemenation of {@link KeyedPoolableObjectFactory KeyedPoolableObjectFactory}.
+ * A base implementation of <code>KeyedPoolableObjectFactory</code>.
  * <p>
  * All operations defined here are essentially no-op's.
  *

Modified: jakarta/commons/proper/pool/trunk/src/java/org/apache/commons/pool/BaseObjectPool.java
URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/pool/trunk/src/java/org/apache/commons/pool/BaseObjectPool.java?rev=384428&r1=384427&r2=384428&view=diff
==============================================================================
--- jakarta/commons/proper/pool/trunk/src/java/org/apache/commons/pool/BaseObjectPool.java
(original)
+++ jakarta/commons/proper/pool/trunk/src/java/org/apache/commons/pool/BaseObjectPool.java
Wed Mar  8 20:43:46 2006
@@ -62,6 +62,10 @@
         throw new UnsupportedOperationException();
     }
 
+    /**
+     * Close this pool.
+     * This affects the behavior of <code>isClosed</code> and <code>assertOpen</code>.
+     */
     public void close() throws Exception {
         closed = true;
     }

Modified: jakarta/commons/proper/pool/trunk/src/java/org/apache/commons/pool/BasePoolableObjectFactory.java
URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/pool/trunk/src/java/org/apache/commons/pool/BasePoolableObjectFactory.java?rev=384428&r1=384427&r2=384428&view=diff
==============================================================================
--- jakarta/commons/proper/pool/trunk/src/java/org/apache/commons/pool/BasePoolableObjectFactory.java
(original)
+++ jakarta/commons/proper/pool/trunk/src/java/org/apache/commons/pool/BasePoolableObjectFactory.java
Wed Mar  8 20:43:46 2006
@@ -17,7 +17,7 @@
 package org.apache.commons.pool;
 
 /**
- * A base implemenation of {@link PoolableObjectFactory <tt>PoolableObjectFactory</tt>}.
+ * A base implementation of <code>PoolableObjectFactory</code>.
  * <p>
  * All operations defined here are essentially no-op's.
  *

Modified: jakarta/commons/proper/pool/trunk/src/java/org/apache/commons/pool/KeyedObjectPool.java
URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/pool/trunk/src/java/org/apache/commons/pool/KeyedObjectPool.java?rev=384428&r1=384427&r2=384428&view=diff
==============================================================================
--- jakarta/commons/proper/pool/trunk/src/java/org/apache/commons/pool/KeyedObjectPool.java
(original)
+++ jakarta/commons/proper/pool/trunk/src/java/org/apache/commons/pool/KeyedObjectPool.java
Wed Mar  8 20:43:46 2006
@@ -1,5 +1,5 @@
 /*
- * Copyright 1999-2004 The Apache Software Foundation.
+ * Copyright 1999-2006 The Apache Software Foundation.
  * 
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -19,28 +19,32 @@
 import java.util.NoSuchElementException;
 
 /**
- * A  "keyed" pooling interface.
+ * A "keyed" pooling interface.
  * <p>
  * A keyed pool pools instances of multiple types. Each
  * type may be accessed using an arbitrary key.
+ * </p>
  * <p>
  * Example of use:
- * <table border="1" cellspacing="0" cellpadding="3" align="center" bgcolor="#FFFFFF"><tr><td><pre>
- * Object obj = <font color="#0000CC">null</font>;
- * Object key = <font color="#CC0000">"Key"</font>;
- *
- * <font color="#0000CC">try</font> {
- *    obj = pool.borrowObject(key);
- *    <font color="#00CC00">//...use the object...</font>
- * } <font color="#0000CC">catch</font>(Exception e) {
- *    <font color="#00CC00">//...handle any exceptions...</font>
- * } <font color="#0000CC">finally</font> {
- *    <font color="#00CC00">// make sure the object is returned to the pool</font>
- *    <font color="#0000CC">if</font>(<font color="#0000CC">null</font>
!= obj) {
- *       pool.returnObject(key,obj);
- *    }
- * }</pre></td></tr></table>
+ * <pre style="border:solid thin; padding: 1ex;"
+ * > Object obj = <code style="color:#00C">null</code>;
+ * Object key = <code style="color:#C00">"Key"</code>;
  *
+ * <code style="color:#00C">try</code> {
+ *     obj = pool.borrowObject(key);
+ *     <code style="color:#0C0">//...use the object...</code>
+ * } <code style="color:#00C">catch</code>(Exception e) {
+ *     <code style="color:#0C0">// invalidate the object</code>
+ *     pool.invalidateObject(key, obj);
+ *     <code style="color:#0C0">// do not return the object to the pool twice</code>
+ *     obj = <code style="color:#00C">null</code>;
+ * } <code style="color:#00C">finally</code> {
+ *     <code style="color:#0C0">// make sure the object is returned to the pool</code>
+ *     <code style="color:#00C">if</code>(<code style="color:#00C">null</code>
!= obj) {
+ *         pool.returnObject(key, obj);
+ *     }
+ * }</pre>
+ * </p>
  * <p>
  * {@link KeyedObjectPool} implementations <i>may</i> choose to store at most
  * one instance per key value, or may choose to maintain a pool of instances
@@ -48,80 +52,83 @@
  * {@link ObjectPool pools}).
  * </p>
  *
- * @see KeyedPoolableObjectFactory
- * @see KeyedObjectPoolFactory
- * @see ObjectPool
+ * <p>See {@link BaseKeyedObjectPool} for a simple base implementation.</p>
  *
  * @author Rodney Waldhoff
+ * @author Sandy McArthur
  * @version $Revision$ $Date$
+ * @see KeyedPoolableObjectFactory
+ * @see KeyedObjectPoolFactory
+ * @see ObjectPool
+ * @see BaseKeyedObjectPool
  */
 public interface KeyedObjectPool {
     /**
-     * Obtains an instance from this pool for the specified <i>key</i>.
+     * Obtains an instance from this pool for the specified <code>key</code>.
      * <p>
      * Instances returned from this method will have been either newly created with
-     * {@link KeyedPoolableObjectFactory#makeObject} or will be a previously idle object
and
-     * have been activated with {@link KeyedPoolableObjectFactory#activateObject} and
-     * then validated with {@link KeyedPoolableObjectFactory#validateObject}.
+     * {@link KeyedPoolableObjectFactory#makeObject makeObject} or will be a previously idle
object and
+     * have been activated with {@link KeyedPoolableObjectFactory#activateObject activateObject}
and
+     * then validated with {@link KeyedPoolableObjectFactory#validateObject validateObject}.
      * <p>
      * By contract, clients <strong>must</strong> return the borrowed object
using
-     * {@link #returnObject}, {@link #invalidateObject}, or a related method
+     * {@link #returnObject returnObject}, {@link #invalidateObject invalidateObject}, or
a related method
      * as defined in an implementation or sub-interface,
-     * using a <i>key</i> that is {@link Object#equals equivalent} to the one
used to
+     * using a <code>key</code> that is {@link Object#equals equivalent} to the
one used to
      * borrow the instance in the first place.
      * <p>
      * The behaviour of this method when the pool has been exhausted
      * is not strictly specified (although it may be specified by implementations).
-     * Older versions of this method would return <code>null</code> to indicate
exhasution,
+     * Older versions of this method would return <code>null</code> to indicate
exhaustion,
      * newer versions are encouraged to throw a {@link NoSuchElementException}.
      *
      * @param key the key used to obtain the object
      * @return an instance from this pool.
-     * @throws IllegalStateException after {@link #close} has been called on this pool.
-     * @throws Exception when {@link KeyedPoolableObjectFactory#makeObject} throws an exception.
-     * @throws NoSuchElementException when the pool is exhaused and cannot or will not return
another instance.
+     * @throws IllegalStateException after {@link #close close} has been called on this pool
+     * @throws Exception when {@link KeyedPoolableObjectFactory#makeObject makeObject} throws
an exception
+     * @throws NoSuchElementException when the pool is exhausted and cannot or will not return
another instance
      */
     Object borrowObject(Object key) throws Exception, NoSuchElementException, IllegalStateException;
 
     /**
-     * Return an instance to my pool.
-     * By contract, <i>obj</i> MUST have been obtained
-     * using {@link #borrowObject(java.lang.Object) <tt>borrowObject</tt>}
+     * Return an instance to 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 
-     * using a <i>key</i> that is equivalent to the one used to
-     * borrow the <tt>Object</tt> in the first place.
+     * using a <code>key</code> that is equivalent to the one used to
+     * borrow the instance in the first place.
      *
      * @param key the key used to obtain the object
-     * @param obj a {@link #borrowObject(java.lang.Object) borrowed} instance to be returned.
+     * @param obj a {@link #borrowObject borrowed} instance to be returned.
      */
     void returnObject(Object key, Object obj) throws Exception;
 
     /**
      * Invalidates an object from the pool
-     * By contract, <i>obj</i> MUST have been obtained
+     * 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 
-     * using a <i>key</i> that is equivalent to the one used to
-     * borrow the <tt>Object</tt> in the first place.
+     * using a <code>key</code> that is equivalent to the one used to
+     * borrow the <code>Object</code> in the first place.
      * <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.
-     * If the connection should be validated before or after borrowing,
-     * then the {@link PoolableObjectFactory#validateObject} method should be
-     * used instead.
+     * </p>
      *
+     * @param key the key used to obtain the object
      * @param obj a {@link #borrowObject borrowed} instance to be returned.
      */
     void invalidateObject(Object key, Object obj) throws Exception;
 
     /**
-     * Create an object using my {@link #setFactory factory} or other
+     * Create an object using the {@link KeyedPoolableObjectFactory factory} or other
      * implementation dependent mechanism, and place it into the pool.
      * addObject() is useful for "pre-loading" a pool with idle objects.
      * (Optional operation).
      *
+     * @param key the key a new instance should be added to
      * @throws Exception when {@link KeyedPoolableObjectFactory#makeObject} fails.
      * @throws IllegalStateException after {@link #close} has been called on this pool.
      * @throws UnsupportedOperationException when this pool cannot add new idle objects.
@@ -130,13 +137,12 @@
 
     /**
      * Returns the number of instances
-     * corresponding to the given <i>key</i>
+     * corresponding to the given <code>key</code>
      * currently idle in my pool (optional operation).
-     * Returns a negative value
-     * if this information is not available.
+     * Returns a negative value if this information is not available.
      *
-     * @param key the key
-     * @return the number of instances corresponding to the given <i>key</i>
currently idle in my pool or a negative value if unsupported
+     * @param key the key to query
+     * @return the number of instances corresponding to the given <code>key</code>
currently idle in my pool or a negative value if unsupported
      * @throws UnsupportedOperationException <strong>deprecated</strong>: when
this implementation doesn't support the operation
      */
     int getNumIdle(Object key) throws UnsupportedOperationException;
@@ -144,13 +150,12 @@
     /**
      * Returns the number of instances
      * currently borrowed from but not yet returned
-     * to my pool corresponding to the
-     * given <i>key</i> (optional operation).
-     * Returns a negative value
-     * if this information is not available.
+     * to the pool corresponding to the
+     * given <code>key</code> (optional operation).
+     * Returns a negative value if this information is not available.
      *
-     * @param key the key
-     * @return the number of instances corresponding to the given <i>key</i>
currently borrowed in my pool or a negative value if unsupported
+     * @param key the key to query
+     * @return the number of instances corresponding to the given <code>key</code>
currently borrowed in my pool or a negative value if unsupported
      * @throws UnsupportedOperationException <strong>deprecated</strong>: when
this implementation doesn't support the operation
      */
     int getNumActive(Object key) throws UnsupportedOperationException;
@@ -158,8 +163,7 @@
     /**
      * Returns the total number of instances
      * currently idle in my pool (optional operation).
-     * Returns a negative value
-     * if this information is not available.
+     * Returns a negative value if this information is not available.
      *
      * @return the total number of instances currently idle in my pool or a negative value
if unsupported
      * @throws UnsupportedOperationException <strong>deprecated</strong>: when
this implementation doesn't support the operation
@@ -170,8 +174,7 @@
      * Returns the total number of instances
      * current borrowed from my pool but not
      * yet returned (optional operation).
-     * Returns a negative value
-     * if this information is not available.
+     * Returns a negative value if this information is not available.
      *
      * @return the total number of instances currently borrowed from my pool or a negative
value if unsupported
      * @throws UnsupportedOperationException <strong>deprecated</strong>: when
this implementation doesn't support the operation
@@ -179,10 +182,9 @@
     int getNumActive() throws UnsupportedOperationException;
 
     /**
-     * Clears my pool, removing all pooled instances
-     * (optional operation).
-     * Throws {@link UnsupportedOperationException}
-     * if the pool cannot be cleared.
+     * Clears the pool, removing all pooled instances (optional operation).
+     * Throws {@link UnsupportedOperationException} if the pool cannot be cleared.
+     *
      * @throws UnsupportedOperationException when this implementation doesn't support the
operation
      */
     void clear() throws Exception, UnsupportedOperationException;
@@ -190,9 +192,9 @@
     /**
      * Clears the specified pool, removing all
      * pooled instances corresponding to
-     * the given <i>key</i>  (optional operation).
-     * Throws {@link UnsupportedOperationException}
-     * if the pool cannot be cleared.
+     * the given <code>key</code> (optional operation).
+     * Throws {@link UnsupportedOperationException} if the pool cannot be cleared.
+     *
      * @param key the key to clear
      * @throws UnsupportedOperationException when this implementation doesn't support the
operation
      */
@@ -201,18 +203,22 @@
     /**
      * Close this pool, and free any resources associated with it.
      * <p>
-     * Calling {@link #addObject} or {@link #borrowObject} after invoking
-     * this method on a pool will cause them to throw an
-     * {@link IllegalStateException}.
+     * Calling {@link #addObject addObject} or {@link #borrowObject borrowObject} after invoking
+     * this method on a pool will cause them to throw an {@link IllegalStateException}.
+     * </p>
      *
-     * @throws Exception <strong>deprecated</strong>: implementations should
silently fail if not all reasources can be freed.
+     * @throws Exception <strong>deprecated</strong>: implementations should
silently fail if not all resources can be freed.
      */
     void close() throws Exception;
 
     /**
-     * Sets the {@link KeyedPoolableObjectFactory factory} I use
+     * Sets the {@link KeyedPoolableObjectFactory factory} the pool uses
      * to create new instances (optional operation).
-     * @param factory the {@link KeyedPoolableObjectFactory} I use to create new instances.
+     * Trying to change the <code>factory</code> after a pool has been used will
frequently
+     * throw an {@link UnsupportedOperationException}. It is up to the pool
+     * implementation to determine when it is acceptable to call this method.
+     *
+     * @param factory the {@link KeyedPoolableObjectFactory} used to create new instances.
      * @throws IllegalStateException when the factory cannot be set at this time
      * @throws UnsupportedOperationException when this implementation doesn't support the
operation
      */

Modified: jakarta/commons/proper/pool/trunk/src/java/org/apache/commons/pool/KeyedPoolableObjectFactory.java
URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/pool/trunk/src/java/org/apache/commons/pool/KeyedPoolableObjectFactory.java?rev=384428&r1=384427&r2=384428&view=diff
==============================================================================
--- jakarta/commons/proper/pool/trunk/src/java/org/apache/commons/pool/KeyedPoolableObjectFactory.java
(original)
+++ jakarta/commons/proper/pool/trunk/src/java/org/apache/commons/pool/KeyedPoolableObjectFactory.java
Wed Mar  8 20:43:46 2006
@@ -1,5 +1,5 @@
 /*
- * Copyright 1999-2004 The Apache Software Foundation.
+ * Copyright 1999-2006 The Apache Software Foundation.
  * 
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -24,85 +24,118 @@
  * delegates to a {@link KeyedPoolableObjectFactory},
  * <ol>
  *  <li>
- *   {@link #makeObject}
+ *   {@link #makeObject makeObject}
  *   is called whenever a new instance is needed.
  *  </li>
  *  <li>
- *   {@link #activateObject}
+ *   {@link #activateObject activateObject}
  *   is invoked on every instance that has been
  *   {@link #passivateObject passivated} before it is
  *   {@link KeyedObjectPool#borrowObject borrowed} from the pool.
  *  </li>
  *  <li>
- *   {@link #validateObject}
+ *   {@link #validateObject validateObject}
  *   is invoked on {@link #activateObject activated} instances to make sure
  *   they can be {@link KeyedObjectPool#borrowObject borrowed} from the pool.
- *   {@link #validateObject} <strong>may</strong> also be used to test an
+ *   <code>validateObject</code> <strong>may</strong> also be used
to test an
  *   instance being {@link KeyedObjectPool#returnObject returned} to the pool
  *   before it is {@link #passivateObject passivated}. It will only be invoked
- *   on an {@link #activateObject activated} instance.
+ *   on an activated instance.
  *  </li>
  *  <li>
- *   {@link #passivateObject}
+ *   {@link #passivateObject passivateObject}
  *   is invoked on every instance when it is returned to the pool.
  *  </li>
  *  <li>
- *   {@link #destroyObject}
+ *   {@link #destroyObject destroyObject}
  *   is invoked on every instance when it is being "dropped" from the
- *   pool (whether due to the response from {@link #validateObject},
+ *   pool (whether due to the response from <code>validateObject</code>,
  *   or for reasons specific to the pool implementation.) There is no
- *   guarantee that the instance being {@link #destroyObject destroyed} will
- *   be considered active or passive.
+ *   guarantee that the instance being destroyed will
+ *   be considered active, passive or in a generally consistent state.
  *  </li>
  * </ol>
- *
+ * </p>
  * <p>
  * {@link KeyedPoolableObjectFactory} must be thread-safe. The only promise
  * an {@link KeyedObjectPool} makes is that the same instance of an object will not
- * be passed to more than one method of a {@link KeyedPoolableObjectFactory}
+ * be passed to more than one method of a <code>KeyedPoolableObjectFactory</code>
  * at a time.
+ * </p>
  *
  * @see KeyedObjectPool
  * 
  * @author Rodney Waldhoff
+ * @author Sandy McArthur
  * @version $Revision$ $Date$ 
  */
 public interface KeyedPoolableObjectFactory {
     /**
      * Create an instance that can be served by the pool.
+     * Instances returned from this method should be in the
+     * same state as if they had been
+     * {@link #activateObject activated}. They will not be
+     * activated before being served by the pool.
+     *
      * @param key the key used when constructing the object
      * @return an instance that can be served by the pool.
+     * @throws Exception if there is a problem creating a new instance,
+     *    this will be propagated to the code requesting an object.
      */
     Object makeObject(Object key) throws Exception;
 
     /**
      * Destroy an instance no longer needed by the pool.
+     * <p>
+     * It is important for implementations of this method to be aware
+     * that there is no guarantee about what state <code>obj</code>
+     * will be in and the implementation should be prepared to handle
+     * unexpected errors.
+     * </p>
+     * <p>
+     * Also, an implementation must take in to consideration that
+     * instances lost to the garbage collector may never be destroyed.
+     * </p>
+     *
      * @param key the key used when selecting the instance
      * @param obj the instance to be destroyed
+     * @throws Exception should be avoided as it may be swallowed by
+     *    the pool implementation.
+     * @see #validateObject
+     * @see KeyedObjectPool#invalidateObject
      */
     void destroyObject(Object key, Object obj) throws Exception;
 
     /**
      * Ensures that the instance is safe to be returned by the pool.
-     * Returns <tt>false</tt> if this instance should be destroyed.
+     * Returns <code>false</code> if <code>obj</code> should be destroyed.
+     *
      * @param key the key used when selecting the object
      * @param obj the instance to be validated
-     * @return <tt>false</tt> if this <i>obj</i> is not valid and
should
-     *         be dropped from the pool, <tt>true</tt> otherwise.
+     * @return <code>false</code> if <code>obj</code> is not valid
and should
+     *         be dropped from the pool, <code>true</code> otherwise.
      */
     boolean validateObject(Object key, Object obj);
 
     /**
      * Reinitialize an instance to be returned by the pool.
+     *
      * @param key the key used when selecting the object
      * @param obj the instance to be activated
+     * @throws Exception if there is a problem activating <code>obj</code>,
+     *    this exception may be swallowed by the pool.
+     * @see #destroyObject
      */
     void activateObject(Object key, Object obj) throws Exception;
 
     /**
-     * Uninitialize an instance to be returned to the pool.
+     * Uninitialize an instance to be returned to the idle object pool.
+     *
      * @param key the key used when selecting the object
      * @param obj the instance to be passivated
+     * @throws Exception if there is a problem passivating <code>obj</code>,
+     *    this exception may be swallowed by the pool.
+     * @see #destroyObject
      */
     void passivateObject(Object key, Object obj) throws Exception;
 }

Modified: jakarta/commons/proper/pool/trunk/src/java/org/apache/commons/pool/ObjectPool.java
URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/pool/trunk/src/java/org/apache/commons/pool/ObjectPool.java?rev=384428&r1=384427&r2=384428&view=diff
==============================================================================
--- jakarta/commons/proper/pool/trunk/src/java/org/apache/commons/pool/ObjectPool.java (original)
+++ jakarta/commons/proper/pool/trunk/src/java/org/apache/commons/pool/ObjectPool.java Wed
Mar  8 20:43:46 2006
@@ -1,5 +1,5 @@
 /*
- * Copyright 1999-2004 The Apache Software Foundation.
+ * Copyright 1999-2006 The Apache Software Foundation.
  * 
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -22,57 +22,71 @@
  * A pooling interface.
  * <p>
  * <code>ObjectPool</code> defines a trivially simple pooling interface. The
only 
- * required methods are {@link #borrowObject borrowObject} and {@link #returnObject returnObject}.
+ * required methods are {@link #borrowObject borrowObject}, {@link #returnObject returnObject}
+ * and {@link #invalidateObject invalidateObject}.
+ * </p>
  * <p>
  * Example of use:
- * <table border="1" cellspacing="0" cellpadding="3" align="center" bgcolor="#FFFFFF"><tr><td><pre>
- * Object obj = <font color="#0000CC">null</font>;
- * 
- * <font color="#0000CC">try</font> {
- *    obj = pool.borrowObject();
- *    <font color="#00CC00">//...use the object...</font>
- * } <font color="#0000CC">catch</font>(Exception e) {
- *    <font color="#00CC00">//...handle any exceptions...</font>
- * } <font color="#0000CC">finally</font> {
- *    <font color="#00CC00">// make sure the object is returned to the pool</font>
- *    <font color="#0000CC">if</font>(<font color="#0000CC">null</font>
!= obj) {
- *       pool.returnObject(obj);
+ * <pre style="border:solid thin; padding: 1ex;"
+ * > Object obj = <code style="color:#00C">null</code>;
+ *
+ * <code style="color:#00C">try</code> {
+ *     obj = pool.borrowObject();
+ *     <code style="color:#0C0">//...use the object...</code>
+ * } <code style="color:#00C">catch</code>(Exception e) {
+ *     <code style="color:#0C0">// invalidate the object</code>
+ *     pool.invalidateObject(obj);
+ *     <code style="color:#0C0">// do not return the object to the pool twice</code>
+ *     obj = <code style="color:#00C">null</code>;
+ * } <code style="color:#00C">finally</code> {
+ *     <code style="color:#0C0">// make sure the object is returned to the pool</code>
+ *     <code style="color:#00C">if</code>(<code style="color:#00C">null</code>
!= obj) {
+ *         pool.returnObject(obj);
  *    }
- * }</pre></td></tr></table>
- * See {@link org.apache.commons.pool.BaseObjectPool BaseObjectPool} for a simple base implementation.
+ * }</pre>
+ * </p>
+ *
+ * <p>See {@link BaseObjectPool} for a simple base implementation.</p>
  *
  * @author Rodney Waldhoff
+ * @author Sandy McArthur
  * @version $Revision$ $Date$ 
- *
+ * @see PoolableObjectFactory
+ * @see ObjectPoolFactory
+ * @see KeyedObjectPool
+ * @see BaseObjectPool
  */
 public interface ObjectPool {
     /**
      * Obtains an instance from this pool.
      * <p>
      * Instances returned from this method will have been either newly created with
-     * {@link PoolableObjectFactory#makeObject} or will be a previously idle object and
-     * have been activated with {@link PoolableObjectFactory#activateObject} and
-     * then validated with {@link PoolableObjectFactory#validateObject}.
+     * {@link PoolableObjectFactory#makeObject makeObject} or will be a previously idle object
and
+     * have been activated with {@link PoolableObjectFactory#activateObject activateObject}
and
+     * then validated with {@link PoolableObjectFactory#validateObject validateObject}.
+     * </p>
      * <p>
      * By contract, clients <strong>must</strong> return the borrowed instance
using
-     * {@link #returnObject}, {@link #invalidateObject}, or a related method
+     * {@link #returnObject returnObject}, {@link #invalidateObject invalidateObject}, or
a related method
      * as defined in an implementation or sub-interface.
+     * </p>
      * <p>
      * The behaviour of this method when the pool has been exhausted
      * is not strictly specified (although it may be specified by implementations).
-     * Older versions of this method would return <code>null</code> to indicate
exhasution,
+     * Older versions of this method would return <code>null</code> to indicate
exhaustion,
      * newer versions are encouraged to throw a {@link NoSuchElementException}.
+     * </p>
      *
      * @return an instance from this pool.
-     * @throws IllegalStateException after {@link #close} has been called on this pool.
-     * @throws Exception when {@link PoolableObjectFactory#makeObject} throws an exception.
-     * @throws NoSuchElementException when the pool is exhaused and cannot or will not return
another instance.
+     * @throws IllegalStateException after {@link #close close} has been called on this pool.
+     * @throws Exception when {@link PoolableObjectFactory#makeObject makeObject} throws
an exception.
+     * @throws NoSuchElementException when the pool is exhausted and cannot or will not return
another instance.
      */
     Object borrowObject() throws Exception, NoSuchElementException, IllegalStateException;
 
     /**
-     * Return an instance to my pool.
-     * By contract, <i>obj</i> MUST have been obtained
+     * Return an instance to 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.
@@ -83,23 +97,21 @@
 
     /**
      * Invalidates an object from the pool
-     * By contract, <i>obj</i> MUST have been obtained
-     * using {@link #borrowObject() borrowObject}
+     * 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.
-     * If the connection should be validated before or after borrowing,
-     * then the {@link PoolableObjectFactory#validateObject} method should be
-     * used instead.
+     * </p>
      *
-     * @param obj a {@link #borrowObject borrowed} instance to be returned.
+     * @param obj a {@link #borrowObject borrowed} instance to be disposed.
      */
     void invalidateObject(Object obj) throws Exception;
 
     /**
-     * Create an object using my {@link #setFactory factory} or other
+     * Create an object using the {@link PoolableObjectFactory factory} or other
      * implementation dependent mechanism, and place it into the pool.
      * addObject() is useful for "pre-loading" a pool with idle objects.
      * (Optional operation).
@@ -148,16 +160,20 @@
      * Calling {@link #addObject} or {@link #borrowObject} after invoking
      * this method on a pool will cause them to throw an
      * {@link IllegalStateException}.
+     * </p>
      *
-     * @throws Exception <strong>deprecated</strong>: implementations should
silently fail if not all reasources can be freed.
+     * @throws Exception <strong>deprecated</strong>: implementations should
silently fail if not all resources can be freed.
      */
     void close() throws Exception;
 
     /**
-     * Sets the {@link PoolableObjectFactory factory} I use
-     * to create new instances (optional operation).
-     * @param factory the {@link PoolableObjectFactory} I use to create new instances.
+     * Sets the {@link PoolableObjectFactory factory} this pool uses
+     * to create new instances (optional operation). Trying to change
+     * the <code>factory</code> after a pool has been used will frequently
+     * throw an {@link UnsupportedOperationException}. It is up to the pool
+     * implementation to determine when it is acceptable to call this method.
      *
+     * @param factory the {@link PoolableObjectFactory} I use to create new instances.
      * @throws IllegalStateException when the factory cannot be set at this time
      * @throws UnsupportedOperationException if this implementation does not support the
operation
      */

Modified: jakarta/commons/proper/pool/trunk/src/java/org/apache/commons/pool/PoolableObjectFactory.java
URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/pool/trunk/src/java/org/apache/commons/pool/PoolableObjectFactory.java?rev=384428&r1=384427&r2=384428&view=diff
==============================================================================
--- jakarta/commons/proper/pool/trunk/src/java/org/apache/commons/pool/PoolableObjectFactory.java
(original)
+++ jakarta/commons/proper/pool/trunk/src/java/org/apache/commons/pool/PoolableObjectFactory.java
Wed Mar  8 20:43:46 2006
@@ -1,5 +1,5 @@
 /*
- * Copyright 1999-2004 The Apache Software Foundation.
+ * Copyright 1999-2006 The Apache Software Foundation.
  * 
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -24,80 +24,113 @@
  * delegates to a {@link PoolableObjectFactory},
  * <ol>
  *  <li>
- *   {@link #makeObject}
+ *   {@link #makeObject makeObject}
  *   is called whenever a new instance is needed.
  *  </li>
  *  <li>
- *   {@link #activateObject}
+ *   {@link #activateObject activateObject}
  *   is invoked on every instance that has been
  *   {@link #passivateObject passivated} before it is
  *   {@link ObjectPool#borrowObject borrowed} from the pool.
  *  </li>
  *  <li>
- *   {@link #validateObject}
+ *   {@link #validateObject validateObject}
  *   is invoked on {@link #activateObject activated} instances to make sure
  *   they can be {@link ObjectPool#borrowObject borrowed} from the pool.
- *   {@link #validateObject} <strong>may</strong> also be used to test an
+ *   <code>validateObject</code> <strong>may</strong> also be used
to test an
  *   instance being {@link ObjectPool#returnObject returned} to the pool
  *   before it is {@link #passivateObject passivated}. It will only be invoked
- *   on an {@link #activateObject activated} instance.
+ *   on an activated instance.
  *  </li>
  *  <li>
- *   {@link #passivateObject}
+ *   {@link #passivateObject passivateObject}
  *   is invoked on every instance when it is returned to the pool.
  *  </li>
  *  <li>
- *   {@link #destroyObject}
+ *   {@link #destroyObject destroyObject}
  *   is invoked on every instance when it is being "dropped" from the
- *   pool (whether due to the response from {@link #validateObject},
+ *   pool (whether due to the response from <code>validateObject</code>,
  *   or for reasons specific to the pool implementation.) There is no
- *   guarantee that the instance being {@link #destroyObject destroyed} will
- *   be considered active or passive.
+ *   guarantee that the instance being destroyed will
+ *   be considered active, passive or in a generally consistent state.
  *  </li>
  * </ol>
- *
+ * </p>
  * <p>
  * {@link PoolableObjectFactory} must be thread-safe. The only promise
  * an {@link ObjectPool} makes is that the same instance of an object will not
- * be passed to more than one method of a {@link PoolableObjectFactory}
+ * be passed to more than one method of a <code>PoolableObjectFactory</code>
  * at a time.
+ * </p>
  *
  * @see ObjectPool
  *
  * @author Rodney Waldhoff
+ * @author Sandy McArthur
  * @version $Revision$ $Date$ 
  */
 public interface PoolableObjectFactory {
   /**
-   * Creates an instance that can be returned by the pool.
-   * @return an instance that can be returned by the pool.
+   * Creates an instance that can be served by the pool.
+   * Instances returned from this method should be in the
+   * same state as if they had been
+   * {@link #activateObject activated}. They will not be
+   * activated before being served by the pool.
+   *
+   * @return an instance that can be served by the pool.
+   * @throws Exception if there is a problem creating a new instance,
+   *    this will be propagated to the code requesting an object.
    */
   Object makeObject() throws Exception;
 
   /**
    * Destroys an instance no longer needed by the pool.
+   * <p>
+   * It is important for implementations of this method to be aware
+   * that there is no guarantee about what state <code>obj</code>
+   * will be in and the implementation should be prepared to handle
+   * unexpected errors.
+   * </p>
+   * <p>
+   * Also, an implementation must take in to consideration that
+   * instances lost to the garbage collector may never be destroyed.
+   * </p>
+   *
    * @param obj the instance to be destroyed
+   * @throws Exception should be avoided as it may be swallowed by
+   *    the pool implementation.
+   * @see #validateObject
+   * @see ObjectPool#invalidateObject
    */
   void destroyObject(Object obj) throws Exception;
 
   /**
    * Ensures that the instance is safe to be returned by the pool.
-   * Returns <tt>false</tt> if this object should be destroyed.
+   * Returns <code>false</code> if <code>obj</code> should be destroyed.
+   *
    * @param obj the instance to be validated
-   * @return <tt>false</tt> if this <i>obj</i> is not valid and should
-   *         be dropped from the pool, <tt>true</tt> otherwise.
+   * @return <code>false</code> if <code>obj</code> is not valid
and should
+   *         be dropped from the pool, <code>true</code> otherwise.
    */
   boolean validateObject(Object obj);
 
   /**
    * Reinitialize an instance to be returned by the pool.
+   *
    * @param obj the instance to be activated
+   * @throws Exception if there is a problem activating <code>obj</code>,
+   *    this exception may be swallowed by the pool.
+   * @see #destroyObject
    */
   void activateObject(Object obj) throws Exception;
 
   /**
-   * Uninitialize an instance to be returned to the pool.
+   * Uninitialize an instance to be returned to the idle object pool.
+   *
    * @param obj the instance to be passivated
+   * @throws Exception if there is a problem passivating <code>obj</code>,
+   *    this exception may be swallowed by the pool.
+   * @see #destroyObject
    */
   void passivateObject(Object obj) throws Exception;
 }



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


Mime
View raw message