commons-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From pste...@apache.org
Subject svn commit: r963070 - /commons/proper/pool/trunk/src/java/org/apache/commons/pool/impl/SoftReferenceObjectPool.java
Date Sun, 11 Jul 2010 13:24:21 GMT
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;



Mime
View raw message