You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by ps...@apache.org on 2010/07/11 15:24:21 UTC
svn commit: r963070 -
/commons/proper/pool/trunk/src/java/org/apache/commons/pool/impl/SoftReferenceObjectPool.java
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;