You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by rd...@apache.org on 2006/02/18 20:17:16 UTC
svn commit: r378761 - in
/jakarta/commons/proper/pool/trunk/src/java/org/apache/commons/pool:
KeyedObjectPool.java ObjectPool.java
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
- * {@link #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
+ * {@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}.
+ * <p>
+ * By contract, clients <strong>must</strong> return the borrowed object using
+ * {@link #returnObject}, {@link #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
* 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 {@link 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 {@link 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
- * {@link #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
+ * {@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 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 {@link NoSuchElementException}.
*
- * @return an instance from my pool.
+ * @return an instance from 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.
*/
- Object borrowObject() throws Exception;
+ Object borrowObject() throws Exception, NoSuchElementException;
/**
* Return an instance to my pool.
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org