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.impl
Class StackKeyedObjectPool

    java.lang.Object
      org.apache.commons.pool.BaseKeyedObjectPool
          org.apache.commons.pool.impl.StackKeyedObjectPool

All Implemented Interfaces:
  KeyedObjectPool

    public class StackKeyedObjectPool

extends BaseKeyedObjectPool
implements KeyedObjectPool

A simple, `Stack`-based `KeyedObjectPool` implementation.

Given a `KeyedPoolableObjectFactory`, this class will maintain a simple pool of instances. A finite number of "sleeping" or inactive instances is enforced, but when the pool is empty, new instances are created to support the new load. Hence this class places no limit on the number of "active" instances created by the pool, but is quite useful for re-using `Object`s without introducing artificial limits.

Since:
  Pool 1.0
Version:
  $Revision: 990437 $ $Date: 2010-08-28 13:17:57 -0700 (Sat, 28 Aug 2010) $
Author:
  Rodney Waldhoff, Sandy McArthur
See Also:
  `Stack`

Field Summary
`protected HashMap` | `_activeCount` Deprecated. to be removed in pool 2.0. Use `getActiveCount()`.
`protected KeyedPoolableObjectFactory` | `_factory` Deprecated. to be removed in pool 2.0. Use `getFactory()`
`protected int` | `_initSleepingCapacity` Deprecated. to be removed in pool 2.0. Use `getInitSleepingCapacity()`.
`protected int` | `_maxSleeping` Deprecated. to be removed in pool 2.0. Use `getMaxSleeping()`
`protected HashMap` | `_pools` Deprecated. to be removed in pool 2.0. Use `getPools()`
`protected int` | `_totActive` Deprecated. to be removed in pool 2.0. Use `getTotActive()`.
`protected int` | `_totIdle` Deprecated. to be removed in pool 2.0. Use `getTotIdle()`.
`protected static int` | `DEFAULT_INIT_SLEEPING_CAPACITY` The default initial size of the pool (this specifies the size of the container, it does not cause the pool to be pre-populated.)
`protected static int` | `DEFAULT_MAX_SLEEPING` The default cap on the number of "sleeping" instances in the pool.

Constructor Summary
`StackKeyedObjectPool()` Create a new pool using no factory.
`StackKeyedObjectPool(int max)` Create a new pool using no factory.
`StackKeyedObjectPool(int max, int init)` Create a new pool using no factory.
`StackKeyedObjectPool(KeyedPoolableObjectFactory factory)` Create a new `SimpleKeyedObjectPool` using the specified `factory` to create new instances.
`StackKeyedObjectPool(KeyedPoolableObjectFactory factory, int max)` Create a new `SimpleKeyedObjectPool` using the specified `factory` to create new instances.
`StackKeyedObjectPool(KeyedPoolableObjectFactory factory, int max, int init)` Create a new `SimpleKeyedObjectPool` using the specified `factory` to create new instances.

Method Summary
`void` | `addObject(Object key)` Create an object using the `factory`, passivate it, and then placed in the idle object pool.
`Object` | `borrowObject(Object key)` Borrows an object with the given key.
`void` | `clear()` Clears the pool, removing all pooled instances.
`void` | `clear(Object key)` Clears the specified pool, removing all pooled instances corresponding to the given `key`.
`void` | `close()` Close this pool, and free any resources associated with it.
`Map` | `getActiveCount()`
`KeyedPoolableObjectFactory` | `getFactory()`
`int` | `getInitSleepingCapacity()`
`int` | `getMaxSleeping()`
`int` | `getNumActive()` Returns the total number of instances current borrowed from this pool but not yet returned.
`int` | `getNumActive(Object key)` Returns the number of instances currently borrowed from but not yet returned to the pool corresponding to the given `key`.
`int` | `getNumIdle()` Returns the total number of instances currently idle in this pool.
`int` | `getNumIdle(Object key)` Returns the number of instances corresponding to the given `key` currently idle in this pool.
`Map` | `getPools()`
`int` | `getTotActive()`
`int` | `getTotIdle()`
`void` | `invalidateObject(Object key, Object obj)` Invalidates an object from the pool.
`void` | `returnObject(Object key, Object obj)` Returns `obj` to the pool under `key`.
`void` | `setFactory(KeyedPoolableObjectFactory factory)` Deprecated. to be removed in pool 2.0
`String` | `toString()` Returns a string representation of this StackKeyedObjectPool, including the number of pools, the keys and the size of each keyed pool.

