You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by ma...@apache.org on 2012/05/04 12:10:14 UTC
svn commit: r1333854 [1/2] - in
/commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2: ./ impl/
Author: markt
Date: Fri May 4 10:10:13 2012
New Revision: 1333854
URL: http://svn.apache.org/viewvc?rev=1333854&view=rev
Log:
Javadoc.
Modified:
commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/BaseKeyedPoolableObjectFactory.java
commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/BaseObjectPool.java
commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/BasePoolableObjectFactory.java
commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/KeyedObjectPool.java
commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/KeyedPoolableObjectFactory.java
commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/ObjectPool.java
commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/PoolUtils.java
commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/PoolableObjectFactory.java
commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/impl/SoftReferenceObjectPool.java
Modified: commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/BaseKeyedPoolableObjectFactory.java
URL: http://svn.apache.org/viewvc/commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/BaseKeyedPoolableObjectFactory.java?rev=1333854&r1=1333853&r2=1333854&view=diff
==============================================================================
--- commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/BaseKeyedPoolableObjectFactory.java (original)
+++ commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/BaseKeyedPoolableObjectFactory.java Fri May 4 10:10:13 2012
@@ -14,7 +14,6 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
-
package org.apache.commons.pool2;
/**
@@ -23,7 +22,7 @@ package org.apache.commons.pool2;
* All operations defined here are essentially no-op's.
* </p>
* This class is immutable, and therefore thread-safe.
- *
+ *
* @see KeyedPoolableObjectFactory
*
* @param <K> The type of keys managed by this factory.
@@ -32,7 +31,9 @@ package org.apache.commons.pool2;
* @version $Revision$
* @since Pool 1.0
*/
-public abstract class BaseKeyedPoolableObjectFactory<K,V> implements KeyedPoolableObjectFactory<K,V> {
+public abstract class BaseKeyedPoolableObjectFactory<K,V>
+ implements KeyedPoolableObjectFactory<K,V> {
+
/**
* Create an instance that can be served by the pool.
*
@@ -47,7 +48,6 @@ public abstract class BaseKeyedPoolableO
* 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
@@ -61,12 +61,11 @@ public abstract class BaseKeyedPoolableO
* 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
- */
+ */
@Override
public boolean validateObject(K key, V obj) {
return true;
@@ -76,7 +75,6 @@ public abstract class BaseKeyedPoolableO
* 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
@@ -90,7 +88,6 @@ public abstract class BaseKeyedPoolableO
* 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
* @param obj the instance to be passivated
Modified: commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/BaseObjectPool.java
URL: http://svn.apache.org/viewvc/commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/BaseObjectPool.java?rev=1333854&r1=1333853&r2=1333854&view=diff
==============================================================================
--- commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/BaseObjectPool.java (original)
+++ commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/BaseObjectPool.java Fri May 4 10:10:13 2012
@@ -14,7 +14,6 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
-
package org.apache.commons.pool2;
/**
@@ -23,7 +22,7 @@ package org.apache.commons.pool2;
* indicating it is unsupported or throw {@link UnsupportedOperationException}.
* <p>
* This class is intended to be thread-safe.
- *
+ *
* @param <T> Type of element pooled in this pool.
*
* @version $Revision$
@@ -32,8 +31,9 @@ package org.apache.commons.pool2;
public abstract class BaseObjectPool<T> implements ObjectPool<T> {
/**
* Obtains an instance from the pool.
- *
+ *
* @return an instance from the pool
+ *
* @throws Exception if an instance cannot be obtained from the pool
*/
@Override
@@ -41,52 +41,50 @@ public abstract class BaseObjectPool<T>
/**
* Returns an instance to the pool.
- *
+ *
* @param obj instance to return to the pool
*/
@Override
public abstract void returnObject(T 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}.<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>
+ * Invalidates an object from the pool.
+ * <p>
+ * By contract, <code>obj</code> <strong>must</strong> have been obtained
+ * using {@link #borrowObject borrowObject}.
+ * <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.
*
* @param obj a {@link #borrowObject borrowed} instance to be disposed.
- * @throws Exception
+ * @throws Exception
*/
@Override
public abstract void invalidateObject(T obj) throws Exception;
/**
* Not supported in this base implementation.
+ *
* @return a negative value.
- *
- * @throws UnsupportedOperationException
*/
@Override
- public int getNumIdle() throws UnsupportedOperationException {
+ public int getNumIdle() {
return -1;
}
/**
* Not supported in this base implementation.
+ *
* @return a negative value.
- *
- * @throws UnsupportedOperationException
*/
@Override
- public int getNumActive() throws UnsupportedOperationException {
+ public int getNumActive() {
return -1;
}
/**
* Not supported in this base implementation.
- *
+ *
* @throws UnsupportedOperationException
*/
@Override
@@ -95,10 +93,10 @@ public abstract class BaseObjectPool<T>
}
/**
- * Not supported in this base implementation.
- * Always throws an {@link UnsupportedOperationException},
- * subclasses should override this behavior.
- *
+ * Not supported in this base implementation.Always throws an
+ * {@link UnsupportedOperationException}, subclasses should override this
+ * behavior.
+ *
* @throws UnsupportedOperationException
*/
@Override
@@ -107,16 +105,17 @@ public abstract class BaseObjectPool<T>
}
/**
- * Close this pool.
- * This affects the behavior of <code>isClosed</code> and <code>assertOpen</code>.
+ * Close this pool. This affects the behavior of <code>isClosed</code> and
+ * <code>assertOpen</code>.
*/
@Override
- public void close() throws Exception {
+ public void close() {
closed = true;
}
/**
* Has this pool instance been closed.
+ *
* @return <code>true</code> when this pool has been closed.
*/
public final boolean isClosed() {
@@ -124,8 +123,11 @@ public abstract class BaseObjectPool<T>
}
/**
- * Throws an <code>IllegalStateException</code> when this pool has been 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 {
@@ -134,6 +136,5 @@ public abstract class BaseObjectPool<T>
}
}
- /** Whether or not the pool is closed */
private volatile boolean closed = false;
}
Modified: commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/BasePoolableObjectFactory.java
URL: http://svn.apache.org/viewvc/commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/BasePoolableObjectFactory.java?rev=1333854&r1=1333853&r2=1333854&view=diff
==============================================================================
--- commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/BasePoolableObjectFactory.java (original)
+++ commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/BasePoolableObjectFactory.java Fri May 4 10:10:13 2012
@@ -14,7 +14,6 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
-
package org.apache.commons.pool2;
/**
@@ -23,7 +22,7 @@ package org.apache.commons.pool2;
* All operations defined here are essentially no-op's.
* <p>
* This class is immutable, and therefore thread-safe
- *
+ *
* @param <T> Type of element managed in this factory.
*
* @see PoolableObjectFactory
@@ -40,7 +39,7 @@ public abstract class BasePoolableObject
/**
* No-op.
- *
+ *
* @param obj ignored
*/
@Override
@@ -49,10 +48,11 @@ public abstract class BasePoolableObject
}
/**
- * This implementation always returns <tt>true</tt>.
- *
+ * This implementation always returns <code>true</code>.
+ *
* @param obj ignored
- * @return <tt>true</tt>
+ *
+ * @return <code>true</code>
*/
@Override
public boolean validateObject(T obj) {
@@ -61,7 +61,7 @@ public abstract class BasePoolableObject
/**
* No-op.
- *
+ *
* @param obj ignored
*/
@Override
@@ -70,7 +70,7 @@ public abstract class BasePoolableObject
/**
* No-op.
- *
+ *
* @param obj ignored
*/
@Override
Modified: commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/KeyedObjectPool.java
URL: http://svn.apache.org/viewvc/commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/KeyedObjectPool.java?rev=1333854&r1=1333853&r2=1333854&view=diff
==============================================================================
--- commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/KeyedObjectPool.java (original)
+++ commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/KeyedObjectPool.java Fri May 4 10:10:13 2012
@@ -14,7 +14,6 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
-
package org.apache.commons.pool2;
import java.util.NoSuchElementException;
@@ -22,9 +21,8 @@ import java.util.NoSuchElementException;
/**
* A "keyed" pooling interface.
* <p>
- * A keyed pool pools instances of multiple types. Each
- * type may be accessed using an arbitrary key.
- * </p>
+ * A keyed pool pools instances of multiple types. Each type may be accessed
+ * using an arbitrary key.
* <p>
* Example of use:
* <pre style="border:solid thin; padding: 1ex;"
@@ -45,15 +43,14 @@ import java.util.NoSuchElementException;
* 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
* for each key (essentially creating a {@link java.util.Map Map} of
* {@link ObjectPool pools}).
- * </p>
- *
- * <p>See {@link org.apache.commons.pool2.impl.GenericKeyedObjectPool GenericKeyedObjectPool} for an implementation.</p>
+ * <p>
+ * See {@link org.apache.commons.pool2.impl.GenericKeyedObjectPool
+ * GenericKeyedObjectPool} for an implementation.
*
* @param <K> The type of keys maintained by this pool.
* @param <V> Type of element pooled in this pool.
@@ -68,148 +65,147 @@ public interface KeyedObjectPool<K,V> {
/**
* 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 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 returnObject}, {@link #invalidateObject invalidateObject}, or a related method
- * as defined in an implementation or sub-interface,
- * 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 exhaustion,
- * newer versions are encouraged to throw a {@link NoSuchElementException}.
+ * Instances returned from this method will have been either newly created
+ * with {@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 returnObject},
+ * {@link #invalidateObject invalidateObject}, or a related method as
+ * defined in an implementation or sub-interface, 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).
*
* @param key the key used to obtain the object
+ *
* @return an instance from this pool.
- * @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
+ *
+ * @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
*/
V borrowObject(K key) throws Exception, NoSuchElementException, IllegalStateException;
/**
- * 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 <code>key</code> that is equivalent to the one used to
- * borrow the instance in the first place.
+ * 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 <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 borrowed} instance to be returned.
- * @throws Exception
+ *
+ * @throws Exception
*/
void returnObject(K key, V obj) throws Exception;
/**
- * <p>Invalidates an object from the pool.</p>
- *
- * <p>By contract, <code>obj</code> <strong>must</strong> have been obtained
+ * Invalidates an object from the pool.
+ * <p>
+ * 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 <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>
+ * 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.
*
* @param key the key used to obtain the object
* @param obj a {@link #borrowObject borrowed} instance to be returned.
- * @throws Exception
+ *
+ * @throws Exception
*/
void invalidateObject(K key, V obj) throws Exception;
/**
- * Create an object using the {@link KeyedPoolableObjectFactory factory} or other
- * implementation dependent mechanism, passivate it, and then place it in the idle object pool.
- * <code>addObject</code> is useful for "pre-loading" a pool with idle objects
- * (Optional operation).
+ * Create an object using the {@link KeyedPoolableObjectFactory factory} or
+ * other implementation dependent mechanism, passivate it, and then place it
+ * in the idle object pool. <code>addObject</code> 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.
- */
- void addObject(K key) throws Exception, IllegalStateException, UnsupportedOperationException;
+ *
+ * @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.
+ */
+ void addObject(K key) throws Exception, IllegalStateException,
+ UnsupportedOperationException;
/**
- * Returns the number of instances
- * corresponding to the given <code>key</code>
- * currently idle in this pool (optional operation).
- * Returns a negative value if this information is not available.
+ * Returns the number of instances corresponding to the given
+ * <code>key</code> currently idle in this pool. Returns a negative value if
+ * this information is not available.
*
* @param key the key to query
- * @return the number of instances corresponding to the given <code>key</code> currently idle in this pool or a negative value if unsupported
- * @throws UnsupportedOperationException <strong>deprecated</strong>: when this implementation doesn't support the operation
*/
- int getNumIdle(K key) throws UnsupportedOperationException;
+ int getNumIdle(K key);
/**
- * Returns the number of instances
- * currently borrowed from but not yet returned
- * to the pool corresponding to the
- * given <code>key</code> (optional operation).
+ * Returns the number of instances currently borrowed from but not yet
+ * returned to the pool corresponding to the given <code>key</code>.
* Returns a negative value if this information is not available.
*
* @param key the key to query
- * @return the number of instances corresponding to the given <code>key</code> currently borrowed in this pool or a negative value if unsupported
- * @throws UnsupportedOperationException <strong>deprecated</strong>: when this implementation doesn't support the operation
- */
- int getNumActive(K key) throws UnsupportedOperationException;
+= */
+ int getNumActive(K key);
/**
- * Returns the total number of instances
- * currently idle in this pool (optional operation).
+ * Returns the total number of instances currently idle in this pool.
* Returns a negative value if this information is not available.
- *
- * @return the total number of instances currently idle in this pool or a negative value if unsupported
- * @throws UnsupportedOperationException <strong>deprecated</strong>: when this implementation doesn't support the operation
- */
- int getNumIdle() throws UnsupportedOperationException;
+ = */
+ int getNumIdle();
/**
- * Returns the total number of instances
- * current borrowed from this pool but not
- * yet returned (optional operation).
- * Returns a negative value if this information is not available.
- *
- * @return the total number of instances currently borrowed from this pool or a negative value if unsupported
- * @throws UnsupportedOperationException <strong>deprecated</strong>: when this implementation doesn't support the operation
+ * Returns the total number of instances current borrowed from this pool but
+ * not yet returned. Returns a negative value if this information is not
+ * available.
*/
- int getNumActive() throws UnsupportedOperationException;
+ int getNumActive();
/**
* 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
+ * @throws UnsupportedOperationException when this implementation doesn't
+ * support the operation
*/
void clear() throws Exception, UnsupportedOperationException;
/**
- * Clears the specified pool, removing all
- * pooled instances corresponding to
+ * Clears the specified pool, removing all pooled instances corresponding to
* 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
+ *
+ * @throws UnsupportedOperationException when this implementation doesn't
+ * support the operation
*/
void clear(K key) throws Exception, UnsupportedOperationException;
/**
* Close this pool, and free any resources associated with it.
* <p>
- * 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
+ * Calling {@link #addObject addObject} or
+ * {@link #borrowObject borrowObject} after invoking this method on a pool
+ * will cause them to throw an {@link IllegalStateException}.
+ * <p>
+ * Implementations should silently fail if not all resources can be freed.
*/
- void close() throws Exception;
+ void close();
}
Modified: commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/KeyedPoolableObjectFactory.java
URL: http://svn.apache.org/viewvc/commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/KeyedPoolableObjectFactory.java?rev=1333854&r1=1333853&r2=1333854&view=diff
==============================================================================
--- commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/KeyedPoolableObjectFactory.java (original)
+++ commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/KeyedPoolableObjectFactory.java Fri May 4 10:10:13 2012
@@ -14,7 +14,6 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
-
package org.apache.commons.pool2;
/**
@@ -25,19 +24,17 @@ package org.apache.commons.pool2;
* delegates to a {@link KeyedPoolableObjectFactory},
* <ol>
* <li>
- * {@link #makeObject makeObject}
- * is called whenever a new instance is needed.
+ * {@link #makeObject} is called whenever a new instance is needed.
* </li>
* <li>
- * {@link #activateObject activateObject}
- * is invoked on every instance that has been
+ * {@link #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 validateObject}
- * is invoked on {@link #activateObject activated} instances to make sure
- * they can be {@link KeyedObjectPool#borrowObject borrowed} from the pool.
+ * {@link #validateObject} is invoked on {@link #activateObject activated}
+ * instances to make sure they can be
+ * {@link KeyedObjectPool#borrowObject borrowed} from the pool.
* <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
@@ -56,13 +53,10 @@ package org.apache.commons.pool2;
* 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 <code>KeyedPoolableObjectFactory</code>
- * at a time.
- * </p>
+ * an {@link KeyedObjectPool} makes is that the same instance of an object will
+ * not be passed to more than one method of a
+ * <code>KeyedPoolableObjectFactory</code> at a time.
*
* @see KeyedObjectPool
*
@@ -77,7 +71,9 @@ public interface KeyedPoolableObjectFact
* 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.
+ *
* @throws Exception if there is a problem creating a new instance,
* this will be propagated to the code requesting an object.
*/
@@ -86,20 +82,19 @@ public interface KeyedPoolableObjectFact
/**
* 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>
+ * 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>
- * Also, an implementation must take in to consideration that
- * instances lost to the garbage collector may never be destroyed.
- * </p>
+ * Also, an implementation must take in to consideration that instances lost
+ * to the garbage collector may never be destroyed.
*
* @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
*/
@@ -107,10 +102,10 @@ public interface KeyedPoolableObjectFact
/**
* Ensures that the instance is safe to be returned by the pool.
- * 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 <code>false</code> if <code>obj</code> is not valid and should
* be dropped from the pool, <code>true</code> otherwise.
*/
@@ -121,8 +116,10 @@ public interface KeyedPoolableObjectFact
*
* @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(K key, V obj) throws Exception;
@@ -132,8 +129,10 @@ public interface KeyedPoolableObjectFact
*
* @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(K key, V obj) throws Exception;
Modified: commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/ObjectPool.java
URL: http://svn.apache.org/viewvc/commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/ObjectPool.java?rev=1333854&r1=1333853&r2=1333854&view=diff
==============================================================================
--- commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/ObjectPool.java (original)
+++ commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/ObjectPool.java Fri May 4 10:10:13 2012
@@ -14,18 +14,12 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
-
package org.apache.commons.pool2;
import java.util.NoSuchElementException;
/**
- * A pooling interface.
- * <p>
- * <code>ObjectPool</code> defines a trivially simple pooling interface. The only
- * required methods are {@link #borrowObject borrowObject}, {@link #returnObject returnObject}
- * and {@link #invalidateObject invalidateObject}.
- * </p>
+ * A pooling simple interface.
* <p>
* Example of use:
* <pre style="border:solid thin; padding: 1ex;"
@@ -49,9 +43,8 @@ import java.util.NoSuchElementException;
* } <code style="color:#00C">catch</code>(Exception e) {
* <code style="color:#0C0">// failed to borrow an object</code>
* }</pre>
- * </p>
- *
- * <p>See {@link BaseObjectPool} for a simple base implementation.</p>
+ * <p>
+ * See {@link BaseObjectPool} for a simple base implementation.
*
* @param <T> Type of element pooled in this pool.
*
@@ -65,111 +58,108 @@ public interface ObjectPool<T> {
/**
* Obtains an instance from this pool.
* <p>
- * Instances returned from this method will have been either newly created with
- * {@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 returnObject}, {@link #invalidateObject invalidateObject}, or a related method
- * as defined in an implementation or sub-interface.
- * </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}.
+ * <p>
+ * By contract, clients <strong>must</strong> return the borrowed instance
+ * using {@link #returnObject}, {@link #invalidateObject}, or a related
+ * method as defined in an implementation or sub-interface.
* <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 exhaustion,
- * newer versions are encouraged to throw a {@link NoSuchElementException}.
- * </p>
+ * is not strictly specified (although it may be specified by
+ * implementations).
*
* @return an instance from this pool.
- * @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.
- */
- T borrowObject() throws Exception, NoSuchElementException, IllegalStateException;
+ *
+ * @throws IllegalStateException
+ * after {@link #close close} has been called on this pool.
+ * @throws Exception
+ * when {@link PoolableObjectFactory#makeObject} throws an
+ * exception.
+ * @throws NoSuchElementException
+ * when the pool is exhausted and cannot or will not return
+ * another instance.
+ */
+ T borrowObject() throws Exception, NoSuchElementException,
+ IllegalStateException;
/**
- * 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.
+ * Return an instance to the pool. By contract, <code>obj</code>
+ * <strong>must</strong> have been obtained using {@link #borrowObject()} or
+ * a related method as defined in an implementation or sub-interface.
*
* @param obj a {@link #borrowObject borrowed} instance to be returned.
- * @throws Exception
+ *
+ * @throws Exception
*/
void returnObject(T 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} or a related method as defined in
- * an implementation or sub-interface.</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>
+ * Invalidates an object from the pool.
+ * <p>
+ * By contract, <code>obj</code> <strong>must</strong> have been obtained
+ * using {@link #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.
*
* @param obj a {@link #borrowObject borrowed} instance to be disposed.
+ *
* @throws Exception
*/
void invalidateObject(T obj) throws Exception;
/**
* Create an object using the {@link PoolableObjectFactory factory} or other
- * implementation dependent mechanism, passivate it, and then place it in the idle object pool.
- * <code>addObject</code> is useful for "pre-loading" a pool with idle objects.
- * (Optional operation).
- *
- * @throws Exception when {@link PoolableObjectFactory#makeObject} fails.
- * @throws IllegalStateException after {@link #close} has been called on this pool.
- * @throws UnsupportedOperationException when this pool cannot add new idle objects.
- */
- void addObject() throws Exception, IllegalStateException, UnsupportedOperationException;
-
- /**
- * Return the number of instances
- * currently idle in this pool (optional operation).
- * This may be considered an approximation of the number
- * of objects that can be {@link #borrowObject borrowed}
- * without creating any new instances.
- * Returns a negative value if this information is not available.
+ * implementation dependent mechanism, passivate it, and then place it in
+ * the idle object pool. <code>addObject</code> is useful for "pre-loading"
+ * a pool with idle objects. (Optional operation).
*
- * @return the number of instances currently idle in this pool or a negative value if unsupported
- * @throws UnsupportedOperationException <strong>deprecated</strong>: if this implementation does not support the operation
- */
- int getNumIdle() throws UnsupportedOperationException;
+ * @throws Exception
+ * when {@link PoolableObjectFactory#makeObject} fails.
+ * @throws IllegalStateException
+ * after {@link #close} has been called on this pool.
+ * @throws UnsupportedOperationException
+ * when this pool cannot add new idle objects.
+ */
+ void addObject() throws Exception, IllegalStateException,
+ UnsupportedOperationException;
/**
- * Return the number of instances
- * currently borrowed from this pool
- * (optional operation).
+ * Return the number of instances currently idle in this pool. This may be
+ * considered an approximation of the number of objects that can be
+ * {@link #borrowObject borrowed} without creating any new instances.
* Returns a negative value if this information is not available.
- *
- * @return the number of instances currently borrowed from this pool or a negative value if unsupported
- * @throws UnsupportedOperationException <strong>deprecated</strong>: if this implementation does not support the operation
*/
- int getNumActive() throws UnsupportedOperationException;
+ int getNumIdle();
+
+ /**
+ * Return the number of instances currently borrowed from this pool. Returns
+ * a negative value if this information is not available.
+= */
+ int getNumActive();
/**
- * Clears any objects sitting idle in the pool, releasing any
- * associated resources (optional operation).
- * Idle objects cleared must be {@link PoolableObjectFactory#destroyObject(Object) destroyed}.
+ * Clears any objects sitting idle in the pool, releasing any associated
+ * resources (optional operation). Idle objects cleared must be
+ * {@link PoolableObjectFactory#destroyObject(Object)}.
*
- * @throws UnsupportedOperationException if this implementation does not support the operation
+ * @throws UnsupportedOperationException
+ * if this implementation does not support the operation
*/
void clear() throws Exception, UnsupportedOperationException;
/**
* 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}.
- * </p>
- *
- * @throws Exception <strong>deprecated</strong>: implementations should silently fail if not all resources can be freed.
+ * Calling {@link #addObject} or {@link #borrowObject} after invoking this
+ * method on a pool will cause them to throw an {@link IllegalStateException}.
+ * <p>
+ * Implementations should silently fail if not all resources can be freed.
*/
- void close() throws Exception;
+ void close();
}