Author: markt
Date: Mon Feb 10 13:06:40 2014
New Revision: 1566605
URL: http://svn.apache.org/r1566605
Log:
Follow-up for POOL-248.
Ensure the reasons for ISE on return is clear in the Javadoc.
Modified:
commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/BaseObjectPool.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/ObjectPool.java
commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/impl/GenericObjectPool.java
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=1566605&r1=1566604&r2=1566605&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
Mon Feb 10 13:06:40 2014
@@ -30,37 +30,13 @@ package org.apache.commons.pool2;
* @since 2.0
*/
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
public abstract T borrowObject() throws Exception;
- /**
- * Returns an instance to the pool.
- *
- * @param obj instance to return to the pool
- */
@Override
public abstract void returnObject(T obj) throws Exception;
- /**
- * 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 If the object can not be invalidated
- */
@Override
public abstract void invalidateObject(T obj) throws Exception;
@@ -108,7 +84,9 @@ public abstract class BaseObjectPool<T>
}
/**
- * Close this pool. This affects the behavior of <code>isClosed</code> and
+ * {@inheritDoc}
+ * <p>
+ * This affects the behavior of <code>isClosed</code> and
* <code>assertOpen</code>.
*/
@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=1566605&r1=1566604&r2=1566605&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
Mon Feb 10 13:06:40 2014
@@ -108,6 +108,13 @@ public interface KeyedObjectPool<K,V> {
* @param key the key used to obtain the object
* @param obj a {@link #borrowObject borrowed} instance to be returned.
*
+ * @throws IllegalStateException
+ * if an attempt is made to return an object to the pool that
+ * is in any state other than allocated (i.e. borrowed).
+ * Attempting to return an object more than once or attempting
+ * to return an object that was never borrowed from the pool
+ * will trigger this exception.
+ *
* @throws Exception if an instance cannot be returned to the pool
*/
void returnObject(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=1566605&r1=1566604&r2=1566605&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
Mon Feb 10 13:06:40 2014
@@ -95,6 +95,13 @@ public interface ObjectPool<T> {
*
* @param obj a {@link #borrowObject borrowed} instance to be returned.
*
+ * @throws IllegalStateException
+ * if an attempt is made to return an object to the pool that
+ * is in any state other than allocated (i.e. borrowed).
+ * Attempting to return an object more than once or attempting
+ * to return an object that was never borrowed from the pool
+ * will trigger this exception.
+ *
* @throws Exception if an instance cannot be returned to the pool
*/
void returnObject(T obj) throws Exception;
Modified:
commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/impl/GenericObjectPool.java
URL:
http://svn.apache.org/viewvc/commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/impl/GenericObjectPool.java?rev=1566605&r1=1566604&r2=1566605&view=diff
==============================================================================
---
commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/impl/GenericObjectPool.java
(original)
+++
commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/impl/GenericObjectPool.java
Mon Feb 10 13:06:40 2014
@@ -513,7 +513,7 @@ public class GenericObjectPool<T> extend
}
/**
- * Returns an object instance to the pool.
+ * {@inheritDoc}
* <p>
* If {@link #getMaxIdle() maxIdle} is set to a positive value and the
* number of idle instances has reached this value, the returning instance
@@ -525,8 +525,6 @@ public class GenericObjectPool<T> extend
* <p>
* Exceptions encountered destroying objects for any reason are swallowed
* but notified via a {@link SwallowedExceptionListener}.
- *
- * @param obj instance to return to the pool
*/
@Override
public void returnObject(T obj) {
