You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by ma...@apache.org on 2012/05/04 12:10:14 UTC
svn commit: r1333854 [2/2] - in
/commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2: ./ impl/
Modified: commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/PoolUtils.java
URL: http://svn.apache.org/viewvc/commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/PoolUtils.java?rev=1333854&r1=1333853&r2=1333854&view=diff
==============================================================================
--- commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/PoolUtils.java (original)
+++ commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/PoolUtils.java Fri May 4 10:10:13 2012
@@ -14,7 +14,6 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
-
package org.apache.commons.pool2;
import java.util.Collection;
@@ -30,26 +29,25 @@ import java.util.concurrent.locks.Reentr
import java.util.concurrent.locks.ReentrantReadWriteLock.WriteLock;
/**
- * This class consists exclusively of static methods that operate on or return ObjectPool
- * or KeyedObjectPool related interfaces.
+ * This class consists exclusively of static methods that operate on or return
+ * ObjectPool or KeyedObjectPool related interfaces.
*
* @version $Revision$
- * @since Pool 1.3
- *
- * This class is intended to be thread-safe.
+ * @since Pool 1.3 This class is intended to be thread-safe.
*/
public final class PoolUtils {
/**
- * Timer used to periodically check pools idle object count.
- * Because a {@link Timer} creates a {@link Thread} this is lazily instantiated.
+ * Timer used to periodically check pools idle object count. Because a
+ * {@link Timer} creates a {@link Thread} this is lazily instantiated.
*/
- private static Timer MIN_IDLE_TIMER; //@GuardedBy("PoolUtils.class")
+ private static Timer MIN_IDLE_TIMER; // @GuardedBy("PoolUtils.class")
/**
* PoolUtils instances should NOT be constructed in standard programming.
* Instead, the class should be used procedurally: PoolUtils.adapt(aPool);.
- * This constructor is public to permit tools that require a JavaBean instance to operate.
+ * This constructor is public to permit tools that require a JavaBean
+ * instance to operate.
*/
public PoolUtils() {
}
@@ -59,9 +57,13 @@ public final class PoolUtils {
* one of the Throwables that should never be swallowed). Used by the pool
* error handling for operations that throw exceptions that normally need to
* be ignored.
- * @param t The Throwable to check
- * @throws ThreadDeath if that is passed in
- * @throws VirtualMachineError if that is passed in
+ *
+ * @param t
+ * The Throwable to check
+ * @throws ThreadDeath
+ * if that is passed in
+ * @throws VirtualMachineError
+ * if that is passed in
* @since Pool 1.5.5
*/
public static void checkRethrow(Throwable t) {
@@ -75,20 +77,30 @@ public final class PoolUtils {
}
/**
- * Periodically check the idle object count for the pool. At most one idle object will be added per period.
- * If there is an exception when calling {@link ObjectPool#addObject()} then no more checks will be performed.
- *
- * @param pool the pool to check periodically.
- * @param minIdle if the {@link ObjectPool#getNumIdle()} is less than this then add an idle object.
- * @param period the frequency to check the number of idle objects in a pool, see
- * {@link Timer#schedule(TimerTask, long, long)}.
- * @return the {@link TimerTask} that will periodically check the pools idle object count.
- * @throws IllegalArgumentException when <code>pool</code> is <code>null</code> or
- * when <code>minIdle</code> is negative or when <code>period</code> isn't
- * valid for {@link Timer#schedule(TimerTask, long, long)}.
+ * Periodically check the idle object count for the pool. At most one idle
+ * object will be added per period. If there is an exception when calling
+ * {@link ObjectPool#addObject()} then no more checks will be performed.
+ *
+ * @param pool
+ * the pool to check periodically.
+ * @param minIdle
+ * if the {@link ObjectPool#getNumIdle()} is less than this then
+ * add an idle object.
+ * @param period
+ * the frequency to check the number of idle objects in a pool,
+ * see {@link Timer#schedule(TimerTask, long, long)}.
+ * @return the {@link TimerTask} that will periodically check the pools idle
+ * object count.
+ * @throws IllegalArgumentException
+ * when <code>pool</code> is <code>null</code> or when
+ * <code>minIdle</code> is negative or when <code>period</code>
+ * isn't valid for {@link Timer#schedule(TimerTask, long, long)}
+ * .
* @since Pool 1.3
*/
- public static <T> TimerTask checkMinIdle(final ObjectPool<T> pool, final int minIdle, final long period) throws IllegalArgumentException {
+ public static <T> TimerTask checkMinIdle(final ObjectPool<T> pool,
+ final int minIdle, final long period)
+ throws IllegalArgumentException {
if (pool == null) {
throw new IllegalArgumentException("keyedPool must not be null.");
}
@@ -101,22 +113,34 @@ public final class PoolUtils {
}
/**
- * Periodically check the idle object count for the key in the keyedPool. At most one idle object will be added per period.
- * If there is an exception when calling {@link KeyedObjectPool#addObject(Object)} then no more checks for that key
- * will be performed.
- *
- * @param keyedPool the keyedPool to check periodically.
- * @param key the key to check the idle count of.
- * @param minIdle if the {@link KeyedObjectPool#getNumIdle(Object)} is less than this then add an idle object.
- * @param period the frequency to check the number of idle objects in a keyedPool, see
- * {@link Timer#schedule(TimerTask, long, long)}.
- * @return the {@link TimerTask} that will periodically check the pools idle object count.
- * @throws IllegalArgumentException when <code>keyedPool</code>, <code>key</code> is <code>null</code> or
- * when <code>minIdle</code> is negative or when <code>period</code> isn't
- * valid for {@link Timer#schedule(TimerTask, long, long)}.
+ * Periodically check the idle object count for the key in the keyedPool. At
+ * most one idle object will be added per period. If there is an exception
+ * when calling {@link KeyedObjectPool#addObject(Object)} then no more
+ * checks for that key will be performed.
+ *
+ * @param keyedPool
+ * the keyedPool to check periodically.
+ * @param key
+ * the key to check the idle count of.
+ * @param minIdle
+ * if the {@link KeyedObjectPool#getNumIdle(Object)} is less than
+ * this then add an idle object.
+ * @param period
+ * the frequency to check the number of idle objects in a
+ * keyedPool, see {@link Timer#schedule(TimerTask, long, long)}.
+ * @return the {@link TimerTask} that will periodically check the pools idle
+ * object count.
+ * @throws IllegalArgumentException
+ * when <code>keyedPool</code>, <code>key</code> is
+ * <code>null</code> or when <code>minIdle</code> is negative or
+ * when <code>period</code> isn't valid for
+ * {@link Timer#schedule(TimerTask, long, long)}.
* @since Pool 1.3
*/
- public static <K,V> TimerTask checkMinIdle(final KeyedObjectPool<K,V> keyedPool, final K key, final int minIdle, final long period) throws IllegalArgumentException {
+ public static <K, V> TimerTask checkMinIdle(
+ final KeyedObjectPool<K, V> keyedPool, final K key,
+ final int minIdle, final long period)
+ throws IllegalArgumentException {
if (keyedPool == null) {
throw new IllegalArgumentException("keyedPool must not be null.");
}
@@ -126,32 +150,46 @@ public final class PoolUtils {
if (minIdle < 0) {
throw new IllegalArgumentException("minIdle must be non-negative.");
}
- final TimerTask task = new KeyedObjectPoolMinIdleTimerTask<K,V>(keyedPool, key, minIdle);
+ final TimerTask task = new KeyedObjectPoolMinIdleTimerTask<K, V>(
+ keyedPool, key, minIdle);
getMinIdleTimer().schedule(task, 0L, period);
return task;
}
/**
- * Periodically check the idle object count for each key in the <code>Collection</code> <code>keys</code> in the keyedPool.
- * At most one idle object will be added per period.
- *
- * @param keyedPool the keyedPool to check periodically.
- * @param keys a collection of keys to check the idle object count.
- * @param minIdle if the {@link KeyedObjectPool#getNumIdle(Object)} is less than this then add an idle object.
- * @param period the frequency to check the number of idle objects in a keyedPool, see
- * {@link Timer#schedule(TimerTask, long, long)}.
- * @return a {@link Map} of key and {@link TimerTask} pairs that will periodically check the pools idle object count.
- * @throws IllegalArgumentException when <code>keyedPool</code>, <code>keys</code>, or any of the values in the
- * collection is <code>null</code> or when <code>minIdle</code> is negative or when <code>period</code> isn't
- * valid for {@link Timer#schedule(TimerTask, long, long)}.
+ * Periodically check the idle object count for each key in the
+ * <code>Collection</code> <code>keys</code> in the keyedPool. At most one
+ * idle object will be added per period.
+ *
+ * @param keyedPool
+ * the keyedPool to check periodically.
+ * @param keys
+ * a collection of keys to check the idle object count.
+ * @param minIdle
+ * if the {@link KeyedObjectPool#getNumIdle(Object)} is less than
+ * this then add an idle object.
+ * @param period
+ * the frequency to check the number of idle objects in a
+ * keyedPool, see {@link Timer#schedule(TimerTask, long, long)}.
+ * @return a {@link Map} of key and {@link TimerTask} pairs that will
+ * periodically check the pools idle object count.
+ * @throws IllegalArgumentException
+ * when <code>keyedPool</code>, <code>keys</code>, or any of the
+ * values in the collection is <code>null</code> or when
+ * <code>minIdle</code> is negative or when <code>period</code>
+ * isn't valid for {@link Timer#schedule(TimerTask, long, long)}
+ * .
* @see #checkMinIdle(KeyedObjectPool, Object, int, long)
* @since Pool 1.3
*/
- public static <K,V> Map<K,TimerTask> checkMinIdle(final KeyedObjectPool<K,V> keyedPool, final Collection<K> keys, final int minIdle, final long period) throws IllegalArgumentException {
+ public static <K, V> Map<K, TimerTask> checkMinIdle(
+ final KeyedObjectPool<K, V> keyedPool, final Collection<K> keys,
+ final int minIdle, final long period)
+ throws IllegalArgumentException {
if (keys == null) {
throw new IllegalArgumentException("keys must not be null.");
}
- final Map<K,TimerTask> tasks = new HashMap<K,TimerTask>(keys.size());
+ final Map<K, TimerTask> tasks = new HashMap<K, TimerTask>(keys.size());
final Iterator<K> iter = keys.iterator();
while (iter.hasNext()) {
final K key = iter.next();
@@ -162,15 +200,21 @@ public final class PoolUtils {
}
/**
- * Call <code>addObject()</code> on <code>pool</code> <code>count</code> number of times.
+ * Call <code>addObject()</code> on <code>pool</code> <code>count</code>
+ * number of times.
*
- * @param pool the pool to prefill.
- * @param count the number of idle objects to add.
- * @throws Exception when {@link ObjectPool#addObject()} fails.
- * @throws IllegalArgumentException when <code>pool</code> is <code>null</code>.
+ * @param pool
+ * the pool to prefill.
+ * @param count
+ * the number of idle objects to add.
+ * @throws Exception
+ * when {@link ObjectPool#addObject()} fails.
+ * @throws IllegalArgumentException
+ * when <code>pool</code> is <code>null</code>.
* @since Pool 1.3
*/
- public static <T> void prefill(final ObjectPool<T> pool, final int count) throws Exception, IllegalArgumentException {
+ public static <T> void prefill(final ObjectPool<T> pool, final int count)
+ throws Exception, IllegalArgumentException {
if (pool == null) {
throw new IllegalArgumentException("pool must not be null.");
}
@@ -180,17 +224,25 @@ public final class PoolUtils {
}
/**
- * Call <code>addObject(Object)</code> on <code>keyedPool</code> with <code>key</code> <code>count</code>
- * number of times.
+ * Call <code>addObject(Object)</code> on <code>keyedPool</code> with
+ * <code>key</code> <code>count</code> number of times.
*
- * @param keyedPool the keyedPool to prefill.
- * @param key the key to add objects for.
- * @param count the number of idle objects to add for <code>key</code>.
- * @throws Exception when {@link KeyedObjectPool#addObject(Object)} fails.
- * @throws IllegalArgumentException when <code>keyedPool</code> or <code>key</code> is <code>null</code>.
+ * @param keyedPool
+ * the keyedPool to prefill.
+ * @param key
+ * the key to add objects for.
+ * @param count
+ * the number of idle objects to add for <code>key</code>.
+ * @throws Exception
+ * when {@link KeyedObjectPool#addObject(Object)} fails.
+ * @throws IllegalArgumentException
+ * when <code>keyedPool</code> or <code>key</code> is
+ * <code>null</code>.
* @since Pool 1.3
*/
- public static <K,V> void prefill(final KeyedObjectPool<K,V> keyedPool, final K key, final int count) throws Exception, IllegalArgumentException {
+ public static <K, V> void prefill(final KeyedObjectPool<K, V> keyedPool,
+ final K key, final int count) throws Exception,
+ IllegalArgumentException {
if (keyedPool == null) {
throw new IllegalArgumentException("keyedPool must not be null.");
}
@@ -203,20 +255,28 @@ public final class PoolUtils {
}
/**
- * Call <code>addObject(Object)</code> on <code>keyedPool</code> with each key in <code>keys</code> for
- * <code>count</code> number of times. This has the same effect as calling
- * {@link #prefill(KeyedObjectPool, Object, int)} for each key in the <code>keys</code> collection.
- *
- * @param keyedPool the keyedPool to prefill.
- * @param keys {@link Collection} of keys to add objects for.
- * @param count the number of idle objects to add for each <code>key</code>.
- * @throws Exception when {@link KeyedObjectPool#addObject(Object)} fails.
- * @throws IllegalArgumentException when <code>keyedPool</code>, <code>keys</code>, or
- * any value in <code>keys</code> is <code>null</code>.
+ * Call <code>addObject(Object)</code> on <code>keyedPool</code> with each
+ * key in <code>keys</code> for <code>count</code> number of times. This has
+ * the same effect as calling {@link #prefill(KeyedObjectPool, Object, int)}
+ * for each key in the <code>keys</code> collection.
+ *
+ * @param keyedPool
+ * the keyedPool to prefill.
+ * @param keys
+ * {@link Collection} of keys to add objects for.
+ * @param count
+ * the number of idle objects to add for each <code>key</code>.
+ * @throws Exception
+ * when {@link KeyedObjectPool#addObject(Object)} fails.
+ * @throws IllegalArgumentException
+ * when <code>keyedPool</code>, <code>keys</code>, or any value
+ * in <code>keys</code> is <code>null</code>.
* @see #prefill(KeyedObjectPool, Object, int)
* @since Pool 1.3
*/
- public static <K,V> void prefill(final KeyedObjectPool<K,V> keyedPool, final Collection<K> keys, final int count) throws Exception, IllegalArgumentException {
+ public static <K, V> void prefill(final KeyedObjectPool<K, V> keyedPool,
+ final Collection<K> keys, final int count) throws Exception,
+ IllegalArgumentException {
if (keys == null) {
throw new IllegalArgumentException("keys must not be null.");
}
@@ -227,16 +287,19 @@ public final class PoolUtils {
}
/**
- * Returns a synchronized (thread-safe) ObjectPool backed by the specified ObjectPool.
- *
- * <p><b>Note:</b>
- * This should not be used on pool implementations that already provide proper synchronization
- * such as the pools provided in the Commons Pool library. Wrapping a pool that
- * {@link #wait() waits} for poolable objects to be returned before allowing another one to be
- * borrowed with another layer of synchronization will cause liveliness issues or a deadlock.
+ * Returns a synchronized (thread-safe) ObjectPool backed by the specified
+ * ObjectPool.
+ * <p>
+ * <b>Note:</b> This should not be used on pool implementations that already
+ * provide proper synchronization such as the pools provided in the Commons
+ * Pool library. Wrapping a pool that {@link #wait() waits} for poolable
+ * objects to be returned before allowing another one to be borrowed with
+ * another layer of synchronization will cause liveliness issues or a
+ * deadlock.
* </p>
*
- * @param pool the ObjectPool to be "wrapped" in a synchronized ObjectPool.
+ * @param pool
+ * the ObjectPool to be "wrapped" in a synchronized ObjectPool.
* @return a synchronized view of the specified ObjectPool.
* @since Pool 1.3
*/
@@ -245,77 +308,96 @@ public final class PoolUtils {
throw new IllegalArgumentException("pool must not be null.");
}
/*
- assert !(pool instanceof GenericObjectPool)
- : "GenericObjectPool is already thread-safe";
- assert !(pool instanceof SoftReferenceObjectPool)
- : "SoftReferenceObjectPool is already thread-safe";
- assert !(pool instanceof StackObjectPool)
- : "StackObjectPool is already thread-safe";
- assert !"org.apache.commons.pool.composite.CompositeObjectPool".equals(pool.getClass().getName())
- : "CompositeObjectPools are already thread-safe";
- */
+ * assert !(pool instanceof GenericObjectPool) :
+ * "GenericObjectPool is already thread-safe"; assert !(pool instanceof
+ * SoftReferenceObjectPool) :
+ * "SoftReferenceObjectPool is already thread-safe"; assert !(pool
+ * instanceof StackObjectPool) :
+ * "StackObjectPool is already thread-safe"; assert
+ * !"org.apache.commons.pool.composite.CompositeObjectPool"
+ * .equals(pool.getClass().getName()) :
+ * "CompositeObjectPools are already thread-safe";
+ */
return new SynchronizedObjectPool<T>(pool);
}
/**
- * Returns a synchronized (thread-safe) KeyedObjectPool backed by the specified KeyedObjectPool.
- *
- * <p><b>Note:</b>
- * This should not be used on pool implementations that already provide proper synchronization
- * such as the pools provided in the Commons Pool library. Wrapping a pool that
- * {@link #wait() waits} for poolable objects to be returned before allowing another one to be
- * borrowed with another layer of synchronization will cause liveliness issues or a deadlock.
+ * Returns a synchronized (thread-safe) KeyedObjectPool backed by the
+ * specified KeyedObjectPool.
+ * <p>
+ * <b>Note:</b> This should not be used on pool implementations that already
+ * provide proper synchronization such as the pools provided in the Commons
+ * Pool library. Wrapping a pool that {@link #wait() waits} for poolable
+ * objects to be returned before allowing another one to be borrowed with
+ * another layer of synchronization will cause liveliness issues or a
+ * deadlock.
* </p>
*
- * @param keyedPool the KeyedObjectPool to be "wrapped" in a synchronized KeyedObjectPool.
+ * @param keyedPool
+ * the KeyedObjectPool to be "wrapped" in a synchronized
+ * KeyedObjectPool.
* @return a synchronized view of the specified KeyedObjectPool.
* @since Pool 1.3
*/
- public static <K,V> KeyedObjectPool<K,V> synchronizedPool(final KeyedObjectPool<K,V> keyedPool) {
+ public static <K, V> KeyedObjectPool<K, V> synchronizedPool(
+ final KeyedObjectPool<K, V> keyedPool) {
if (keyedPool == null) {
throw new IllegalArgumentException("keyedPool must not be null.");
}
/*
- assert !(keyedPool instanceof GenericKeyedObjectPool)
- : "GenericKeyedObjectPool is already thread-safe";
- assert !(keyedPool instanceof StackKeyedObjectPool)
- : "StackKeyedObjectPool is already thread-safe";
- assert !"org.apache.commons.pool.composite.CompositeKeyedObjectPool".equals(keyedPool.getClass().getName())
- : "CompositeKeyedObjectPools are already thread-safe";
- */
- return new SynchronizedKeyedObjectPool<K,V>(keyedPool);
+ * assert !(keyedPool instanceof GenericKeyedObjectPool) :
+ * "GenericKeyedObjectPool is already thread-safe"; assert !(keyedPool
+ * instanceof StackKeyedObjectPool) :
+ * "StackKeyedObjectPool is already thread-safe"; assert
+ * !"org.apache.commons.pool.composite.CompositeKeyedObjectPool"
+ * .equals(keyedPool.getClass().getName()) :
+ * "CompositeKeyedObjectPools are already thread-safe";
+ */
+ return new SynchronizedKeyedObjectPool<K, V>(keyedPool);
}
/**
- * Returns a synchronized (thread-safe) PoolableObjectFactory backed by the specified PoolableObjectFactory.
+ * Returns a synchronized (thread-safe) PoolableObjectFactory backed by the
+ * specified PoolableObjectFactory.
*
- * @param factory the PoolableObjectFactory to be "wrapped" in a synchronized PoolableObjectFactory.
+ * @param factory
+ * the PoolableObjectFactory to be "wrapped" in a synchronized
+ * PoolableObjectFactory.
* @return a synchronized view of the specified PoolableObjectFactory.
* @since Pool 1.3
*/
- public static <T> PoolableObjectFactory<T> synchronizedPoolableFactory(final PoolableObjectFactory<T> factory) {
+ public static <T> PoolableObjectFactory<T> synchronizedPoolableFactory(
+ final PoolableObjectFactory<T> factory) {
return new SynchronizedPoolableObjectFactory<T>(factory);
}
/**
- * Returns a synchronized (thread-safe) KeyedPoolableObjectFactory backed by the specified KeyedPoolableObjectFactory.
+ * Returns a synchronized (thread-safe) KeyedPoolableObjectFactory backed by
+ * the specified KeyedPoolableObjectFactory.
*
- * @param keyedFactory the KeyedPoolableObjectFactory to be "wrapped" in a synchronized KeyedPoolableObjectFactory.
+ * @param keyedFactory
+ * the KeyedPoolableObjectFactory to be "wrapped" in a
+ * synchronized KeyedPoolableObjectFactory.
* @return a synchronized view of the specified KeyedPoolableObjectFactory.
* @since Pool 1.3
*/
- public static <K,V> KeyedPoolableObjectFactory<K,V> synchronizedPoolableFactory(final KeyedPoolableObjectFactory<K,V> keyedFactory) {
- return new SynchronizedKeyedPoolableObjectFactory<K,V>(keyedFactory);
+ public static <K, V> KeyedPoolableObjectFactory<K, V> synchronizedPoolableFactory(
+ final KeyedPoolableObjectFactory<K, V> keyedFactory) {
+ return new SynchronizedKeyedPoolableObjectFactory<K, V>(keyedFactory);
}
/**
- * Returns a pool that adaptively decreases it's size when idle objects are no longer needed.
- * This is intended as an always thread-safe alternative to using an idle object evictor
- * provided by many pool implementations. This is also an effective way to shrink FIFO ordered
- * pools that experience load spikes.
- *
- * @param pool the ObjectPool to be decorated so it shrinks it's idle count when possible.
- * @return a pool that adaptively decreases it's size when idle objects are no longer needed.
+ * Returns a pool that adaptively decreases it's size when idle objects are
+ * no longer needed. This is intended as an always thread-safe alternative
+ * to using an idle object evictor provided by many pool implementations.
+ * This is also an effective way to shrink FIFO ordered pools that
+ * experience load spikes.
+ *
+ * @param pool
+ * the ObjectPool to be decorated so it shrinks it's idle count
+ * when possible.
+ * @return a pool that adaptively decreases it's size when idle objects are
+ * no longer needed.
* @see #erodingPool(ObjectPool, float)
* @since Pool 1.4
*/
@@ -324,26 +406,33 @@ public final class PoolUtils {
}
/**
- * Returns a pool that adaptively decreases it's size when idle objects are no longer needed.
- * This is intended as an always thread-safe alternative to using an idle object evictor
- * provided by many pool implementations. This is also an effective way to shrink FIFO ordered
- * pools that experience load spikes.
- *
+ * Returns a pool that adaptively decreases it's size when idle objects are
+ * no longer needed. This is intended as an always thread-safe alternative
+ * to using an idle object evictor provided by many pool implementations.
+ * This is also an effective way to shrink FIFO ordered pools that
+ * experience load spikes.
* <p>
- * The factor parameter provides a mechanism to tweak the rate at which the pool tries to shrink
- * it's size. Values between 0 and 1 cause the pool to try to shrink it's size more often.
- * Values greater than 1 cause the pool to less frequently try to shrink it's size.
+ * The factor parameter provides a mechanism to tweak the rate at which the
+ * pool tries to shrink it's size. Values between 0 and 1 cause the pool to
+ * try to shrink it's size more often. Values greater than 1 cause the pool
+ * to less frequently try to shrink it's size.
* </p>
*
- * @param pool the ObjectPool to be decorated so it shrinks it's idle count when possible.
- * @param factor a positive value to scale the rate at which the pool tries to reduce it's size.
- * If 0 < factor < 1 then the pool shrinks more aggressively.
- * If 1 < factor then the pool shrinks less aggressively.
- * @return a pool that adaptively decreases it's size when idle objects are no longer needed.
+ * @param pool
+ * the ObjectPool to be decorated so it shrinks it's idle count
+ * when possible.
+ * @param factor
+ * a positive value to scale the rate at which the pool tries to
+ * reduce it's size. If 0 < factor < 1 then the pool
+ * shrinks more aggressively. If 1 < factor then the pool
+ * shrinks less aggressively.
+ * @return a pool that adaptively decreases it's size when idle objects are
+ * no longer needed.
* @see #erodingPool(ObjectPool)
* @since Pool 1.4
*/
- public static <T> ObjectPool<T> erodingPool(final ObjectPool<T> pool, final float factor) {
+ public static <T> ObjectPool<T> erodingPool(final ObjectPool<T> pool,
+ final float factor) {
if (pool == null) {
throw new IllegalArgumentException("pool must not be null.");
}
@@ -354,77 +443,95 @@ public final class PoolUtils {
}
/**
- * Returns a pool that adaptively decreases it's size when idle objects are no longer needed.
- * This is intended as an always thread-safe alternative to using an idle object evictor
- * provided by many pool implementations. This is also an effective way to shrink FIFO ordered
- * pools that experience load spikes.
- *
- * @param keyedPool the KeyedObjectPool to be decorated so it shrinks it's idle count when
- * possible.
- * @return a pool that adaptively decreases it's size when idle objects are no longer needed.
+ * Returns a pool that adaptively decreases it's size when idle objects are
+ * no longer needed. This is intended as an always thread-safe alternative
+ * to using an idle object evictor provided by many pool implementations.
+ * This is also an effective way to shrink FIFO ordered pools that
+ * experience load spikes.
+ *
+ * @param keyedPool
+ * the KeyedObjectPool to be decorated so it shrinks it's idle
+ * count when possible.
+ * @return a pool that adaptively decreases it's size when idle objects are
+ * no longer needed.
* @see #erodingPool(KeyedObjectPool, float)
* @see #erodingPool(KeyedObjectPool, float, boolean)
* @since Pool 1.4
*/
- public static <K,V> KeyedObjectPool<K,V> erodingPool(final KeyedObjectPool<K,V> keyedPool) {
+ public static <K, V> KeyedObjectPool<K, V> erodingPool(
+ final KeyedObjectPool<K, V> keyedPool) {
return erodingPool(keyedPool, 1f);
}
/**
- * Returns a pool that adaptively decreases it's size when idle objects are no longer needed.
- * This is intended as an always thread-safe alternative to using an idle object evictor
- * provided by many pool implementations. This is also an effective way to shrink FIFO ordered
- * pools that experience load spikes.
- *
+ * Returns a pool that adaptively decreases it's size when idle objects are
+ * no longer needed. This is intended as an always thread-safe alternative
+ * to using an idle object evictor provided by many pool implementations.
+ * This is also an effective way to shrink FIFO ordered pools that
+ * experience load spikes.
* <p>
- * The factor parameter provides a mechanism to tweak the rate at which the pool tries to shrink
- * it's size. Values between 0 and 1 cause the pool to try to shrink it's size more often.
- * Values greater than 1 cause the pool to less frequently try to shrink it's size.
+ * The factor parameter provides a mechanism to tweak the rate at which the
+ * pool tries to shrink it's size. Values between 0 and 1 cause the pool to
+ * try to shrink it's size more often. Values greater than 1 cause the pool
+ * to less frequently try to shrink it's size.
* </p>
*
- * @param keyedPool the KeyedObjectPool to be decorated so it shrinks it's idle count when
- * possible.
- * @param factor a positive value to scale the rate at which the pool tries to reduce it's size.
- * If 0 < factor < 1 then the pool shrinks more aggressively.
- * If 1 < factor then the pool shrinks less aggressively.
- * @return a pool that adaptively decreases it's size when idle objects are no longer needed.
+ * @param keyedPool
+ * the KeyedObjectPool to be decorated so it shrinks it's idle
+ * count when possible.
+ * @param factor
+ * a positive value to scale the rate at which the pool tries to
+ * reduce it's size. If 0 < factor < 1 then the pool
+ * shrinks more aggressively. If 1 < factor then the pool
+ * shrinks less aggressively.
+ * @return a pool that adaptively decreases it's size when idle objects are
+ * no longer needed.
* @see #erodingPool(KeyedObjectPool, float, boolean)
* @since Pool 1.4
*/
- public static <K,V> KeyedObjectPool<K,V> erodingPool(final KeyedObjectPool<K,V> keyedPool, final float factor) {
+ public static <K, V> KeyedObjectPool<K, V> erodingPool(
+ final KeyedObjectPool<K, V> keyedPool, final float factor) {
return erodingPool(keyedPool, factor, false);
}
/**
- * Returns a pool that adaptively decreases it's size when idle objects are no longer needed.
- * This is intended as an always thread-safe alternative to using an idle object evictor
- * provided by many pool implementations. This is also an effective way to shrink FIFO ordered
- * pools that experience load spikes.
- *
+ * Returns a pool that adaptively decreases it's size when idle objects are
+ * no longer needed. This is intended as an always thread-safe alternative
+ * to using an idle object evictor provided by many pool implementations.
+ * This is also an effective way to shrink FIFO ordered pools that
+ * experience load spikes.
* <p>
- * The factor parameter provides a mechanism to tweak the rate at which the pool tries to shrink
- * it's size. Values between 0 and 1 cause the pool to try to shrink it's size more often.
- * Values greater than 1 cause the pool to less frequently try to shrink it's size.
+ * The factor parameter provides a mechanism to tweak the rate at which the
+ * pool tries to shrink it's size. Values between 0 and 1 cause the pool to
+ * try to shrink it's size more often. Values greater than 1 cause the pool
+ * to less frequently try to shrink it's size.
* </p>
- *
* <p>
- * The perKey parameter determines if the pool shrinks on a whole pool basis or a per key basis.
- * When perKey is false, the keys do not have an effect on the rate at which the pool tries to
- * shrink it's size. When perKey is true, each key is shrunk independently.
+ * The perKey parameter determines if the pool shrinks on a whole pool basis
+ * or a per key basis. When perKey is false, the keys do not have an effect
+ * on the rate at which the pool tries to shrink it's size. When perKey is
+ * true, each key is shrunk independently.
* </p>
*
- * @param keyedPool the KeyedObjectPool to be decorated so it shrinks it's idle count when
- * possible.
- * @param factor a positive value to scale the rate at which the pool tries to reduce it's size.
- * If 0 < factor < 1 then the pool shrinks more aggressively.
- * If 1 < factor then the pool shrinks less aggressively.
- * @param perKey when true, each key is treated independently.
- * @return a pool that adaptively decreases it's size when idle objects are no longer needed.
+ * @param keyedPool
+ * the KeyedObjectPool to be decorated so it shrinks it's idle
+ * count when possible.
+ * @param factor
+ * a positive value to scale the rate at which the pool tries to
+ * reduce it's size. If 0 < factor < 1 then the pool
+ * shrinks more aggressively. If 1 < factor then the pool
+ * shrinks less aggressively.
+ * @param perKey
+ * when true, each key is treated independently.
+ * @return a pool that adaptively decreases it's size when idle objects are
+ * no longer needed.
* @see #erodingPool(KeyedObjectPool)
* @see #erodingPool(KeyedObjectPool, float)
* @since Pool 1.4
*/
- public static <K,V> KeyedObjectPool<K,V> erodingPool(final KeyedObjectPool<K,V> keyedPool, final float factor, final boolean perKey) {
+ public static <K, V> KeyedObjectPool<K, V> erodingPool(
+ final KeyedObjectPool<K, V> keyedPool, final float factor,
+ final boolean perKey) {
if (keyedPool == null) {
throw new IllegalArgumentException("keyedPool must not be null.");
}
@@ -432,13 +539,14 @@ public final class PoolUtils {
throw new IllegalArgumentException("factor must be positive.");
}
if (perKey) {
- return new ErodingPerKeyKeyedObjectPool<K,V>(keyedPool, factor);
+ return new ErodingPerKeyKeyedObjectPool<K, V>(keyedPool, factor);
}
- return new ErodingKeyedObjectPool<K,V>(keyedPool, factor);
+ return new ErodingKeyedObjectPool<K, V>(keyedPool, factor);
}
/**
- * Get the <code>Timer</code> for checking keyedPool's idle count. Lazily create the {@link Timer} as needed.
+ * Get the <code>Timer</code> for checking keyedPool's idle count. Lazily
+ * create the {@link Timer} as needed.
*
* @return the {@link Timer} for checking keyedPool's idle count.
* @since Pool 1.3
@@ -452,26 +560,30 @@ public final class PoolUtils {
/**
* Timer task that adds objects to the pool until the number of idle
- * instances reaches the configured minIdle. Note that this is not the
- * same as the pool's minIdle setting.
- *
+ * instances reaches the configured minIdle. Note that this is not the same
+ * as the pool's minIdle setting.
*/
private static class ObjectPoolMinIdleTimerTask<T> extends TimerTask {
- /** Minimum number of idle instances. Not the same as pool.getMinIdle(). */
+ /** Minimum number of idle instances. Not the same as pool.getMinIdle(). */
private final int minIdle;
/** Object pool */
private final ObjectPool<T> pool;
/**
- * Create a new ObjectPoolMinIdleTimerTask for the given pool with the given minIdle setting.
+ * Create a new ObjectPoolMinIdleTimerTask for the given pool with the
+ * given minIdle setting.
*
- * @param pool object pool
- * @param minIdle number of idle instances to maintain
- * @throws IllegalArgumentException if the pool is null
+ * @param pool
+ * object pool
+ * @param minIdle
+ * number of idle instances to maintain
+ * @throws IllegalArgumentException
+ * if the pool is null
*/
- ObjectPoolMinIdleTimerTask(final ObjectPool<T> pool, final int minIdle) throws IllegalArgumentException {
+ ObjectPoolMinIdleTimerTask(final ObjectPool<T> pool, final int minIdle)
+ throws IllegalArgumentException {
if (pool == null) {
throw new IllegalArgumentException("pool must not be null.");
}
@@ -518,31 +630,37 @@ public final class PoolUtils {
/**
* Timer task that adds objects to the pool until the number of idle
- * instances for the given key reaches the configured minIdle. Note that this is not the
- * same as the pool's minIdle setting.
- *
+ * instances for the given key reaches the configured minIdle. Note that
+ * this is not the same as the pool's minIdle setting.
*/
- private static class KeyedObjectPoolMinIdleTimerTask<K,V> extends TimerTask {
- /** Minimum number of idle instances. Not the same as pool.getMinIdle(). */
+ private static class KeyedObjectPoolMinIdleTimerTask<K, V> extends
+ TimerTask {
+ /** Minimum number of idle instances. Not the same as pool.getMinIdle(). */
private final int minIdle;
/** Key to ensure minIdle for */
private final K key;
/** Keyed object pool */
- private final KeyedObjectPool<K,V> keyedPool;
+ private final KeyedObjectPool<K, V> keyedPool;
/**
* Create a new KeyedObjecPoolMinIdleTimerTask.
*
- * @param keyedPool keyed object pool
- * @param key key to ensure minimum number of idle instances
- * @param minIdle minimum number of idle instances
- * @throws IllegalArgumentException if the key is null
+ * @param keyedPool
+ * keyed object pool
+ * @param key
+ * key to ensure minimum number of idle instances
+ * @param minIdle
+ * minimum number of idle instances
+ * @throws IllegalArgumentException
+ * if the key is null
*/
- KeyedObjectPoolMinIdleTimerTask(final KeyedObjectPool<K,V> keyedPool, final K key, final int minIdle) throws IllegalArgumentException {
+ KeyedObjectPoolMinIdleTimerTask(final KeyedObjectPool<K, V> keyedPool,
+ final K key, final int minIdle) throws IllegalArgumentException {
if (keyedPool == null) {
- throw new IllegalArgumentException("keyedPool must not be null.");
+ throw new IllegalArgumentException(
+ "keyedPool must not be null.");
}
this.keyedPool = keyedPool;
this.key = key;
@@ -588,18 +706,23 @@ public final class PoolUtils {
}
/**
- * A synchronized (thread-safe) ObjectPool backed by the specified ObjectPool.
- *
- * <p><b>Note:</b>
- * This should not be used on pool implementations that already provide proper synchronization
- * such as the pools provided in the Commons Pool library. Wrapping a pool that
- * {@link #wait() waits} for poolable objects to be returned before allowing another one to be
- * borrowed with another layer of synchronization will cause liveliness issues or a deadlock.
+ * A synchronized (thread-safe) ObjectPool backed by the specified
+ * ObjectPool.
+ * <p>
+ * <b>Note:</b> This should not be used on pool implementations that already
+ * provide proper synchronization such as the pools provided in the Commons
+ * Pool library. Wrapping a pool that {@link #wait() waits} for poolable
+ * objects to be returned before allowing another one to be borrowed with
+ * another layer of synchronization will cause liveliness issues or a
+ * deadlock.
* </p>
*/
private static class SynchronizedObjectPool<T> implements ObjectPool<T> {
- /** Object whose monitor is used to synchronize methods on the wrapped pool. */
+ /**
+ * Object whose monitor is used to synchronize methods on the wrapped
+ * pool.
+ */
private final ReentrantReadWriteLock readWriteLock = new ReentrantReadWriteLock();
/** the underlying object pool */
@@ -608,10 +731,14 @@ public final class PoolUtils {
/**
* Create a new SynchronizedObjectPool wrapping the given pool.
*
- * @param pool the ObjectPool to be "wrapped" in a synchronized ObjectPool.
- * @throws IllegalArgumentException if the pool is null
+ * @param pool
+ * the ObjectPool to be "wrapped" in a synchronized
+ * ObjectPool.
+ * @throws IllegalArgumentException
+ * if the pool is null
*/
- SynchronizedObjectPool(final ObjectPool<T> pool) throws IllegalArgumentException {
+ SynchronizedObjectPool(final ObjectPool<T> pool)
+ throws IllegalArgumentException {
if (pool == null) {
throw new IllegalArgumentException("pool must not be null.");
}
@@ -622,7 +749,8 @@ public final class PoolUtils {
* {@inheritDoc}
*/
@Override
- public T borrowObject() throws Exception, NoSuchElementException, IllegalStateException {
+ public T borrowObject() throws Exception, NoSuchElementException,
+ IllegalStateException {
WriteLock writeLock = readWriteLock.writeLock();
writeLock.tryLock();
try {
@@ -668,7 +796,8 @@ public final class PoolUtils {
* {@inheritDoc}
*/
@Override
- public void addObject() throws Exception, IllegalStateException, UnsupportedOperationException {
+ public void addObject() throws Exception, IllegalStateException,
+ UnsupportedOperationException {
WriteLock writeLock = readWriteLock.writeLock();
writeLock.tryLock();
try {
@@ -682,7 +811,7 @@ public final class PoolUtils {
* {@inheritDoc}
*/
@Override
- public int getNumIdle() throws UnsupportedOperationException {
+ public int getNumIdle() {
ReadLock readLock = readWriteLock.readLock();
readLock.tryLock();
try {
@@ -696,7 +825,7 @@ public final class PoolUtils {
* {@inheritDoc}
*/
@Override
- public int getNumActive() throws UnsupportedOperationException {
+ public int getNumActive() {
ReadLock readLock = readWriteLock.readLock();
readLock.tryLock();
try {
@@ -750,32 +879,42 @@ public final class PoolUtils {
}
/**
- * A synchronized (thread-safe) KeyedObjectPool backed by the specified KeyedObjectPool.
- *
- * <p><b>Note:</b>
- * This should not be used on pool implementations that already provide proper synchronization
- * such as the pools provided in the Commons Pool library. Wrapping a pool that
- * {@link #wait() waits} for poolable objects to be returned before allowing another one to be
- * borrowed with another layer of synchronization will cause liveliness issues or a deadlock.
+ * A synchronized (thread-safe) KeyedObjectPool backed by the specified
+ * KeyedObjectPool.
+ * <p>
+ * <b>Note:</b> This should not be used on pool implementations that already
+ * provide proper synchronization such as the pools provided in the Commons
+ * Pool library. Wrapping a pool that {@link #wait() waits} for poolable
+ * objects to be returned before allowing another one to be borrowed with
+ * another layer of synchronization will cause liveliness issues or a
+ * deadlock.
* </p>
*/
- private static class SynchronizedKeyedObjectPool<K,V> implements KeyedObjectPool<K,V> {
+ private static class SynchronizedKeyedObjectPool<K, V> implements
+ KeyedObjectPool<K, V> {
- /** Object whose monitor is used to synchronize methods on the wrapped pool. */
+ /**
+ * Object whose monitor is used to synchronize methods on the wrapped
+ * pool.
+ */
private final ReentrantReadWriteLock readWriteLock = new ReentrantReadWriteLock();
/** Underlying object pool */
- private final KeyedObjectPool<K,V> keyedPool;
+ private final KeyedObjectPool<K, V> keyedPool;
/**
* Create a new SynchronizedKeyedObjectPool wrapping the given pool
*
- * @param keyedPool KeyedObjectPool to wrap
- * @throws IllegalArgumentException if keyedPool is null
+ * @param keyedPool
+ * KeyedObjectPool to wrap
+ * @throws IllegalArgumentException
+ * if keyedPool is null
*/
- SynchronizedKeyedObjectPool(final KeyedObjectPool<K,V> keyedPool) throws IllegalArgumentException {
+ SynchronizedKeyedObjectPool(final KeyedObjectPool<K, V> keyedPool)
+ throws IllegalArgumentException {
if (keyedPool == null) {
- throw new IllegalArgumentException("keyedPool must not be null.");
+ throw new IllegalArgumentException(
+ "keyedPool must not be null.");
}
this.keyedPool = keyedPool;
}
@@ -784,7 +923,8 @@ public final class PoolUtils {
* {@inheritDoc}
*/
@Override
- public V borrowObject(final K key) throws Exception, NoSuchElementException, IllegalStateException {
+ public V borrowObject(final K key) throws Exception,
+ NoSuchElementException, IllegalStateException {
WriteLock writeLock = readWriteLock.writeLock();
writeLock.tryLock();
try {
@@ -830,7 +970,8 @@ public final class PoolUtils {
* {@inheritDoc}
*/
@Override
- public void addObject(final K key) throws Exception, IllegalStateException, UnsupportedOperationException {
+ public void addObject(final K key) throws Exception,
+ IllegalStateException, UnsupportedOperationException {
WriteLock writeLock = readWriteLock.writeLock();
writeLock.tryLock();
try {
@@ -844,7 +985,7 @@ public final class PoolUtils {
* {@inheritDoc}
*/
@Override
- public int getNumIdle(final K key) throws UnsupportedOperationException {
+ public int getNumIdle(final K key) {
ReadLock readLock = readWriteLock.readLock();
readLock.tryLock();
try {
@@ -858,7 +999,7 @@ public final class PoolUtils {
* {@inheritDoc}
*/
@Override
- public int getNumActive(final K key) throws UnsupportedOperationException {
+ public int getNumActive(final K key) {
ReadLock readLock = readWriteLock.readLock();
readLock.tryLock();
try {
@@ -872,7 +1013,7 @@ public final class PoolUtils {
* {@inheritDoc}
*/
@Override
- public int getNumIdle() throws UnsupportedOperationException {
+ public int getNumIdle() {
ReadLock readLock = readWriteLock.readLock();
readLock.tryLock();
try {
@@ -886,7 +1027,7 @@ public final class PoolUtils {
* {@inheritDoc}
*/
@Override
- public int getNumActive() throws UnsupportedOperationException {
+ public int getNumActive() {
ReadLock readLock = readWriteLock.readLock();
readLock.tryLock();
try {
@@ -914,7 +1055,8 @@ public final class PoolUtils {
* {@inheritDoc}
*/
@Override
- public void clear(final K key) throws Exception, UnsupportedOperationException {
+ public void clear(final K key) throws Exception,
+ UnsupportedOperationException {
WriteLock writeLock = readWriteLock.writeLock();
writeLock.tryLock();
try {
@@ -954,14 +1096,17 @@ public final class PoolUtils {
}
/**
- * A fully synchronized PoolableObjectFactory that wraps a PoolableObjectFactory and synchronizes
- * access to the wrapped factory methods.
- *
- * <p><b>Note:</b>
- * This should not be used on pool implementations that already provide proper synchronization
- * such as the pools provided in the Commons Pool library. </p>
+ * A fully synchronized PoolableObjectFactory that wraps a
+ * PoolableObjectFactory and synchronizes access to the wrapped factory
+ * methods.
+ * <p>
+ * <b>Note:</b> This should not be used on pool implementations that already
+ * provide proper synchronization such as the pools provided in the Commons
+ * Pool library.
+ * </p>
*/
- private static class SynchronizedPoolableObjectFactory<T> implements PoolableObjectFactory<T> {
+ private static class SynchronizedPoolableObjectFactory<T> implements
+ PoolableObjectFactory<T> {
/** Synchronization lock */
private final WriteLock writeLock = new ReentrantReadWriteLock().writeLock();
@@ -969,12 +1114,16 @@ public final class PoolUtils {
private final PoolableObjectFactory<T> factory;
/**
- * Create a SynchronizedPoolableObjectFactory wrapping the given factory.
+ * Create a SynchronizedPoolableObjectFactory wrapping the given
+ * factory.
*
- * @param factory underlying factory to wrap
- * @throws IllegalArgumentException if the factory is null
+ * @param factory
+ * underlying factory to wrap
+ * @throws IllegalArgumentException
+ * if the factory is null
*/
- SynchronizedPoolableObjectFactory(final PoolableObjectFactory<T> factory) throws IllegalArgumentException {
+ SynchronizedPoolableObjectFactory(final PoolableObjectFactory<T> factory)
+ throws IllegalArgumentException {
if (factory == null) {
throw new IllegalArgumentException("factory must not be null.");
}
@@ -1060,29 +1209,38 @@ public final class PoolUtils {
}
/**
- * A fully synchronized KeyedPoolableObjectFactory that wraps a KeyedPoolableObjectFactory and synchronizes
- * access to the wrapped factory methods.
- *
- * <p><b>Note:</b>
- * This should not be used on pool implementations that already provide proper synchronization
- * such as the pools provided in the Commons Pool library. </p>
+ * A fully synchronized KeyedPoolableObjectFactory that wraps a
+ * KeyedPoolableObjectFactory and synchronizes access to the wrapped factory
+ * methods.
+ * <p>
+ * <b>Note:</b> This should not be used on pool implementations that already
+ * provide proper synchronization such as the pools provided in the Commons
+ * Pool library.
+ * </p>
*/
- private static class SynchronizedKeyedPoolableObjectFactory<K,V> implements KeyedPoolableObjectFactory<K,V> {
+ private static class SynchronizedKeyedPoolableObjectFactory<K, V>
+ implements KeyedPoolableObjectFactory<K, V> {
/** Synchronization lock */
private final WriteLock writeLock = new ReentrantReadWriteLock().writeLock();
/** Wrapped factory */
- private final KeyedPoolableObjectFactory<K,V> keyedFactory;
+ private final KeyedPoolableObjectFactory<K, V> keyedFactory;
/**
- * Create a SynchronizedKeyedPoolableObjectFactory wrapping the given factory.
+ * Create a SynchronizedKeyedPoolableObjectFactory wrapping the given
+ * factory.
*
- * @param keyedFactory underlying factory to wrap
- * @throws IllegalArgumentException if the factory is null
- */
- SynchronizedKeyedPoolableObjectFactory(final KeyedPoolableObjectFactory<K,V> keyedFactory) throws IllegalArgumentException {
+ * @param keyedFactory
+ * underlying factory to wrap
+ * @throws IllegalArgumentException
+ * if the factory is null
+ */
+ SynchronizedKeyedPoolableObjectFactory(
+ final KeyedPoolableObjectFactory<K, V> keyedFactory)
+ throws IllegalArgumentException {
if (keyedFactory == null) {
- throw new IllegalArgumentException("keyedFactory must not be null.");
+ throw new IllegalArgumentException(
+ "keyedFactory must not be null.");
}
this.keyedFactory = keyedFactory;
}
@@ -1166,13 +1324,14 @@ public final class PoolUtils {
}
/**
- * Encapsulate the logic for when the next poolable object should be discarded.
- * Each time update is called, the next time to shrink is recomputed, based on
- * the float factor, number of idle instances in the pool and high water mark.
- * Float factor is assumed to be between 0 and 1. Values closer to 1 cause
- * less frequent erosion events. Erosion event timing also depends on numIdle.
- * When this value is relatively high (close to previously established high water
- * mark), erosion occurs more frequently.
+ * Encapsulate the logic for when the next poolable object should be
+ * discarded. Each time update is called, the next time to shrink is
+ * recomputed, based on the float factor, number of idle instances in the
+ * pool and high water mark. Float factor is assumed to be between 0 and 1.
+ * Values closer to 1 cause less frequent erosion events. Erosion event
+ * timing also depends on numIdle. When this value is relatively high (close
+ * to previously established high water mark), erosion occurs more
+ * frequently.
*/
private static class ErodingFactor {
/** Determines frequency of "erosion" events */
@@ -1187,26 +1346,35 @@ public final class PoolUtils {
/**
* Create a new ErodingFactor with the given erosion factor.
*
- * @param factor erosion factor
+ * @param factor
+ * erosion factor
*/
public ErodingFactor(final float factor) {
this.factor = factor;
- nextShrink = System.currentTimeMillis() + (long)(900000 * factor); // now + 15 min * factor
+ nextShrink = System.currentTimeMillis() + (long) (900000 * factor); // now
+ // +
+ // 15
+ // min
+ // *
+ // factor
idleHighWaterMark = 1;
}
/**
* Updates internal state using the supplied time and numIdle.
*
- * @param now current time
- * @param numIdle number of idle elements in the pool
+ * @param now
+ * current time
+ * @param numIdle
+ * number of idle elements in the pool
*/
public void update(final long now, final int numIdle) {
final int idle = Math.max(0, numIdle);
idleHighWaterMark = Math.max(idle, idleHighWaterMark);
final float maxInterval = 15f;
- final float minutes = maxInterval + ((1f-maxInterval)/idleHighWaterMark) * idle;
- nextShrink = now + (long)(minutes * 60000f * factor);
+ final float minutes = maxInterval +
+ ((1f - maxInterval) / idleHighWaterMark) * idle;
+ nextShrink = now + (long) (minutes * 60000f * factor);
}
/**
@@ -1223,18 +1391,15 @@ public final class PoolUtils {
*/
@Override
public String toString() {
- return "ErodingFactor{" +
- "factor=" + factor +
- ", idleHighWaterMark=" + idleHighWaterMark +
- '}';
+ return "ErodingFactor{" + "factor=" + factor +
+ ", idleHighWaterMark=" + idleHighWaterMark + '}';
}
}
/**
- * Decorates an object pool, adding "eroding" behavior. Based on the
+ * Decorates an object pool, adding "eroding" behavior. Based on the
* configured {@link #factor erosion factor}, objects returning to the pool
* may be invalidated instead of being added to idle capacity.
- *
*/
private static class ErodingObjectPool<T> implements ObjectPool<T> {
/** Underlying object pool */
@@ -1244,10 +1409,14 @@ public final class PoolUtils {
private final ErodingFactor factor;
/**
- * Create an ErodingObjectPool wrapping the given pool using the specified erosion factor.
+ * Create an ErodingObjectPool wrapping the given pool using the
+ * specified erosion factor.
*
- * @param pool underlying pool
- * @param factor erosion factor - determines the frequency of erosion events
+ * @param pool
+ * underlying pool
+ * @param factor
+ * erosion factor - determines the frequency of erosion
+ * events
* @see #factor
*/
public ErodingObjectPool(final ObjectPool<T> pool, final float factor) {
@@ -1259,17 +1428,20 @@ public final class PoolUtils {
* {@inheritDoc}
*/
@Override
- public T borrowObject() throws Exception, NoSuchElementException, IllegalStateException {
+ public T borrowObject() throws Exception, NoSuchElementException,
+ IllegalStateException {
return pool.borrowObject();
}
/**
- * Returns obj to the pool, unless erosion is triggered, in which
- * case obj is invalidated. Erosion is triggered when there are idle instances in
- * the pool and more than the {@link #factor erosion factor}-determined time has elapsed
- * since the last returnObject activation.
+ * Returns obj to the pool, unless erosion is triggered, in which case
+ * obj is invalidated. Erosion is triggered when there are idle
+ * instances in the pool and more than the {@link #factor erosion
+ * factor}-determined time has elapsed since the last returnObject
+ * activation.
*
- * @param obj object to return or invalidate
+ * @param obj
+ * object to return or invalidate
* @see #factor
*/
@Override
@@ -1277,7 +1449,8 @@ public final class PoolUtils {
boolean discard = false;
final long now = System.currentTimeMillis();
synchronized (pool) {
- if (factor.getNextShrink() < now) { // XXX: Pool 3: move test out of sync block
+ if (factor.getNextShrink() < now) { // XXX: Pool 3: move test
+ // out of sync block
final int numIdle = pool.getNumIdle();
if (numIdle > 0) {
discard = true;
@@ -1313,7 +1486,8 @@ public final class PoolUtils {
* {@inheritDoc}
*/
@Override
- public void addObject() throws Exception, IllegalStateException, UnsupportedOperationException {
+ public void addObject() throws Exception, IllegalStateException,
+ UnsupportedOperationException {
pool.addObject();
}
@@ -1321,7 +1495,7 @@ public final class PoolUtils {
* {@inheritDoc}
*/
@Override
- public int getNumIdle() throws UnsupportedOperationException {
+ public int getNumIdle() {
return pool.getNumIdle();
}
@@ -1329,7 +1503,7 @@ public final class PoolUtils {
* {@inheritDoc}
*/
@Override
- public int getNumActive() throws UnsupportedOperationException {
+ public int getNumActive() {
return pool.getNumActive();
}
@@ -1358,47 +1532,56 @@ public final class PoolUtils {
*/
@Override
public String toString() {
- return "ErodingObjectPool{" +
- "factor=" + factor +
- ", pool=" + pool +
- '}';
+ return "ErodingObjectPool{" + "factor=" + factor + ", pool=" +
+ pool + '}';
}
}
/**
- * Decorates a keyed object pool, adding "eroding" behavior. Based on the
+ * Decorates a keyed object pool, adding "eroding" behavior. Based on the
* configured {@link #factor erosion factor}, objects returning to the pool
* may be invalidated instead of being added to idle capacity.
- *
*/
- private static class ErodingKeyedObjectPool<K,V> implements KeyedObjectPool<K,V> {
+ private static class ErodingKeyedObjectPool<K, V> implements
+ KeyedObjectPool<K, V> {
/** Underlying pool */
- private final KeyedObjectPool<K,V> keyedPool;
+ private final KeyedObjectPool<K, V> keyedPool;
/** Erosion factor */
private final ErodingFactor erodingFactor;
/**
- * Create an ErodingObjectPool wrapping the given pool using the specified erosion factor.
+ * Create an ErodingObjectPool wrapping the given pool using the
+ * specified erosion factor.
*
- * @param keyedPool underlying pool
- * @param factor erosion factor - determines the frequency of erosion events
+ * @param keyedPool
+ * underlying pool
+ * @param factor
+ * erosion factor - determines the frequency of erosion
+ * events
* @see #erodingFactor
*/
- public ErodingKeyedObjectPool(final KeyedObjectPool<K,V> keyedPool, final float factor) {
+ public ErodingKeyedObjectPool(final KeyedObjectPool<K, V> keyedPool,
+ final float factor) {
this(keyedPool, new ErodingFactor(factor));
}
/**
- * Create an ErodingObjectPool wrapping the given pool using the specified erosion factor.
+ * Create an ErodingObjectPool wrapping the given pool using the
+ * specified erosion factor.
*
- * @param keyedPool underlying pool - must not be null
- * @param erodingFactor erosion factor - determines the frequency of erosion events
+ * @param keyedPool
+ * underlying pool - must not be null
+ * @param erodingFactor
+ * erosion factor - determines the frequency of erosion
+ * events
* @see #factor
*/
- protected ErodingKeyedObjectPool(final KeyedObjectPool<K,V> keyedPool, final ErodingFactor erodingFactor) {
+ protected ErodingKeyedObjectPool(final KeyedObjectPool<K, V> keyedPool,
+ final ErodingFactor erodingFactor) {
if (keyedPool == null) {
- throw new IllegalArgumentException("keyedPool must not be null.");
+ throw new IllegalArgumentException(
+ "keyedPool must not be null.");
}
this.keyedPool = keyedPool;
this.erodingFactor = erodingFactor;
@@ -1408,18 +1591,22 @@ public final class PoolUtils {
* {@inheritDoc}
*/
@Override
- public V borrowObject(final K key) throws Exception, NoSuchElementException, IllegalStateException {
+ public V borrowObject(final K key) throws Exception,
+ NoSuchElementException, IllegalStateException {
return keyedPool.borrowObject(key);
}
/**
- * Returns obj to the pool, unless erosion is triggered, in which
- * case obj is invalidated. Erosion is triggered when there are idle instances in
- * the pool associated with the given key and more than the configured {@link #erodingFactor erosion factor}
- * time has elapsed since the last returnObject activation.
+ * Returns obj to the pool, unless erosion is triggered, in which case
+ * obj is invalidated. Erosion is triggered when there are idle
+ * instances in the pool associated with the given key and more than the
+ * configured {@link #erodingFactor erosion factor} time has elapsed
+ * since the last returnObject activation.
*
- * @param obj object to return or invalidate
- * @param key key
+ * @param obj
+ * object to return or invalidate
+ * @param key
+ * key
* @see #erodingFactor
*/
@Override
@@ -1450,7 +1637,9 @@ public final class PoolUtils {
/**
* Returns the eroding factor for the given key
- * @param key key
+ *
+ * @param key
+ * key
* @return eroding factor for the given keyed pool
*/
protected ErodingFactor getErodingFactor(final K key) {
@@ -1473,7 +1662,8 @@ public final class PoolUtils {
* {@inheritDoc}
*/
@Override
- public void addObject(final K key) throws Exception, IllegalStateException, UnsupportedOperationException {
+ public void addObject(final K key) throws Exception,
+ IllegalStateException, UnsupportedOperationException {
keyedPool.addObject(key);
}
@@ -1481,7 +1671,7 @@ public final class PoolUtils {
* {@inheritDoc}
*/
@Override
- public int getNumIdle() throws UnsupportedOperationException {
+ public int getNumIdle() {
return keyedPool.getNumIdle();
}
@@ -1489,7 +1679,7 @@ public final class PoolUtils {
* {@inheritDoc}
*/
@Override
- public int getNumIdle(final K key) throws UnsupportedOperationException {
+ public int getNumIdle(final K key) {
return keyedPool.getNumIdle(key);
}
@@ -1497,7 +1687,7 @@ public final class PoolUtils {
* {@inheritDoc}
*/
@Override
- public int getNumActive() throws UnsupportedOperationException {
+ public int getNumActive() {
return keyedPool.getNumActive();
}
@@ -1505,7 +1695,7 @@ public final class PoolUtils {
* {@inheritDoc}
*/
@Override
- public int getNumActive(final K key) throws UnsupportedOperationException {
+ public int getNumActive(final K key) {
return keyedPool.getNumActive(key);
}
@@ -1521,7 +1711,8 @@ public final class PoolUtils {
* {@inheritDoc}
*/
@Override
- public void clear(final K key) throws Exception, UnsupportedOperationException {
+ public void clear(final K key) throws Exception,
+ UnsupportedOperationException {
keyedPool.clear(key);
}
@@ -1542,7 +1733,7 @@ public final class PoolUtils {
*
* @return the keyed pool that this ErodingKeyedObjectPool wraps
*/
- protected KeyedObjectPool<K,V> getKeyedPool() {
+ protected KeyedObjectPool<K, V> getKeyedPool() {
return keyedPool;
}
@@ -1551,31 +1742,35 @@ public final class PoolUtils {
*/
@Override
public String toString() {
- return "ErodingKeyedObjectPool{" +
- "erodingFactor=" + erodingFactor +
- ", keyedPool=" + keyedPool +
- '}';
+ return "ErodingKeyedObjectPool{" + "erodingFactor=" +
+ erodingFactor + ", keyedPool=" + keyedPool + '}';
}
}
/**
- * Extends ErodingKeyedObjectPool to allow erosion to take place on a per-key
- * basis. Timing of erosion events is tracked separately for separate keyed pools.
+ * Extends ErodingKeyedObjectPool to allow erosion to take place on a
+ * per-key basis. Timing of erosion events is tracked separately for
+ * separate keyed pools.
*/
- private static class ErodingPerKeyKeyedObjectPool<K,V> extends ErodingKeyedObjectPool<K,V> {
+ private static class ErodingPerKeyKeyedObjectPool<K, V> extends
+ ErodingKeyedObjectPool<K, V> {
/** Erosion factor - same for all pools */
private final float factor;
/** Map of ErodingFactor instances keyed on pool keys */
- private final Map<K,ErodingFactor> factors = Collections.synchronizedMap(new HashMap<K,ErodingFactor>());
+ private final Map<K, ErodingFactor> factors = Collections.synchronizedMap(new HashMap<K, ErodingFactor>());
/**
- * Create a new ErordingPerKeyKeyedObjectPool decorating the given keyed pool with
- * the specified erosion factor.
- * @param keyedPool underlying keyed pool
- * @param factor erosion factor
+ * Create a new ErordingPerKeyKeyedObjectPool decorating the given keyed
+ * pool with the specified erosion factor.
+ *
+ * @param keyedPool
+ * underlying keyed pool
+ * @param factor
+ * erosion factor
*/
- public ErodingPerKeyKeyedObjectPool(final KeyedObjectPool<K,V> keyedPool, final float factor) {
+ public ErodingPerKeyKeyedObjectPool(
+ final KeyedObjectPool<K, V> keyedPool, final float factor) {
super(keyedPool, null);
this.factor = factor;
}
@@ -1600,10 +1795,8 @@ public final class PoolUtils {
*/
@Override
public String toString() {
- return "ErodingPerKeyKeyedObjectPool{" +
- "factor=" + factor +
- ", keyedPool=" + getKeyedPool() +
- '}';
+ return "ErodingPerKeyKeyedObjectPool{" + "factor=" + factor +
+ ", keyedPool=" + getKeyedPool() + '}';
}
}
}
\ No newline at end of file
Modified: commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/PoolableObjectFactory.java
URL: http://svn.apache.org/viewvc/commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/PoolableObjectFactory.java?rev=1333854&r1=1333853&r2=1333854&view=diff
==============================================================================
--- commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/PoolableObjectFactory.java (original)
+++ commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/PoolableObjectFactory.java Fri May 4 10:10:13 2012
@@ -14,55 +14,47 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
-
package org.apache.commons.pool2;
/**
- * An interface defining life-cycle methods for
- * instances to be served by an {@link ObjectPool}.
+ * An interface defining life-cycle methods for instances to be served by an
+ * {@link ObjectPool}.
* <p>
- * By contract, when an {@link ObjectPool}
- * delegates to a {@link PoolableObjectFactory},
+ * By contract, when an {@link ObjectPool} delegates to a
+ * {@link PoolableObjectFactory},
* <ol>
* <li>
- * {@link #makeObject makeObject}
- * is called whenever a new instance is needed.
+ * {@link #makeObject} is called whenever a new instance is needed.
* </li>
* <li>
- * {@link #activateObject activateObject}
- * is invoked on every instance that has been
+ * {@link #activateObject} is invoked on every instance that has been
* {@link #passivateObject passivated} before it is
* {@link ObjectPool#borrowObject borrowed} from the pool.
* </li>
* <li>
- * {@link #validateObject validateObject}
- * is invoked on {@link #activateObject activated} instances to make sure
- * they can be {@link ObjectPool#borrowObject borrowed} from the pool.
- * <code>validateObject</code> <strong>may</strong> also be used to test an
- * instance being {@link ObjectPool#returnObject returned} to the pool
+ * {@link #validateObject} is invoked on {@link #activateObject activated}
+ * instances to make sure they can be {@link ObjectPool#borrowObject borrowed}
+ * from the pool. {@link #validateObject} <strong>may</strong> also be used to
+ * test an instance being {@link ObjectPool#returnObject returned} to the pool
* before it is {@link #passivateObject passivated}. It will only be invoked
* on an activated instance.
* </li>
* <li>
- * {@link #passivateObject passivateObject}
- * is invoked on every instance when it is returned to the pool.
+ * {@link #passivateObject} is invoked on every instance when it is returned
+ * to the pool.
* </li>
* <li>
- * {@link #destroyObject destroyObject}
- * is invoked on every instance when it is being "dropped" from the
- * pool (whether due to the response from <code>validateObject</code>,
- * or for reasons specific to the pool implementation.) There is no
- * guarantee that the instance being destroyed will
- * be considered active, passive or in a generally consistent state.
+ * {@link #destroyObject} is invoked on every instance when it is being
+ * "dropped" from the pool (whether due to the response from
+ * {@link #validateObject}, or for reasons specific to the pool
+ * implementation.) There is no guarantee that the instance being destroyed
+ * will be considered active, passive or in a generally consistent state.
* </li>
* </ol>
- * </p>
- * <p>
* {@link PoolableObjectFactory} must be thread-safe. The only promise
* an {@link ObjectPool} makes is that the same instance of an object will not
* be passed to more than one method of a <code>PoolableObjectFactory</code>
* at a time.
- * </p>
*
* @param <T> Type of element managed in this factory.
*
@@ -73,13 +65,13 @@ package org.apache.commons.pool2;
*/
public interface PoolableObjectFactory<T> {
/**
- * Creates an instance that can be served by the pool.
- * Instances returned from this method should be in the
- * same state as if they had been
- * {@link #activateObject activated}. They will not be
- * activated before being served by the pool.
+ * Creates an instance that can be served by the pool. Instances returned from
+ * this method should be in the same state as if they had been
+ * {@link #activateObject activated}. They will not be activated before being
+ * served by the pool.
*
* @return an instance that can be served by the pool.
+ *
* @throws Exception if there is a problem creating a new instance,
* this will be propagated to the code requesting an object.
*/
@@ -88,19 +80,19 @@ public interface PoolableObjectFactory<T
/**
* Destroys an instance no longer needed by the pool.
* <p>
- * It is important for implementations of this method to be aware
- * that there is no guarantee about what state <code>obj</code>
- * will be in and the implementation should be prepared to handle
- * unexpected errors.
- * </p>
+ * It is important for implementations of this method to be aware that there
+ * is no guarantee about what state <code>obj</code> will be in and the
+ * implementation should be prepared to handle unexpected errors.
* <p>
- * Also, an implementation must take in to consideration that
- * instances lost to the garbage collector may never be destroyed.
+ * Also, an implementation must take in to consideration that instances lost
+ * to the garbage collector may never be destroyed.
* </p>
*
* @param obj the instance to be destroyed
+ *
* @throws Exception should be avoided as it may be swallowed by
* the pool implementation.
+ *
* @see #validateObject
* @see ObjectPool#invalidateObject
*/
@@ -108,9 +100,9 @@ public interface PoolableObjectFactory<T
/**
* Ensures that the instance is safe to be returned by the pool.
- * Returns <code>false</code> if <code>obj</code> should be destroyed.
*
* @param obj the instance to be validated
+ *
* @return <code>false</code> if <code>obj</code> is not valid and should
* be dropped from the pool, <code>true</code> otherwise.
*/
@@ -120,8 +112,10 @@ public interface PoolableObjectFactory<T
* Reinitialize an instance to be returned by the pool.
*
* @param obj the instance to be activated
+ *
* @throws Exception if there is a problem activating <code>obj</code>,
* this exception may be swallowed by the pool.
+ *
* @see #destroyObject
*/
void activateObject(T obj) throws Exception;
@@ -130,8 +124,10 @@ public interface PoolableObjectFactory<T
* Uninitialize an instance to be returned to the idle object pool.
*
* @param obj the instance to be passivated
+ *
* @throws Exception if there is a problem passivating <code>obj</code>,
* this exception may be swallowed by the pool.
+ *
* @see #destroyObject
*/
void passivateObject(T obj) throws Exception;
Modified: commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/impl/SoftReferenceObjectPool.java
URL: http://svn.apache.org/viewvc/commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/impl/SoftReferenceObjectPool.java?rev=1333854&r1=1333853&r2=1333854&view=diff
==============================================================================
--- commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/impl/SoftReferenceObjectPool.java (original)
+++ commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/impl/SoftReferenceObjectPool.java Fri May 4 10:10:13 2012
@@ -290,12 +290,9 @@ public class SoftReferenceObjectPool<T>
* Calling {@link #addObject} or {@link #borrowObject} after invoking this
* method on a pool will cause them to throw an
* {@link IllegalStateException}.
- *
- * @throws Exception
- * never - exceptions clearing the pool are swallowed
*/
@Override
- public void close() throws Exception {
+ public void close() {
super.close();
clear();
}