Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.apache.commons.pool
Class PoolUtils

    java.lang.Object
      org.apache.commons.pool.PoolUtils

    public final class PoolUtils

extends Object

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

Since:
  Pool 1.3
Version:
  $Revision: 1086470 $ $Date: 2011-03-28 21:30:47 -0700 (Mon, 28 Mar 2011) $
Author:
  Sandy McArthur

Constructor Summary
`PoolUtils()` PoolUtils instances should NOT be constructed in standard programming.

Method Summary
`static ObjectPool` | `adapt(KeyedObjectPool keyedPool)` Adapt a `KeyedObjectPool` instance to work where an `ObjectPool` is needed.
`static ObjectPool` | `adapt(KeyedObjectPool keyedPool, Object key)` Adapt a `KeyedObjectPool` instance to work where an `ObjectPool` is needed using the specified `key` when delegating.
`static PoolableObjectFactory` | `adapt(KeyedPoolableObjectFactory keyedFactory)` Adapt a `KeyedPoolableObjectFactory` instance to work where a `PoolableObjectFactory` is needed.
`static PoolableObjectFactory` | `adapt(KeyedPoolableObjectFactory keyedFactory, Object key)` Adapt a `KeyedPoolableObjectFactory` instance to work where a `PoolableObjectFactory` is needed using the specified `key` when delegating.
`static KeyedObjectPool` | `adapt(ObjectPool pool)` Adapt an `ObjectPool` to work where an `KeyedObjectPool` is needed.
`static KeyedPoolableObjectFactory` | `adapt(PoolableObjectFactory factory)` Adapt a `PoolableObjectFactory` instance to work where a `KeyedPoolableObjectFactory` is needed.
`static KeyedObjectPool` | `checkedPool(KeyedObjectPool keyedPool, Class type)` Wraps a `KeyedObjectPool` and dynamically checks the type of objects borrowed and returned to the keyedPool.
`static ObjectPool` | `checkedPool(ObjectPool pool, Class type)` Wraps an `ObjectPool` and dynamically checks the type of objects borrowed and returned to the pool.
`static Map` | `checkMinIdle(KeyedObjectPool keyedPool, Collection keys, int minIdle, long period)` Periodically check the idle object count for each key in the `Collection` `keys` in the keyedPool.
`static TimerTask` | `checkMinIdle(KeyedObjectPool keyedPool, Object key, int minIdle, long period)` Periodically check the idle object count for the key in the keyedPool.
`static TimerTask` | `checkMinIdle(ObjectPool pool, int minIdle, long period)` Periodically check the idle object count for the pool.
`static void` | `checkRethrow(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 KeyedObjectPool` | `erodingPool(KeyedObjectPool keyedPool)` Returns a pool that adaptively decreases it's size when idle objects are no longer needed.
`static KeyedObjectPool` | `erodingPool(KeyedObjectPool keyedPool, float factor)` Returns a pool that adaptively decreases it's size when idle objects are no longer needed.
`static KeyedObjectPool` | `erodingPool(KeyedObjectPool keyedPool, float factor, boolean perKey)` Returns a pool that adaptively decreases it's size when idle objects are no longer needed.
`static ObjectPool` | `erodingPool(ObjectPool pool)` Returns a pool that adaptively decreases it's size when idle objects are no longer needed.
`static ObjectPool` | `erodingPool(ObjectPool pool, float factor)` Returns a pool that adaptively decreases it's size when idle objects are no longer needed.
`static void` | `prefill(KeyedObjectPool keyedPool, Collection keys, int count)` Call `addObject(Object)` on `keyedPool` with each key in `keys` for `count` number of times.
`static void` | `prefill(KeyedObjectPool keyedPool, Object key, int count)` Call `addObject(Object)` on `keyedPool` with `key` `count` number of times.
`static void` | `prefill(ObjectPool pool, int count)` Call `addObject()` on `pool` `count` number of times.
`static KeyedObjectPool` | `synchronizedPool(KeyedObjectPool keyedPool)` Returns a synchronized (thread-safe) KeyedObjectPool backed by the specified KeyedObjectPool.
`static ObjectPool` | `synchronizedPool(ObjectPool pool)` Returns a synchronized (thread-safe) ObjectPool backed by the specified ObjectPool.
`static KeyedPoolableObjectFactory` | `synchronizedPoolableFactory(KeyedPoolableObjectFactory keyedFactory)` Returns a synchronized (thread-safe) KeyedPoolableObjectFactory backed by the specified KeyedPoolableObjectFactory.
`static PoolableObjectFactory` | `synchronizedPoolableFactory(PoolableObjectFactory factory)` Returns a synchronized (thread-safe) PoolableObjectFactory backed by the specified PoolableObjectFactory.

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(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:
    `ThreadDeath` - if that is passed in
    `VirtualMachineError` - if that is passed in
  Since:
    Pool 1.5.5

### adapt

    public static PoolableObjectFactory adapt(KeyedPoolableObjectFactory keyedFactory)
                                       throws IllegalArgumentException

  Adapt a `KeyedPoolableObjectFactory` instance to work where a `PoolableObjectFactory` is needed. This method is the equivalent of calling `PoolUtils.adapt(aKeyedPoolableObjectFactory, new Object())`.

  Parameters:
    `keyedFactory` - the `KeyedPoolableObjectFactory` to delegate to.
  Returns:
    a `PoolableObjectFactory` that delegates to `keyedFactory` with an internal key.
  Throws:
    `IllegalArgumentException` - when `keyedFactory` is `null`.
  Since:
    Pool 1.3
  See Also:
    `adapt(KeyedPoolableObjectFactory, Object)`

### adapt

    public static PoolableObjectFactory adapt(KeyedPoolableObjectFactory keyedFactory,
                                              Object key)
                                       throws IllegalArgumentException

  Adapt a `KeyedPoolableObjectFactory` instance to work where a `PoolableObjectFactory` is needed using the specified `key` when delegating.

  Parameters:
    `keyedFactory` - the `KeyedPoolableObjectFactory` to delegate to.
    `key` - the key to use when delegating.
  Returns:
    a `PoolableObjectFactory` that delegates to `keyedFactory` with the specified key.
  Throws:
    `IllegalArgumentException` - when `keyedFactory` or `key` is `null`.
  Since:
    Pool 1.3
  See Also:
    `adapt(KeyedPoolableObjectFactory)`

### adapt

    public static KeyedPoolableObjectFactory adapt(PoolableObjectFactory factory)
                                            throws IllegalArgumentException

  Adapt a `PoolableObjectFactory` instance to work where a `KeyedPoolableObjectFactory` is needed. The key is ignored.

  Parameters:
    `factory` - the `PoolableObjectFactory` to delegate to.
  Returns:
    a `KeyedPoolableObjectFactory` that delegates to `factory` ignoring the key.
  Throws:
    `IllegalArgumentException` - when `factory` is `null`.
  Since:
    Pool 1.3

### adapt

    public static ObjectPool adapt(KeyedObjectPool keyedPool)
                            throws IllegalArgumentException

  Adapt a `KeyedObjectPool` instance to work where an `ObjectPool` is needed. This is the equivalent of calling `PoolUtils.adapt(aKeyedObjectPool, new Object())`.

  Parameters:
    `keyedPool` - the `KeyedObjectPool` to delegate to.
  Returns:
    an `ObjectPool` that delegates to `keyedPool` with an internal key.
  Throws:
    `IllegalArgumentException` - when `keyedPool` is `null`.
  Since:
    Pool 1.3
  See Also:
    `adapt(KeyedObjectPool, Object)`

### adapt

    public static ObjectPool adapt(KeyedObjectPool keyedPool,
                                   Object key)
                            throws IllegalArgumentException

  Adapt a `KeyedObjectPool` instance to work where an `ObjectPool` is needed using the specified `key` when delegating.

  Parameters:
    `keyedPool` - the `KeyedObjectPool` to delegate to.
    `key` - the key to use when delegating.
  Returns:
    an `ObjectPool` that delegates to `keyedPool` with the specified key.
  Throws:
    `IllegalArgumentException` - when `keyedPool` or `key` is `null`.
  Since:
    Pool 1.3
  See Also:
    `adapt(KeyedObjectPool)`

### adapt

    public static KeyedObjectPool adapt(ObjectPool pool)
                                 throws IllegalArgumentException

  Adapt an `ObjectPool` to work where an `KeyedObjectPool` is needed. The key is ignored.

  Parameters:
    `pool` - the `ObjectPool` to delegate to.
  Returns:
    a `KeyedObjectPool` that delegates to `pool` ignoring the key.
  Throws:
    `IllegalArgumentException` - when `pool` is `null`.
  Since:
    Pool 1.3

### checkedPool

    public static ObjectPool checkedPool(ObjectPool pool,
                                         Class type)

  Wraps an `ObjectPool` and dynamically checks the type of objects borrowed and returned to the pool. If an object is passed to the pool that isn't of type `type` a `ClassCastException` will be thrown.

  Parameters:
    `pool` - the pool to enforce type safety on
    `type` - the class type to enforce.
  Returns:
    an `ObjectPool` that will only allow objects of `type`
  Since:
    Pool 1.3

### checkedPool

    public static KeyedObjectPool checkedPool(KeyedObjectPool keyedPool,
                                              Class type)

  Wraps a `KeyedObjectPool` and dynamically checks the type of objects borrowed and returned to the keyedPool. If an object is passed to the keyedPool that isn't of type `type` a `ClassCastException` will be thrown.

  Parameters:
    `keyedPool` - the keyedPool to enforce type safety on
    `type` - the class type to enforce.
  Returns:
    a `KeyedObjectPool` that will only allow objects of `type`
  Since:
    Pool 1.3

### checkMinIdle

    public static TimerTask checkMinIdle(ObjectPool pool,
                                         int minIdle,
                                         long period)
                                  throws 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.

  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:
    `IllegalArgumentException` - when `pool` is `null` or when `minIdle` is negative or when `period` isn't valid for `Timer.schedule(TimerTask, long, long)`.
  Since:
    Pool 1.3

### checkMinIdle

    public static TimerTask checkMinIdle(KeyedObjectPool keyedPool,
                                         Object key,
                                         int minIdle,
                                         long period)
                                  throws 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.

  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:
    `IllegalArgumentException` - when `keyedPool`, `key` is `null` or when `minIdle` is negative or when `period` isn't valid for `Timer.schedule(TimerTask, long, long)`.
  Since:
    Pool 1.3

### checkMinIdle

    public static Map checkMinIdle(KeyedObjectPool keyedPool,
                                   Collection keys,
                                   int minIdle,
                                   long period)
                            throws 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.

  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:
    `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)`.
  Since:
    Pool 1.3
  See Also:
    `checkMinIdle(KeyedObjectPool, Object, int, long)`

### prefill

    public static void prefill(ObjectPool pool,
                               int count)
                        throws Exception,
                               IllegalArgumentException

  Call `addObject()` on `pool` `count` number of times.

  Parameters:
    `pool` - the pool to prefill.
    `count` - the number of idle objects to add.
  Throws:
    `Exception` - when `ObjectPool.addObject()` fails.
    `IllegalArgumentException` - when `pool` is `null`.
  Since:
    Pool 1.3

### prefill

    public static void prefill(KeyedObjectPool keyedPool,
                               Object key,
                               int count)
                        throws Exception,
                               IllegalArgumentException

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

  Parameters:
    `keyedPool` - the keyedPool to prefill.
    `key` - the key to add objects for.
    `count` - the number of idle objects to add for `key`.
  Throws:
    `Exception` - when `KeyedObjectPool.addObject(Object)` fails.
    `IllegalArgumentException` - when `keyedPool` or `key` is `null`.
  Since:
    Pool 1.3

### prefill

    public static void prefill(KeyedObjectPool keyedPool,
                               Collection keys,
                               int count)
                        throws Exception,
                               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.

  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:
    `Exception` - when `KeyedObjectPool.addObject(Object)` fails.
    `IllegalArgumentException` - when `keyedPool`, `keys`, or any value in `keys` is `null`.
  Since:
    Pool 1.3
  See Also:
    `prefill(KeyedObjectPool, Object, int)`

### synchronizedPool

    public static ObjectPool synchronizedPool(ObjectPool 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.

  Parameters:
    `pool` - the ObjectPool to be "wrapped" in a synchronized ObjectPool.
  Returns:
    a synchronized view of the specified ObjectPool.
  Since:
    Pool 1.3

### synchronizedPool

    public static KeyedObjectPool synchronizedPool(KeyedObjectPool 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.

  Parameters:
    `keyedPool` - the KeyedObjectPool to be "wrapped" in a synchronized KeyedObjectPool.
  Returns:
    a synchronized view of the specified KeyedObjectPool.
  Since:
    Pool 1.3

### synchronizedPoolableFactory

    public static PoolableObjectFactory synchronizedPoolableFactory(PoolableObjectFactory factory)

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

  Parameters:
    `factory` - the PoolableObjectFactory to be "wrapped" in a synchronized PoolableObjectFactory.
  Returns:
    a synchronized view of the specified PoolableObjectFactory.
  Since:
    Pool 1.3

### synchronizedPoolableFactory

    public static KeyedPoolableObjectFactory synchronizedPoolableFactory(KeyedPoolableObjectFactory keyedFactory)

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

  Parameters:
    `keyedFactory` - the KeyedPoolableObjectFactory to be "wrapped" in a synchronized KeyedPoolableObjectFactory.
  Returns:
    a synchronized view of the specified KeyedPoolableObjectFactory.
  Since:
    Pool 1.3

### erodingPool

    public static ObjectPool erodingPool(ObjectPool pool)

  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.

  Parameters:
    `pool` - the ObjectPool to be decorated so it shrinks it's idle count when possible.
  Returns:
    a pool that adaptively decreases it's size when idle objects are no longer needed.
  Since:
    Pool 1.4
  See Also:
    `erodingPool(ObjectPool, float)`

### erodingPool

    public static ObjectPool erodingPool(ObjectPool pool,
                                         float factor)

  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.

  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.

  Parameters:
    `pool` - the ObjectPool to be decorated so it shrinks it's idle count when possible.
    `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.
  Returns:
    a pool that adaptively decreases it's size when idle objects are no longer needed.
  Since:
    Pool 1.4
  See Also:
    `erodingPool(ObjectPool)`

### erodingPool

    public static KeyedObjectPool erodingPool(KeyedObjectPool keyedPool)

  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.

  Parameters:
    `keyedPool` - the KeyedObjectPool to be decorated so it shrinks it's idle count when possible.
  Returns:
    a pool that adaptively decreases it's size when idle objects are no longer needed.
  Since:
    Pool 1.4
  See Also:
    `erodingPool(KeyedObjectPool, float)`, `erodingPool(KeyedObjectPool, float, boolean)`

### erodingPool

    public static KeyedObjectPool erodingPool(KeyedObjectPool keyedPool,
                                              float factor)

  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.

  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.

  Parameters:
    `keyedPool` - the KeyedObjectPool to be decorated so it shrinks it's idle count when possible.
    `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.
  Returns:
    a pool that adaptively decreases it's size when idle objects are no longer needed.
  Since:
    Pool 1.4
  See Also:
    `erodingPool(KeyedObjectPool, float, boolean)`

### erodingPool

    public static KeyedObjectPool erodingPool(KeyedObjectPool keyedPool,
                                              float factor,
                                              boolean perKey)

  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.

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

  Parameters:
    `keyedPool` - the KeyedObjectPool to be decorated so it shrinks it's idle count when possible.
    `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.
    `perKey` - when true, each key is treated independently.
  Returns:
    a pool that adaptively decreases it's size when idle objects are no longer needed.
  Since:
    Pool 1.4
  See Also:
    `erodingPool(KeyedObjectPool)`, `erodingPool(KeyedObjectPool, float)`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2001-2011 The Apache Software Foundation. All Rights Reserved.