org.apache.tomcat.dbcp.pool.impl

## Class StackKeyedObjectPool<K,V>

- java.lang.Object
- - org.apache.tomcat.dbcp.pool.BaseKeyedObjectPool<K,V>
  - - org.apache.tomcat.dbcp.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>

  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
  Author:
    Rodney Waldhoff, Sandy McArthur
  See Also:
    `Stack`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected java.util.HashMap<K,java.lang.Integer>` | `_activeCount` Deprecated. to be removed in pool 2.0. Use `getActiveCount()`.
    `protected KeyedPoolableObjectFactory<K,V>` | `_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 java.util.HashMap<K,java.util.Stack<V>>` | `_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

    Constructors
    Constructor and Description
    `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<K,V> factory)` Create a new `SimpleKeyedObjectPool` using the specified `factory` to create new instances.
    `StackKeyedObjectPool(KeyedPoolableObjectFactory<K,V> factory, int max)` Create a new `SimpleKeyedObjectPool` using the specified `factory` to create new instances.
    `StackKeyedObjectPool(KeyedPoolableObjectFactory<K,V> factory, int max, int init)` Create a new `SimpleKeyedObjectPool` using the specified `factory` to create new instances.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addObject(K key)` Create an object using the `factory`, passivate it, and then placed in the idle object pool.
    `V` | `borrowObject(K key)` Borrows an object with the given key.
    `void` | `clear()` Clears the pool, removing all pooled instances.
    `void` | `clear(K 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.
    `java.util.Map<K,java.lang.Integer>` | `getActiveCount()`
    `KeyedPoolableObjectFactory<K,V>` | `getFactory()`
    `int` | `getInitSleepingCapacity()`
    `int` | `getMaxSleeping()`
    `int` | `getNumActive()` Returns the total number of instances current borrowed from this pool but not yet returned.
    `int` | `getNumActive(K 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(K key)` Returns the number of instances corresponding to the given `key` currently idle in this pool.
    `java.util.Map<K,java.util.Stack<V>>` | `getPools()`
    `int` | `getTotActive()`
    `int` | `getTotIdle()`
    `void` | `invalidateObject(K key, V obj)` Invalidates an object from the pool.
    `void` | `returnObject(K key, V obj)` Returns `obj` to the pool under `key`.
    `void` | `setFactory(KeyedPoolableObjectFactory<K,V> factory)` Deprecated. to be removed in pool 2.0
    `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.

    - ### Methods inherited from class org.apache.tomcat.dbcp.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

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

    - #### _factory

          @Deprecated
          protected KeyedPoolableObjectFactory<K,V> _factory

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

    - #### _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

  - ### 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<K,V> 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<K,V> 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<K,V> 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 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()

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

    - #### getFactory

          public KeyedPoolableObjectFactory<K,V> getFactory()

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

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

Copyright © 2000-2020 Apache Software Foundation. All Rights Reserved.