Methods inherited from class org.apache.commons.pool.BaseKeyedObjectPool
`assertOpen, isClosed`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Field Detail

### DEFAULT_MAX_SLEEPING

    protected static final int DEFAULT_MAX_SLEEPING

  The default cap on the number of "sleeping" instances in the pool.

  See Also:
    Constant Field Values

### DEFAULT_INIT_SLEEPING_CAPACITY

    protected static final int DEFAULT_INIT_SLEEPING_CAPACITY

  The default initial size of the pool (this specifies the size of the container, it does not cause the pool to be pre-populated.)

  See Also:
    Constant Field Values

### _pools

    protected HashMap _pools

  Deprecated. to be removed in pool 2.0. Use `getPools()`
  My named-set of pools.

### _factory

    protected KeyedPoolableObjectFactory _factory

  Deprecated. to be removed in pool 2.0. Use `getFactory()`
  My `KeyedPoolableObjectFactory`.

### _maxSleeping

    protected int _maxSleeping

  Deprecated. to be removed in pool 2.0. Use `getMaxSleeping()`
  The cap on the number of "sleeping" instances in `each` pool.

### _initSleepingCapacity

    protected int _initSleepingCapacity

  Deprecated. to be removed in pool 2.0. Use `getInitSleepingCapacity()`.
  The initial capacity of each pool.

### _totActive

    protected int _totActive

  Deprecated. to be removed in pool 2.0. Use `getTotActive()`.
  Total number of object borrowed and not yet returned for all pools.

### _totIdle

    protected int _totIdle

  Deprecated. to be removed in pool 2.0. Use `getTotIdle()`.
  Total number of objects "sleeping" for all pools

### _activeCount

    protected HashMap _activeCount

  Deprecated. to be removed in pool 2.0. Use `getActiveCount()`.
  Number of active objects borrowed and not yet returned by pool

Constructor Detail

### StackKeyedObjectPool

    public StackKeyedObjectPool()

  Create a new pool using no factory. Clients must first set the `factory` or may populate the pool using `returnObject` before they can be `borrowed`.

  See Also:
    `StackKeyedObjectPool(KeyedPoolableObjectFactory)`, `setFactory(KeyedPoolableObjectFactory)`

### StackKeyedObjectPool

    public StackKeyedObjectPool(int max)

  Create a new pool using no factory. Clients must first set the `factory` or may populate the pool using `returnObject` before they can be `borrowed`.

  Parameters:
    `max` - cap on the number of "sleeping" instances in the pool
  See Also:
    `StackKeyedObjectPool(KeyedPoolableObjectFactory, int)`, `setFactory(KeyedPoolableObjectFactory)`

### StackKeyedObjectPool

    public StackKeyedObjectPool(int max,
                                int init)

  Create a new pool using no factory. Clients must first set the `factory` or may populate the pool using `returnObject` before they can be `borrowed`.

  Parameters:
    `max` - cap on the number of "sleeping" instances in the pool
    `init` - initial size of the pool (this specifies the size of the container, it does not cause the pool to be pre-populated.)
  See Also:
    `StackKeyedObjectPool(KeyedPoolableObjectFactory, int, int)`, `setFactory(KeyedPoolableObjectFactory)`

