Author: rdonkin
Date: Sat Feb 18 11:17:13 2006
New Revision: 378761
URL: http://svn.apache.org/viewcvs?rev=378761&view=rev
Log:
Updates to javadoc contracts for 2.0. Contributed by Sandy McArthur.
Issue#38660.
Modified:
jakarta/commons/proper/pool/trunk/src/java/org/apache/commons/pool/KeyedObjectPool.java
jakarta/commons/proper/pool/trunk/src/java/org/apache/commons/pool/ObjectPool.java
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=378761&r1=378760&r2=378761&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
Sat Feb 18 11:17:13 2006
@@ -16,6 +16,8 @@
package org.apache.commons.pool;
+import java.util.NoSuchElementException;
+
/**
* A "keyed" pooling interface.
* <p>
@@ -55,20 +57,30 @@
*/
public interface KeyedObjectPool {
/**
- * Obtain an instance from my pool
- * for the specified <i>key</i>.
- * By contract, clients MUST return
- * the borrowed object using
- * [EMAIL PROTECTED] #returnObject(java.lang.Object,java.lang.Object)
<tt>returnObject</tt>},
- * 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
+ * Obtains an instance from this pool for the specified <i>key</i>.
+ * <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}.
+ * <p>
+ * By contract, clients <strong>must</strong> return the borrowed object
using
+ * [EMAIL PROTECTED] #returnObject}, [EMAIL PROTECTED] #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
* 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,
+ * newer versions are encouraged to throw a [EMAIL PROTECTED]
NoSuchElementException}.
*
* @param key the key used to obtain the object
- * @return an instance from my pool.
+ * @return an instance from 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.
*/
- Object borrowObject(Object key) throws Exception;
+ Object borrowObject(Object key) throws Exception, NoSuchElementException;
/**
* Return an instance to my pool.
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=378761&r1=378760&r2=378761&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
Sat Feb 18 11:17:13 2006
@@ -16,6 +16,8 @@
package org.apache.commons.pool;
+import java.util.NoSuchElementException;
+
/**
* A pooling interface.
* <p>
@@ -45,19 +47,27 @@
*/
public interface ObjectPool {
/**
- * Obtain an instance from my pool.
- * By contract, clients MUST return
- * the borrowed instance using
- * [EMAIL PROTECTED] #returnObject(java.lang.Object) returnObject}
- * or a related method as defined in an implementation
- * or sub-interface.
+ * 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}.
+ * <p>
+ * By contract, clients <strong>must</strong> return the borrowed instance
using
+ * [EMAIL PROTECTED] #returnObject}, [EMAIL PROTECTED] #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 specified (although it may be specified by implementations).
+ * is not strictly specified (although it may be specified by
implementations).
+ * Older versions of this method would return <code>null</code> to
indicate exhasution,
+ * newer versions are encouraged to throw a [EMAIL PROTECTED]
NoSuchElementException}.
*
- * @return an instance from my pool.
+ * @return an instance from 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.
*/
- Object borrowObject() throws Exception;
+ Object borrowObject() throws Exception, NoSuchElementException;
/**
* Return an instance to my pool.
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
