You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by sa...@apache.org on 2006/03/09 05:43:48 UTC
svn commit: r384428 -
/jakarta/commons/proper/pool/trunk/src/java/org/apache/commons/pool/
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