### StackKeyedObjectPool

    public StackKeyedObjectPool(KeyedPoolableObjectFactory factory)

  Create a new `SimpleKeyedObjectPool` using the specified `factory` to create new instances.

  Parameters:
    `factory` - the `KeyedPoolableObjectFactory` used to populate the pool

### StackKeyedObjectPool

    public StackKeyedObjectPool(KeyedPoolableObjectFactory factory,
                                int max)

  Create a new `SimpleKeyedObjectPool` using the specified `factory` to create new instances. capping the number of "sleeping" instances to `max`

  Parameters:
    `factory` - the `KeyedPoolableObjectFactory` used to populate the pool
    `max` - cap on the number of "sleeping" instances in the pool

### StackKeyedObjectPool

    public StackKeyedObjectPool(KeyedPoolableObjectFactory factory,
                                int max,
                                int init)

  Create a new `SimpleKeyedObjectPool` using the specified `factory` to create new instances. capping the number of "sleeping" instances to `max`, and initially allocating a container capable of containing at least `init` instances.

  Parameters:
    `factory` - the `KeyedPoolableObjectFactory` used to populate the pool
    `max` - cap on the number of "sleeping" instances in the pool
    `init` - initial size of the pool (this specifies the size of the container, it does not cause the pool to be pre-populated.)

Method Detail

### borrowObject

    public Object borrowObject(Object key)
                        throws Exception

  Borrows an object with the given key. If there are no idle instances under the given key, a new one is created.

  Specified by:
    `borrowObject` in interface `KeyedObjectPool`
  Specified by:
    `borrowObject` in class `BaseKeyedObjectPool`
  Parameters:
    `key` - the pool key
  Returns:
    keyed poolable object instance
  Throws:
    `IllegalStateException` - after `close` has been called on this pool
    `Exception` - when `makeObject` throws an exception
    `NoSuchElementException` - when the pool is exhausted and cannot or will not return another instance

### returnObject

    public void returnObject(Object key,
                             Object obj)
                      throws Exception

  Returns `obj` to the pool under `key`. If adding the returning instance to the pool results in `maxSleeping` exceeded for the given key, the oldest instance in the idle object pool is destroyed to make room for the returning instance.

  Specified by:
    `returnObject` in interface `KeyedObjectPool`
  Specified by:
    `returnObject` in class `BaseKeyedObjectPool`
  Parameters:
    `key` - the pool key
    `obj` - returning instance
  Throws:
    `Exception`

### invalidateObject

    public void invalidateObject(Object key,
                                 Object obj)
                          throws Exception

  Invalidates an object from the pool.

  By contract, `obj` must have been obtained using `borrowObject` using a `key` that is equivalent to the one used to borrow the `Object` in the first place.

  This method should be used when an object that has been borrowed is determined (due to an exception or other problem) to be invalid.

  Specified by:
    `invalidateObject` in interface `KeyedObjectPool`
  Specified by:
    `invalidateObject` in class `BaseKeyedObjectPool`
  Parameters:
    `key` - the key used to obtain the object
    `obj` - a `borrowed` instance to be returned.
  Throws:
    `Exception`

### addObject

    public void addObject(Object key)
                   throws Exception

  Create an object using the `factory`, passivate it, and then placed in the idle object pool. `addObject` is useful for "pre-loading" a pool with idle objects.

  Specified by:
    `addObject` in interface `KeyedObjectPool`
  Overrides:
    `addObject` in class `BaseKeyedObjectPool`
  Parameters:
    `key` - the key a new instance should be added to
  Throws:
    `Exception` - when `KeyedPoolableObjectFactory.makeObject(java.lang.Object)` fails.
    `IllegalStateException` - when no `factory` has been set or after `close()` has been called on this pool.

### getNumIdle

    public int getNumIdle()

  Returns the total number of instances currently idle in this pool.

  Specified by:
    `getNumIdle` in interface `KeyedObjectPool`
  Overrides:
    `getNumIdle` in class `BaseKeyedObjectPool`
  Returns:
    the total number of instances currently idle in this pool

