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 [EMAIL PROTECTED] 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 [EMAIL PROTECTED] 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 [EMAIL PROTECTED] 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>
* [EMAIL PROTECTED] 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 @@
* [EMAIL PROTECTED] ObjectPool pools}).
* </p>
*
- * @see KeyedPoolableObjectFactory
- * @see KeyedObjectPoolFactory
- * @see ObjectPool
+ * <p>See [EMAIL PROTECTED] 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
- * [EMAIL PROTECTED] KeyedPoolableObjectFactory#makeObject} or will be a
previously idle object and
- * have been activated with [EMAIL PROTECTED]
KeyedPoolableObjectFactory#activateObject} and
- * then validated with [EMAIL PROTECTED]
KeyedPoolableObjectFactory#validateObject}.
+ * [EMAIL PROTECTED] KeyedPoolableObjectFactory#makeObject makeObject} or
will be a previously idle object and
+ * have been activated with [EMAIL PROTECTED]
KeyedPoolableObjectFactory#activateObject activateObject} and
+ * then validated with [EMAIL PROTECTED]
KeyedPoolableObjectFactory#validateObject validateObject}.
* <p>
* By contract, clients <strong>must</strong> return the borrowed object
using
- * [EMAIL PROTECTED] #returnObject}, [EMAIL PROTECTED] #invalidateObject},
or a related method
+ * [EMAIL PROTECTED] #returnObject returnObject}, [EMAIL PROTECTED]
#invalidateObject invalidateObject}, or a related method
* as defined in an implementation or sub-interface,
- * using a <i>key</i> that is [EMAIL PROTECTED] Object#equals equivalent}
to the one used to
+ * using a <code>key</code> that is [EMAIL PROTECTED] 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 [EMAIL PROTECTED]
NoSuchElementException}.
*
* @param key the key used to obtain the object
* @return an instance from this pool.
- * @throws IllegalStateException after [EMAIL PROTECTED] #close} has been
called on this pool.
- * @throws Exception when [EMAIL PROTECTED]
KeyedPoolableObjectFactory#makeObject} throws an exception.
- * @throws NoSuchElementException when the pool is exhaused and cannot or
will not return another instance.
+ * @throws IllegalStateException after [EMAIL PROTECTED] #close close} has
been called on this pool
+ * @throws Exception when [EMAIL PROTECTED]
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 [EMAIL PROTECTED] #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 [EMAIL PROTECTED] #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 [EMAIL PROTECTED] #borrowObject(java.lang.Object)
borrowed} instance to be returned.
+ * @param obj a [EMAIL PROTECTED] #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 [EMAIL PROTECTED] #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 [EMAIL PROTECTED] PoolableObjectFactory#validateObject} method
should be
- * used instead.
+ * </p>
*
+ * @param key the key used to obtain the object
* @param obj a [EMAIL PROTECTED] #borrowObject borrowed} instance to be
returned.
*/
void invalidateObject(Object key, Object obj) throws Exception;
/**
- * Create an object using my [EMAIL PROTECTED] #setFactory factory} or
other
+ * Create an object using the [EMAIL PROTECTED] 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 [EMAIL PROTECTED]
KeyedPoolableObjectFactory#makeObject} fails.
* @throws IllegalStateException after [EMAIL PROTECTED] #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 [EMAIL PROTECTED] UnsupportedOperationException}
- * if the pool cannot be cleared.
+ * Clears the pool, removing all pooled instances (optional operation).
+ * Throws [EMAIL PROTECTED] 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 [EMAIL PROTECTED] UnsupportedOperationException}
- * if the pool cannot be cleared.
+ * the given <code>key</code> (optional operation).
+ * Throws [EMAIL PROTECTED] 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 [EMAIL PROTECTED] #addObject} or [EMAIL PROTECTED]
#borrowObject} after invoking
- * this method on a pool will cause them to throw an
- * [EMAIL PROTECTED] IllegalStateException}.
+ * Calling [EMAIL PROTECTED] #addObject addObject} or [EMAIL PROTECTED]
#borrowObject borrowObject} after invoking
+ * this method on a pool will cause them to throw an [EMAIL PROTECTED]
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 [EMAIL PROTECTED] KeyedPoolableObjectFactory factory} I use
+ * Sets the [EMAIL PROTECTED] KeyedPoolableObjectFactory factory} the pool
uses
* to create new instances (optional operation).
- * @param factory the [EMAIL PROTECTED] KeyedPoolableObjectFactory} I use
to create new instances.
+ * Trying to change the <code>factory</code> after a pool has been used
will frequently
+ * throw an [EMAIL PROTECTED] UnsupportedOperationException}. It is up to
the pool
+ * implementation to determine when it is acceptable to call this method.
+ *
+ * @param factory the [EMAIL PROTECTED] 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 [EMAIL PROTECTED] KeyedPoolableObjectFactory},
* <ol>
* <li>
- * [EMAIL PROTECTED] #makeObject}
+ * [EMAIL PROTECTED] #makeObject makeObject}
* is called whenever a new instance is needed.
* </li>
* <li>
- * [EMAIL PROTECTED] #activateObject}
+ * [EMAIL PROTECTED] #activateObject activateObject}
* is invoked on every instance that has been
* [EMAIL PROTECTED] #passivateObject passivated} before it is
* [EMAIL PROTECTED] KeyedObjectPool#borrowObject borrowed} from the pool.
* </li>
* <li>
- * [EMAIL PROTECTED] #validateObject}
+ * [EMAIL PROTECTED] #validateObject validateObject}
* is invoked on [EMAIL PROTECTED] #activateObject activated} instances to
make sure
* they can be [EMAIL PROTECTED] KeyedObjectPool#borrowObject borrowed} from
the pool.
- * [EMAIL PROTECTED] #validateObject} <strong>may</strong> also be used to
test an
+ * <code>validateObject</code> <strong>may</strong> also be used to test an
* instance being [EMAIL PROTECTED] KeyedObjectPool#returnObject returned}
to the pool
* before it is [EMAIL PROTECTED] #passivateObject passivated}. It will only
be invoked
- * on an [EMAIL PROTECTED] #activateObject activated} instance.
+ * on an activated instance.
* </li>
* <li>
- * [EMAIL PROTECTED] #passivateObject}
+ * [EMAIL PROTECTED] #passivateObject passivateObject}
* is invoked on every instance when it is returned to the pool.
* </li>
* <li>
- * [EMAIL PROTECTED] #destroyObject}
+ * [EMAIL PROTECTED] #destroyObject destroyObject}
* is invoked on every instance when it is being "dropped" from the
- * pool (whether due to the response from [EMAIL PROTECTED] #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 [EMAIL PROTECTED] #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>
* [EMAIL PROTECTED] KeyedPoolableObjectFactory} must be thread-safe. The only
promise
* an [EMAIL PROTECTED] KeyedObjectPool} makes is that the same instance of an
object will not
- * be passed to more than one method of a [EMAIL PROTECTED]
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
+ * [EMAIL PROTECTED] #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 [EMAIL PROTECTED] #borrowObject borrowObject} and
[EMAIL PROTECTED] #returnObject returnObject}.
+ * required methods are [EMAIL PROTECTED] #borrowObject borrowObject}, [EMAIL
PROTECTED] #returnObject returnObject}
+ * and [EMAIL PROTECTED] #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 [EMAIL PROTECTED] org.apache.commons.pool.BaseObjectPool
BaseObjectPool} for a simple base implementation.
+ * }</pre>
+ * </p>
+ *
+ * <p>See [EMAIL PROTECTED] 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
- * [EMAIL PROTECTED] PoolableObjectFactory#makeObject} or will be a
previously idle object and
- * have been activated with [EMAIL PROTECTED]
PoolableObjectFactory#activateObject} and
- * then validated with [EMAIL PROTECTED]
PoolableObjectFactory#validateObject}.
+ * [EMAIL PROTECTED] PoolableObjectFactory#makeObject makeObject} or will
be a previously idle object and
+ * have been activated with [EMAIL PROTECTED]
PoolableObjectFactory#activateObject activateObject} and
+ * then validated with [EMAIL PROTECTED]
PoolableObjectFactory#validateObject validateObject}.
+ * </p>
* <p>
* By contract, clients <strong>must</strong> return the borrowed instance
using
- * [EMAIL PROTECTED] #returnObject}, [EMAIL PROTECTED] #invalidateObject},
or a related method
+ * [EMAIL PROTECTED] #returnObject returnObject}, [EMAIL PROTECTED]
#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 [EMAIL PROTECTED]
NoSuchElementException}.
+ * </p>
*
* @return an instance from this pool.
- * @throws IllegalStateException after [EMAIL PROTECTED] #close} has been
called on this pool.
- * @throws Exception when [EMAIL PROTECTED]
PoolableObjectFactory#makeObject} throws an exception.
- * @throws NoSuchElementException when the pool is exhaused and cannot or
will not return another instance.
+ * @throws IllegalStateException after [EMAIL PROTECTED] #close close} has
been called on this pool.
+ * @throws Exception when [EMAIL PROTECTED]
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 [EMAIL PROTECTED] #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 [EMAIL PROTECTED] #borrowObject() borrowObject}
+ * By contract, <code>obj</code> <strong>must</strong> have been obtained
+ * using [EMAIL PROTECTED] #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 [EMAIL PROTECTED] PoolableObjectFactory#validateObject} method
should be
- * used instead.
+ * </p>
*
- * @param obj a [EMAIL PROTECTED] #borrowObject borrowed} instance to be
returned.
+ * @param obj a [EMAIL PROTECTED] #borrowObject borrowed} instance to be
disposed.
*/
void invalidateObject(Object obj) throws Exception;
/**
- * Create an object using my [EMAIL PROTECTED] #setFactory factory} or
other
+ * Create an object using the [EMAIL PROTECTED] 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 [EMAIL PROTECTED] #addObject} or [EMAIL PROTECTED]
#borrowObject} after invoking
* this method on a pool will cause them to throw an
* [EMAIL PROTECTED] 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 [EMAIL PROTECTED] PoolableObjectFactory factory} I use
- * to create new instances (optional operation).
- * @param factory the [EMAIL PROTECTED] PoolableObjectFactory} I use to
create new instances.
+ * Sets the [EMAIL PROTECTED] 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 [EMAIL PROTECTED] UnsupportedOperationException}. It is up to
the pool
+ * implementation to determine when it is acceptable to call this method.
*
+ * @param factory the [EMAIL PROTECTED] 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 [EMAIL PROTECTED] PoolableObjectFactory},
* <ol>
* <li>
- * [EMAIL PROTECTED] #makeObject}
+ * [EMAIL PROTECTED] #makeObject makeObject}
* is called whenever a new instance is needed.
* </li>
* <li>
- * [EMAIL PROTECTED] #activateObject}
+ * [EMAIL PROTECTED] #activateObject activateObject}
* is invoked on every instance that has been
* [EMAIL PROTECTED] #passivateObject passivated} before it is
* [EMAIL PROTECTED] ObjectPool#borrowObject borrowed} from the pool.
* </li>
* <li>
- * [EMAIL PROTECTED] #validateObject}
+ * [EMAIL PROTECTED] #validateObject validateObject}
* is invoked on [EMAIL PROTECTED] #activateObject activated} instances to
make sure
* they can be [EMAIL PROTECTED] ObjectPool#borrowObject borrowed} from the
pool.
- * [EMAIL PROTECTED] #validateObject} <strong>may</strong> also be used to
test an
+ * <code>validateObject</code> <strong>may</strong> also be used to test an
* instance being [EMAIL PROTECTED] ObjectPool#returnObject returned} to the
pool
* before it is [EMAIL PROTECTED] #passivateObject passivated}. It will only
be invoked
- * on an [EMAIL PROTECTED] #activateObject activated} instance.
+ * on an activated instance.
* </li>
* <li>
- * [EMAIL PROTECTED] #passivateObject}
+ * [EMAIL PROTECTED] #passivateObject passivateObject}
* is invoked on every instance when it is returned to the pool.
* </li>
* <li>
- * [EMAIL PROTECTED] #destroyObject}
+ * [EMAIL PROTECTED] #destroyObject destroyObject}
* is invoked on every instance when it is being "dropped" from the
- * pool (whether due to the response from [EMAIL PROTECTED] #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 [EMAIL PROTECTED] #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>
* [EMAIL PROTECTED] PoolableObjectFactory} must be thread-safe. The only
promise
* an [EMAIL PROTECTED] ObjectPool} makes is that the same instance of an
object will not
- * be passed to more than one method of a [EMAIL PROTECTED]
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
+ * [EMAIL PROTECTED] #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: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
