Package org.apache.commons.pool.impl

Class 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) $
    See Also:
    Stack

    • 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

        @Deprecated
protected java.util.HashMap<K,​java.util.Stack<V>> _pools
        Deprecated.
        to be removed in pool 2.0. Use getPools()
        My named-set of pools.

      • _maxSleeping

        @Deprecated
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

        @Deprecated
protected int _initSleepingCapacity
        Deprecated.
        to be removed in pool 2.0. Use getInitSleepingCapacity().
        The initial capacity of each pool.

      • _totActive

        @Deprecated
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

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

      • _activeCount

        @Deprecated
protected java.util.HashMap<K,​java.lang.Integer> _activeCount
        Deprecated.
        to be removed in pool 2.0. Use getActiveCount().
        Number of active objects borrowed and not yet returned by pool

    • Method Detail

      • borrowObject

        public V borrowObject​(K key)
               throws java.lang.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:
        java.lang.IllegalStateException - after close has been called on this pool
        java.lang.Exception - when makeObject throws an exception
        java.util.NoSuchElementException - when the pool is exhausted and cannot or will not return another instance

      • returnObject

        public void returnObject​(K key,
                         V obj)
                  throws java.lang.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:
        java.lang.Exception

      • invalidateObject

        public void invalidateObject​(K key,
                             V obj)
                      throws java.lang.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:
        java.lang.Exception

      • addObject

        public void addObject​(K key)
               throws java.lang.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:
        java.lang.Exception - when KeyedPoolableObjectFactory.makeObject(K) fails.
        java.lang.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​(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

      • destroyStack

        private void destroyStack​(K key,
                          java.util.Stack<V> stack)
        Destroys all instances in the stack and clears the stack.
        Parameters:
        key - key passed to factory when destroying instances
        stack - stack to destroy

      • toString

        public java.lang.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 java.lang.Object
        Returns:
        Keys and pool sizes

      • close

        public void close()
           throws java.lang.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:
        java.lang.Exception - deprecated: implementations should silently fail if not all resources can be freed.

      • setFactory

        @Deprecated
public void setFactory​(KeyedPoolableObjectFactory<K,​V> factory)
                throws java.lang.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<K,​V>
        Overrides:
        setFactory in class BaseKeyedObjectPool<K,​V>
        Parameters:
        factory - the KeyedPoolableObjectFactory used to manage object instances
        Throws:
        java.lang.IllegalStateException - when the factory cannot be set at this time

      • getActiveCount

        private int getActiveCount​(K key)
        Returns the active instance count for the given key.
        Parameters:
        key - pool key
        Returns:
        active count

      • incrementActiveCount

        private void incrementActiveCount​(K key)
        Increment the active count for the given key. Also increments the total active count.
        Parameters:
        key - pool key

      • decrementActiveCount

        private void decrementActiveCount​(K key)
        Decrements the active count for the given key. Also decrements the total active count.
        Parameters:
        key - pool key

      • getPools

        public java.util.Map<K,​java.util.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 java.util.Map<K,​java.lang.Integer> getActiveCount()
        Returns:
        the _activeCount
        Since:
        1.5.5