Package org.apache.commons.pool.impl

Class StackKeyedObjectPool<K,V>

java.lang.Object
org.apache.commons.pool.BaseKeyedObjectPool<K,V>
org.apache.commons.pool.impl.StackKeyedObjectPool<K,V>
Type Parameters:
K - the type of keys in this pool
V - the type of objects held in this pool
All Implemented Interfaces:
KeyedObjectPool<K,V>
public class StackKeyedObjectPool<K,V> extends BaseKeyedObjectPool<K,V> implements KeyedObjectPool<K,V>
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 Objects without introducing artificial limits.

Since:
Pool 1.0
Version:
$Revision: 1222710 $ $Date: 2011-12-23 10:58:12 -0500 (Fri, 23 Dec 2011) $
Author:
Rodney Waldhoff, Sandy McArthur
See Also:

  • Constructor Details

  • Method Details

    • borrowObject

      public V borrowObject(K 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<K,V>
      Specified by:
      borrowObject in class BaseKeyedObjectPool<K,V>
      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(K key, V 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<K,V>
      Specified by:
      returnObject in class BaseKeyedObjectPool<K,V>
      Parameters:
      key - the pool key
      obj - returning instance
      Throws:
      Exception

    • invalidateObject

      public void invalidateObject(K key, V 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<K,V>
      Specified by:
      invalidateObject in class BaseKeyedObjectPool<K,V>
      Parameters:
      key - the key used to obtain the object
      obj - a borrowed instance to be returned.
      Throws:
      Exception

    • addObject

      public void addObject(K 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<K,V>
      Overrides:
      addObject in class BaseKeyedObjectPool<K,V>
      Parameters:
      key - the key a new instance should be added to
      Throws:
      Exception - when KeyedPoolableObjectFactory.makeObject(K) 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<K,V>
      Overrides:
      getNumIdle in class BaseKeyedObjectPool<K,V>
      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<K,V>
      Overrides:
      getNumActive in class BaseKeyedObjectPool<K,V>
      Returns:
      the total number of instances currently borrowed from this pool

    • getNumActive

      public int getNumActive(K 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<K,V>
      Overrides:
      getNumActive in class BaseKeyedObjectPool<K,V>
      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(K key)
      Returns the number of instances corresponding to the given key currently idle in this pool.
      Specified by:
      getNumIdle in interface KeyedObjectPool<K,V>
      Overrides:
      getNumIdle in class BaseKeyedObjectPool<K,V>
      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<K,V>
      Overrides:
      clear in class BaseKeyedObjectPool<K,V>

    • clear

      public void clear(K key)
      Clears the specified pool, removing all pooled instances corresponding to the given key.
      Specified by:
      clear in interface KeyedObjectPool<K,V>
      Overrides:
      clear in class BaseKeyedObjectPool<K,V>
      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<K,V>
      Overrides:
      close in class BaseKeyedObjectPool<K,V>
      Throws:
      Exception - deprecated: implementations should silently fail if not all resources can be freed.

    • getFactory

      public KeyedPoolableObjectFactory<K,V> getFactory()
      Returns:
      the KeyedPoolableObjectFactory used by this pool to manage object instances.
      Since:
      1.5.5

    • getPools

      public Map<K,Stack<V>> 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<K,Integer> getActiveCount()
      Returns:
      the _activeCount
      Since:
      1.5.5