svn commit: r791676 - in /commons/proper/pool/trunk/src/java/org/apache/commons/pool: BaseKeyedPoolableObjectFactory.java KeyedPoolableObjectFactory.java

[ps...@apache.org]

Author: psteitz
Date: Tue Jul  7 02:29:56 2009
New Revision: 791676

URL: http://svn.apache.org/viewvc?rev=791676&view=rev
Log:
Javadoc.

Modified:
    commons/proper/pool/trunk/src/java/org/apache/commons/pool/BaseKeyedPoolableObjectFactory.java
    commons/proper/pool/trunk/src/java/org/apache/commons/pool/KeyedPoolableObjectFactory.java

Modified: commons/proper/pool/trunk/src/java/org/apache/commons/pool/BaseKeyedPoolableObjectFactory.java
URL: http://svn.apache.org/viewvc/commons/proper/pool/trunk/src/java/org/apache/commons/pool/BaseKeyedPoolableObjectFactory.java?rev=791676&r1=791675&r2=791676&view=diff
==============================================================================
--- commons/proper/pool/trunk/src/java/org/apache/commons/pool/BaseKeyedPoolableObjectFactory.java (original)
+++ commons/proper/pool/trunk/src/java/org/apache/commons/pool/BaseKeyedPoolableObjectFactory.java Tue Jul  7 02:29:56 2009
@@ -21,6 +21,7 @@
  * A base implementation of <code>KeyedPoolableObjectFactory</code>.
  * <p>
  * All operations defined here are essentially no-op's.
+ * </p>
  *
  * @see KeyedPoolableObjectFactory
  *
@@ -29,28 +30,63 @@
  * @since Pool 1.0
  */
 public abstract class BaseKeyedPoolableObjectFactory implements KeyedPoolableObjectFactory {
+    /**
+     * Create an instance that can be served by the pool.
+     *
+     * @param key the key used when constructing the object
+     * @return an instance that can be served by the pool
+     */
     public abstract Object makeObject(Object key)
         throws Exception;
 
-    /** No-op. */
+    /**
+     * Destroy an instance no longer needed by the pool.
+     * <p>
+     * The default implementation is a no-op.
+     * </p>
+     *
+     * @param key the key used when selecting the instance
+     * @param obj the instance to be destroyed
+     */
     public void destroyObject(Object key, Object obj)
         throws Exception {
     }
 
     /**
-     * This implementation always returns <tt>true</tt>.
-     * @return <tt>true</tt>
-     */
+     * Ensures that the instance is safe to be returned by the pool.
+     * <p>
+     * The default implementation always returns <tt>true</tt>.
+     * </p>
+     *
+     * @param key the key used when selecting the object
+     * @param obj the instance to be validated
+     * @return always <code>true</code> in the default implementation
+     */ 
     public boolean validateObject(Object key, Object obj) {
         return true;
     }
 
-    /** No-op. */
+    /**
+     * Reinitialize an instance to be returned by the pool.
+     * <p>
+     * The default implementation is a no-op.
+     * </p>
+     *
+     * @param key the key used when selecting the object
+     * @param obj the instance to be activated
+     */
     public void activateObject(Object key, Object obj)
         throws Exception {
     }
 
-    /** No-op. */
+    /**
+     * Uninitialize an instance to be returned to the idle object pool.
+     * <p>
+     * The default implementation is a no-op.
+     * </p>
+     *
+     * @param key the key used when selecting the object
+     */
     public void passivateObject(Object key, Object obj)
         throws Exception {
     }

Modified: commons/proper/pool/trunk/src/java/org/apache/commons/pool/KeyedPoolableObjectFactory.java
URL: http://svn.apache.org/viewvc/commons/proper/pool/trunk/src/java/org/apache/commons/pool/KeyedPoolableObjectFactory.java?rev=791676&r1=791675&r2=791676&view=diff
==============================================================================
--- commons/proper/pool/trunk/src/java/org/apache/commons/pool/KeyedPoolableObjectFactory.java (original)
+++ commons/proper/pool/trunk/src/java/org/apache/commons/pool/KeyedPoolableObjectFactory.java Tue Jul  7 02:29:56 2009
@@ -74,10 +74,6 @@
 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.