Author: psteitz
Date: Sun Jul 11 13:24:21 2010
New Revision: 963070
URL: http://svn.apache.org/viewvc?rev=963070&view=rev
Log:
* Deprecated setFactory and no arg constructor
* Added getFactory method
* Improved javadoc
JIRA: POOL-169
Modified:
commons/proper/pool/trunk/src/java/org/apache/commons/pool/impl/SoftReferenceObjectPool.java
Modified:
commons/proper/pool/trunk/src/java/org/apache/commons/pool/impl/SoftReferenceObjectPool.java
URL:
http://svn.apache.org/viewvc/commons/proper/pool/trunk/src/java/org/apache/commons/pool/impl/SoftReferenceObjectPool.java?rev=963070&r1=963069&r2=963070&view=diff
==============================================================================
---
commons/proper/pool/trunk/src/java/org/apache/commons/pool/impl/SoftReferenceObjectPool.java
(original)
+++
commons/proper/pool/trunk/src/java/org/apache/commons/pool/impl/SoftReferenceObjectPool.java
Sun Jul 11 13:24:21 2010
@@ -47,6 +47,7 @@ public class SoftReferenceObjectPool ext
* Generally speaking you should prefer the {...@link
#SoftReferenceObjectPool(PoolableObjectFactory)} constructor.
*
* @see #SoftReferenceObjectPool(PoolableObjectFactory)
+ * @deprecated to be removed in pool 2.0. Use {...@link
#SoftReferenceObjectPool(PoolableObjectFactory)}.
*/
public SoftReferenceObjectPool() {
_pool = new ArrayList();
@@ -71,7 +72,7 @@ public class SoftReferenceObjectPool ext
* @throws Exception when there is a problem prefilling the pool.
* @throws IllegalArgumentException when <code>factory</code> is
<code>null</code>.
* @deprecated because this is a SoftReference pool, prefilled idle
obejects may be garbage collected before they are used.
- * To be removed in Pool 3.0.
+ * To be removed in Pool 2.0.
*/
public SoftReferenceObjectPool(PoolableObjectFactory factory, int
initSize) throws Exception, IllegalArgumentException {
if (factory == null) {
@@ -82,6 +83,27 @@ public class SoftReferenceObjectPool ext
PoolUtils.prefill(this, initSize);
}
+ /**
+ * <p>Borrow an object from the pool. If there are no idle instances
available in the pool, the configured
+ * factory's {...@link PoolableObjectFactory#makeObject()} method is
invoked to create a new instance.</p>
+ *
+ * <p>All instances are {...@link
PoolableObjectFactory#activateObject(Object) activated} and
+ * {...@link PoolableObjectFactory#validateObject(Object) validated}
before being returned by this
+ * method. If validation fails or an exception occurs activating or
validating an idle instance,
+ * the failing instance is {...@link
PoolableObjectFactory#destroyObject(Object) destroyed} and another
+ * instance is retrieved from the pool, validated and activated. This
process continues until either the
+ * pool is empty or an instance passes validation. If the pool is empty
on activation or
+ * it does not contain any valid instances, the factory's
<code>makeObject</code> method is used
+ * to create a new instance. If the created instance either raises an
exception on activation or
+ * fails validation, <code>NoSuchElementException</code> is thrown.
Exceptions thrown by <code>MakeObject</code>
+ * are propagated to the caller; but other than <code>ThreadDeath</code>
or <code>VirtualMachineError</code>,
+ * exceptions generated by activation, validation or destroy methods are
swallowed silently.</p>
+ *
+ * @throws NoSuchElementException if a valid object cannot be provided
+ * @throws IllegalStateException if invoked on a {...@link #close()
closed} pool
+ * @throws Exception if an exception occurs creating a new instance
+ * @return a valid, activated object instance
+ */
public synchronized Object borrowObject() throws Exception {
assertOpen();
Object obj = null;
@@ -127,6 +149,20 @@ public class SoftReferenceObjectPool ext
return obj;
}
+ /**
+ * <p>Returns an instance to the pool after successful validation and
passivation. The returning instance
+ * is destroyed if any of the following are true:<ul>
+ * <li>the pool is closed</li>
+ * <li>{...@link PoolableObjectFactory#validateObject(Object)
validation} fails</li>
+ * <li>{...@link PoolableObjectFactory#passivateObject(Object)
passivation} throws an exception</li>
+ * </ul>
+ *</p>
+ *
+ * <p>Exceptions passivating or destroying instances are silently
swallowed. Exceptions validating
+ * instances are propagated to the client.</p>
+ *
+ * @param obj instance to return to the pool
+ */
public synchronized void returnObject(Object obj) throws Exception {
boolean success = !isClosed();
if (_factory != null) {
@@ -157,6 +193,9 @@ public class SoftReferenceObjectPool ext
}
}
+ /**
+ * {...@inheritdoc}
+ */
public synchronized void invalidateObject(Object obj) throws Exception {
_numActive--;
if (_factory != null) {
@@ -166,8 +205,18 @@ public class SoftReferenceObjectPool ext
}
/**
- * Create an object, and place it into the pool.
- * addObject() is useful for "pre-loading" a pool with idle objects.
+ * <p>Create an object, and place it into the pool.
+ * addObject() is useful for "pre-loading" a pool with idle objects.</p>
+ *
+ * <p>Before being added to the pool, the newly created instance is
+ * {...@link PoolableObjectFactory#validateObject(Object) validated} and
+ * {...@link PoolableObjectFactory#passivateObject(Object) passivated}.
If validation
+ * fails, the new instance is {...@link
PoolableObjectFactory#destroyObject(Object) destroyed}.
+ * Exceptions generated by the factory <code>makeObject</code> or
<code>passivate</code> are
+ * propagated to the caller. Exceptions destroying instances are silently
swallowed.</p>
+ *
+ * @throws IllegalStateException if invoked on a {...@link #close()
closed} pool
+ * @throws Exception when the {...@link #getFactory() factory} has a
problem creating or passivating an object.
*/
public synchronized void addObject() throws Exception {
assertOpen();
@@ -198,7 +247,11 @@ public class SoftReferenceObjectPool ext
}
}
- /** Returns an approximation not less than the of the number of idle
instances in the pool. */
+ /**
+ * Returns an approximation not less than the of the number of idle
instances in the pool.
+ *
+ * @return estimated number of idle instances in the pool
+ */
public synchronized int getNumIdle() {
pruneClearedReferences();
return _pool.size();
@@ -234,6 +287,16 @@ public class SoftReferenceObjectPool ext
pruneClearedReferences();
}
+ /**
+ * <p>Close this pool, and free any resources associated with it. Invokes
+ * {...@link #clear()} to destroy and remove instances in the pool.</p>
+ *
+ * <p>Calling {...@link #addObject} or {...@link #borrowObject} after
invoking
+ * this method on a pool will cause them to throw an
+ * {...@link IllegalStateException}.</p>
+ *
+ * @throws Exception never - exceptions clearing the pool are swallowed
+ */
public void close() throws Exception {
super.close();
clear();
@@ -247,6 +310,7 @@ public class SoftReferenceObjectPool ext
*
* @param factory the {...@link PoolableObjectFactory} used to create new
instances.
* @throws IllegalStateException when the factory cannot be set at this
time
+ * @deprecated to be removed in pool 2.0
*/
public synchronized void setFactory(PoolableObjectFactory factory) throws
IllegalStateException {
assertOpen();
@@ -272,6 +336,16 @@ public class SoftReferenceObjectPool ext
}
}
}
+
+ /**
+ * Returns the {...@link PoolableObjectFactory} used by this pool to
create and manage object instances.
+ *
+ * @return the factory
+ * @since 1.5.5
+ */
+ public PoolableObjectFactory getFactory() {
+ return _factory;
+ }
/** My pool. */
private List _pool = null;
