org.apache.commons.pool2

Class PoolUtils

java.lang.Object

org.apache.commons.pool2.PoolUtils

public final class PoolUtils
extends java.lang.Object

This class consists exclusively of static methods that operate on or return ObjectPool or KeyedObjectPool related interfaces.

Since:

2.0

Version:

$Revision: 1566584 $

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
private static class	PoolUtils.ErodingFactor Encapsulate the logic for when the next poolable object should be discarded.
private static class	PoolUtils.ErodingKeyedObjectPool<K,V> Decorates a keyed object pool, adding "eroding" behavior.
private static class	PoolUtils.ErodingObjectPool<T> Decorates an object pool, adding "eroding" behavior.
private static class	PoolUtils.ErodingPerKeyKeyedObjectPool<K,V> Extends ErodingKeyedObjectPool to allow erosion to take place on a per-key basis.
private static class	PoolUtils.KeyedObjectPoolMinIdleTimerTask<K,V> Timer task that adds objects to the pool until the number of idle instances for the given key reaches the configured minIdle.
private static class	PoolUtils.ObjectPoolMinIdleTimerTask<T> Timer task that adds objects to the pool until the number of idle instances reaches the configured minIdle.
private static class	PoolUtils.SynchronizedKeyedObjectPool<K,V> A synchronized (thread-safe) KeyedObjectPool backed by the specified KeyedObjectPool.
private static class	PoolUtils.SynchronizedKeyedPooledObjectFactory<K,V> A fully synchronized KeyedPooledObjectFactory that wraps a KeyedPooledObjectFactory and synchronizes access to the wrapped factory methods.
private static class	PoolUtils.SynchronizedObjectPool<T> A synchronized (thread-safe) ObjectPool backed by the specified ObjectPool.
private static class	PoolUtils.SynchronizedPooledObjectFactory<T> A fully synchronized PooledObjectFactory that wraps a PooledObjectFactory and synchronizes access to the wrapped factory methods.
(package private) static class	PoolUtils.TimerHolder Timer used to periodically check pools idle object count.

Constructor Summary

Constructors

Constructor and Description
PoolUtils() PoolUtils instances should NOT be constructed in standard programming.

Method Summary

Modifier and Type	Method and Description
static <K,V> java.util.Map<K,java.util.TimerTask>	checkMinIdle(KeyedObjectPool<K,V> keyedPool, java.util.Collection<K> keys, int minIdle, long period) Periodically check the idle object count for each key in the Collection keys in the keyedPool.
static <K,V> java.util.TimerTask	checkMinIdle(KeyedObjectPool<K,V> keyedPool, K key, int minIdle, long period) Periodically check the idle object count for the key in the keyedPool.
static <T> java.util.TimerTask	checkMinIdle(ObjectPool<T> pool, int minIdle, long period) Periodically check the idle object count for the pool.
static void	checkRethrow(java.lang.Throwable t) Should the supplied Throwable be re-thrown (eg if it is an instance of one of the Throwables that should never be swallowed).
static <K,V> KeyedObjectPool<K,V>	erodingPool(KeyedObjectPool<K,V> keyedPool) Returns a pool that adaptively decreases its size when idle objects are no longer needed.
static <K,V> KeyedObjectPool<K,V>	erodingPool(KeyedObjectPool<K,V> keyedPool, float factor) Returns a pool that adaptively decreases its size when idle objects are no longer needed.
static <K,V> KeyedObjectPool<K,V>	erodingPool(KeyedObjectPool<K,V> keyedPool, float factor, boolean perKey) Returns a pool that adaptively decreases its size when idle objects are no longer needed.
static <T> ObjectPool<T>	erodingPool(ObjectPool<T> pool) Returns a pool that adaptively decreases its size when idle objects are no longer needed.
static <T> ObjectPool<T>	erodingPool(ObjectPool<T> pool, float factor) Returns a pool that adaptively decreases its size when idle objects are no longer needed.
private static java.util.Timer	getMinIdleTimer() Get the Timer for checking keyedPool's idle count.
static <K,V> void	prefill(KeyedObjectPool<K,V> keyedPool, java.util.Collection<K> keys, int count) Call addObject(Object) on keyedPool with each key in keys for count number of times.
static <K,V> void	prefill(KeyedObjectPool<K,V> keyedPool, K key, int count) Call addObject(Object) on keyedPool with key count number of times.
static <T> void	prefill(ObjectPool<T> pool, int count) Call addObject() on pool count number of times.
static <K,V> KeyedPooledObjectFactory<K,V>	synchronizedKeyedPooledFactory(KeyedPooledObjectFactory<K,V> keyedFactory) Returns a synchronized (thread-safe) KeyedPooledObjectFactory backed by the specified KeyedPoolableObjectFactory.
static <K,V> KeyedObjectPool<K,V>	synchronizedPool(KeyedObjectPool<K,V> keyedPool) Returns a synchronized (thread-safe) KeyedObjectPool backed by the specified KeyedObjectPool.
static <T> ObjectPool<T>	synchronizedPool(ObjectPool<T> pool) Returns a synchronized (thread-safe) ObjectPool backed by the specified ObjectPool.
static <T> PooledObjectFactory<T>	synchronizedPooledFactory(PooledObjectFactory<T> factory) Returns a synchronized (thread-safe) PooledObjectFactory backed by the specified PooledObjectFactory.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