### getNumActive

    public int getNumActive()

  Returns the total number of instances current borrowed from this pool but not yet returned.

  Specified by:
    `getNumActive` in interface `KeyedObjectPool`
  Overrides:
    `getNumActive` in class `BaseKeyedObjectPool`
  Returns:
    the total number of instances currently borrowed from this pool

### getNumActive

    public int getNumActive(Object key)

  Returns the number of instances currently borrowed from but not yet returned to the pool corresponding to the given `key`.

  Specified by:
    `getNumActive` in interface `KeyedObjectPool`
  Overrides:
    `getNumActive` in class `BaseKeyedObjectPool`
  Parameters:
    `key` - the key to query
  Returns:
    the number of instances corresponding to the given `key` currently borrowed in this pool

### getNumIdle

    public int getNumIdle(Object key)

  Returns the number of instances corresponding to the given `key` currently idle in this pool.

  Specified by:
    `getNumIdle` in interface `KeyedObjectPool`
  Overrides:
    `getNumIdle` in class `BaseKeyedObjectPool`
  Parameters:
    `key` - the key to query
  Returns:
    the number of instances corresponding to the given `key` currently idle in this pool

### clear

    public void clear()

  Clears the pool, removing all pooled instances.

  Specified by:
    `clear` in interface `KeyedObjectPool`
  Overrides:
    `clear` in class `BaseKeyedObjectPool`

### clear

    public void clear(Object key)

  Clears the specified pool, removing all pooled instances corresponding to the given `key`.

  Specified by:
    `clear` in interface `KeyedObjectPool`
  Overrides:
    `clear` in class `BaseKeyedObjectPool`
  Parameters:
    `key` - the key to clear

### toString

    public String toString()

  Returns a string representation of this StackKeyedObjectPool, including the number of pools, the keys and the size of each keyed pool.

  Overrides:
    `toString` in class `Object`
  Returns:
    Keys and pool sizes

### close

    public void close()
               throws Exception

  Close this pool, and free any resources associated with it.

  Calling `addObject` or `borrowObject` after invoking this method on a pool will cause them to throw an `IllegalStateException`.

  Specified by:
    `close` in interface `KeyedObjectPool`
  Overrides:
    `close` in class `BaseKeyedObjectPool`
  Throws:
    `Exception` - deprecated: implementations should silently fail if not all resources can be freed.

### setFactory

    public void setFactory(KeyedPoolableObjectFactory factory)
                    throws IllegalStateException

  Deprecated. to be removed in pool 2.0

  Sets the `factory` the pool uses to create new instances. Trying to change the `factory` after a pool has been used will frequently throw an `UnsupportedOperationException`.

  Specified by:
    `setFactory` in interface `KeyedObjectPool`
  Overrides:
    `setFactory` in class `BaseKeyedObjectPool`
  Parameters:
    `factory` - the `KeyedPoolableObjectFactory` used to manage object instances
  Throws:
    `IllegalStateException` - when the factory cannot be set at this time

### getFactory

    public KeyedPoolableObjectFactory getFactory()

  Returns:
    the `KeyedPoolableObjectFactory` used by this pool to manage object instances.
  Since:
    1.5.5

### getPools

    public Map getPools()

  Returns:
    map of keyed pools
  Since:
    1.5.5

### getMaxSleeping

    public int getMaxSleeping()

  Returns:
    the cap on the number of "sleeping" instances in `each` pool.
  Since:
    1.5.5

### getInitSleepingCapacity

    public int getInitSleepingCapacity()

  Returns:
    the initial capacity of each pool.
  Since:
    1.5.5

### getTotActive

    public int getTotActive()

  Returns:
    the _totActive

### getTotIdle

    public int getTotIdle()

  Returns:
    the _totIdle

### getActiveCount

    public Map getActiveCount()

  Returns:
    the _activeCount
  Since:
    1.5.5

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.