PoolUtils

public PoolUtils()

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.

Method Detail

checkRethrow

public static void checkRethrow(java.lang.Throwable t)

Should the supplied Throwable be re-thrown (eg if it is an instance of 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.

Parameters:

t - The Throwable to check

Throws:

java.lang.ThreadDeath - if that is passed in

java.lang.VirtualMachineError - if that is passed in

checkMinIdle

public static <T> java.util.TimerTask checkMinIdle(ObjectPool<T> pool,
                                                   int minIdle,
                                                   long period)
                                            throws java.lang.IllegalArgumentException

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 ObjectPool.addObject() then no more checks will be performed.

Type Parameters:

T - the type of objects in the pool

Parameters:

pool - the pool to check periodically.

minIdle - if the ObjectPool.getNumIdle() is less than this then add an idle object.

period - the frequency to check the number of idle objects in a pool, see Timer.schedule(TimerTask, long, long).

Returns:

the TimerTask that will periodically check the pools idle object count.

Throws:

java.lang.IllegalArgumentException - when pool is null or when minIdle is negative or when period isn't valid for Timer.schedule(TimerTask, long, long)

checkMinIdle

public static <K,V> java.util.TimerTask checkMinIdle(KeyedObjectPool<K,V> keyedPool,
                                                     K key,
                                                     int minIdle,
                                                     long period)
                                              throws java.lang.IllegalArgumentException

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 KeyedObjectPool.addObject(Object) then no more checks for that key will be performed.

Type Parameters:

K - the type of the pool key

V - the type of pool entries

Parameters:

keyedPool - the keyedPool to check periodically.

key - the key to check the idle count of.

minIdle - if the KeyedObjectPool.getNumIdle(Object) is less than this then add an idle object.

period - the frequency to check the number of idle objects in a keyedPool, see Timer.schedule(TimerTask, long, long).

Returns:

the TimerTask that will periodically check the pools idle object count.

Throws:

java.lang.IllegalArgumentException - when keyedPool, key is null or when minIdle is negative or when period isn't valid for Timer.schedule(TimerTask, long, long).

checkMinIdle

public static <K,V> java.util.Map<K,java.util.TimerTask> checkMinIdle(KeyedObjectPool<K,V> keyedPool,
                                                                      java.util.Collection<K> keys,
                                                                      int minIdle,
                                                                      long period)
                                                               throws java.lang.IllegalArgumentException

Periodically check the idle object count for each key in the Collection keys in the keyedPool. At most one idle object will be added per period.

Type Parameters:

K - the type of the pool key

V - the type of pool entries

Parameters:

keyedPool - the keyedPool to check periodically.

keys - a collection of keys to check the idle object count.

minIdle - if the KeyedObjectPool.getNumIdle(Object) is less than this then add an idle object.

period - the frequency to check the number of idle objects in a keyedPool, see Timer.schedule(TimerTask, long, long).

Returns:

a Map of key and TimerTask pairs that will periodically check the pools idle object count.

Throws:

java.lang.IllegalArgumentException - when keyedPool, keys, or any of the values in the collection is null or when minIdle is negative or when period isn't valid for Timer.schedule(TimerTask, long, long) .

See Also:

checkMinIdle(KeyedObjectPool, Object, int, long)

prefill

public static <T> void prefill(ObjectPool<T> pool,
                               int count)
                        throws java.lang.Exception,
                               java.lang.IllegalArgumentException

Call addObject() on pool count number of times.

Type Parameters:

T - the type of objects in the pool

Parameters:

pool - the pool to prefill.

count - the number of idle objects to add.

Throws:

java.lang.Exception - when ObjectPool.addObject() fails.

java.lang.IllegalArgumentException - when pool is null.

prefill

public static <K,V> void prefill(KeyedObjectPool<K,V> keyedPool,
                                 K key,
                                 int count)
                          throws java.lang.Exception,
                                 java.lang.IllegalArgumentException

Call addObject(Object) on keyedPool with key count number of times.

Type Parameters:

K - the type of the pool key

V - the type of pool entries

Parameters:

keyedPool - the keyedPool to prefill.

key - the key to add objects for.

count - the number of idle objects to add for key.

Throws:

java.lang.Exception - when KeyedObjectPool.addObject(Object) fails.

java.lang.IllegalArgumentException - when keyedPool or key is null.

prefill

public static <K,V> void prefill(KeyedObjectPool<K,V> keyedPool,
                                 java.util.Collection<K> keys,
                                 int count)
                          throws java.lang.Exception,
                                 java.lang.IllegalArgumentException

Call addObject(Object) on keyedPool with each key in keys for count number of times. This has the same effect as calling prefill(KeyedObjectPool, Object, int) for each key in the keys collection.

Type Parameters:

K - the type of the pool key

V - the type of pool entries

Parameters:

keyedPool - the keyedPool to prefill.

keys - Collection of keys to add objects for.

count - the number of idle objects to add for each key.

Throws:

java.lang.Exception - when KeyedObjectPool.addObject(Object) fails.

java.lang.IllegalArgumentException - when keyedPool, keys, or any value in keys is null.

See Also:

prefill(KeyedObjectPool, Object, int)

synchronizedPool

public static <T> ObjectPool<T> synchronizedPool(ObjectPool<T> pool)

Returns a synchronized (thread-safe) ObjectPool backed by the specified ObjectPool.

Note: 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 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.

Type Parameters:

T - the type of objects in the pool

Parameters:

pool - the ObjectPool to be "wrapped" in a synchronized ObjectPool.

Returns:

a synchronized view of the specified ObjectPool.

synchronizedPool

public static <K,V> KeyedObjectPool<K,V> synchronizedPool(KeyedObjectPool<K,V> keyedPool)

Returns a synchronized (thread-safe) KeyedObjectPool backed by the specified KeyedObjectPool.

Note: 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 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.

Type Parameters:

K - the type of the pool key

V - the type of pool entries

Parameters:

keyedPool - the KeyedObjectPool to be "wrapped" in a synchronized KeyedObjectPool.

Returns:

a synchronized view of the specified KeyedObjectPool.

synchronizedPooledFactory

public static <T> PooledObjectFactory<T> synchronizedPooledFactory(PooledObjectFactory<T> factory)

Returns a synchronized (thread-safe) PooledObjectFactory backed by the specified PooledObjectFactory.

Type Parameters:

T - the type of objects in the pool

Parameters:

factory - the PooledObjectFactory to be "wrapped" in a synchronized PooledObjectFactory.

Returns:

a synchronized view of the specified PooledObjectFactory.

synchronizedKeyedPooledFactory

public static <K,V> KeyedPooledObjectFactory<K,V> synchronizedKeyedPooledFactory(KeyedPooledObjectFactory<K,V> keyedFactory)

Returns a synchronized (thread-safe) KeyedPooledObjectFactory backed by the specified KeyedPoolableObjectFactory.

Type Parameters:

K - the type of the pool key

V - the type of pool entries

Parameters:

keyedFactory - the KeyedPooledObjectFactory to be "wrapped" in a synchronized KeyedPooledObjectFactory.

Returns:

a synchronized view of the specified KeyedPooledObjectFactory.

erodingPool

public static <T> ObjectPool<T> erodingPool(ObjectPool<T> pool)

Returns a pool that adaptively decreases its 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.

Type Parameters:

T - the type of objects in the pool

Parameters:

pool - the ObjectPool to be decorated so it shrinks its idle count when possible.

Returns:

a pool that adaptively decreases its size when idle objects are no longer needed.

See Also:

erodingPool(ObjectPool, float)

erodingPool

public static <T> ObjectPool<T> erodingPool(ObjectPool<T> pool,
                                            float factor)

Returns a pool that adaptively decreases its 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.

The factor parameter provides a mechanism to tweak the rate at which the pool tries to shrink its size. Values between 0 and 1 cause the pool to try to shrink its size more often. Values greater than 1 cause the pool to less frequently try to shrink its size.

Type Parameters:

T - the type of objects in the pool

Parameters:

pool - the ObjectPool to be decorated so it shrinks its idle count when possible.

factor - a positive value to scale the rate at which the pool tries to reduce its size. If 0 < factor < 1 then the pool shrinks more aggressively. If 1 < factor then the pool shrinks less aggressively.

Returns:

a pool that adaptively decreases its size when idle objects are no longer needed.

See Also:

erodingPool(ObjectPool)

erodingPool

public static <K,V> KeyedObjectPool<K,V> erodingPool(KeyedObjectPool<K,V> keyedPool)

Returns a pool that adaptively decreases its 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.

Type Parameters:

K - the type of the pool key

V - the type of pool entries

Parameters:

keyedPool - the KeyedObjectPool to be decorated so it shrinks its idle count when possible.

Returns:

a pool that adaptively decreases its size when idle objects are no longer needed.

See Also:

erodingPool(KeyedObjectPool, float), erodingPool(KeyedObjectPool, float, boolean)

erodingPool

public static <K,V> KeyedObjectPool<K,V> erodingPool(KeyedObjectPool<K,V> keyedPool,
                                                     float factor)

Returns a pool that adaptively decreases its 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.

The factor parameter provides a mechanism to tweak the rate at which the pool tries to shrink its size. Values between 0 and 1 cause the pool to try to shrink its size more often. Values greater than 1 cause the pool to less frequently try to shrink its size.

Type Parameters:

K - the type of the pool key

V - the type of pool entries

Parameters:

keyedPool - the KeyedObjectPool to be decorated so it shrinks its idle count when possible.

factor - a positive value to scale the rate at which the pool tries to reduce its size. If 0 < factor < 1 then the pool shrinks more aggressively. If 1 < factor then the pool shrinks less aggressively.

Returns:

a pool that adaptively decreases its size when idle objects are no longer needed.

See Also:

erodingPool(KeyedObjectPool, float, boolean)

erodingPool

public static <K,V> KeyedObjectPool<K,V> erodingPool(KeyedObjectPool<K,V> keyedPool,
                                                     float factor,
                                                     boolean perKey)

Returns a pool that adaptively decreases its 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.

The factor parameter provides a mechanism to tweak the rate at which the pool tries to shrink its size. Values between 0 and 1 cause the pool to try to shrink its size more often. Values greater than 1 cause the pool to less frequently try to shrink its size.

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 its size. When perKey is true, each key is shrunk independently.

Type Parameters:

K - the type of the pool key

V - the type of pool entries

Parameters:

keyedPool - the KeyedObjectPool to be decorated so it shrinks its idle count when possible.

factor - a positive value to scale the rate at which the pool tries to reduce its size. If 0 < factor < 1 then the pool shrinks more aggressively. If 1 < factor then the pool shrinks less aggressively.

perKey - when true, each key is treated independently.

Returns:

a pool that adaptively decreases its size when idle objects are no longer needed.

See Also:

erodingPool(KeyedObjectPool), erodingPool(KeyedObjectPool, float)

getMinIdleTimer

private static java.util.Timer getMinIdleTimer()

Get the Timer for checking keyedPool's idle count.

Returns:

the Timer for checking keyedPool's idle count.