GenericKeyedObjectPool (Apache Tomcat 10.1.20 API Documentation)
Description: declaration: package: org.apache.tomcat.dbcp.pool2.impl, class: GenericKeyedObjectPool

Package org.apache.tomcat.dbcp.pool2.impl

# Class GenericKeyedObjectPool<K,T>

java.lang.Object
org.apache.tomcat.dbcp.pool2.BaseObject
org.apache.tomcat.dbcp.pool2.impl.BaseGenericObjectPool<T>
org.apache.tomcat.dbcp.pool2.impl.GenericKeyedObjectPool<K,T>

Type Parameters:
  `K` - The type of keys maintained by this pool.
  `T` - Type of element pooled in this pool.

All Implemented Interfaces:
  `Closeable`, `AutoCloseable`, `GenericKeyedObjectPoolMXBean<K>`, `KeyedObjectPool<K,T>`, `UsageTracking<T>`

public class GenericKeyedObjectPool<K,T> extends BaseGenericObjectPool<T> implements KeyedObjectPool<K,T>, GenericKeyedObjectPoolMXBean<K>, UsageTracking<T>
A configurable `KeyedObjectPool` implementation.

When coupled with the appropriate `KeyedPooledObjectFactory`, `GenericKeyedObjectPool` provides robust pooling functionality for keyed objects. A `GenericKeyedObjectPool` can be viewed as a map of sub-pools, keyed on the (unique) key values provided to the `preparePool`, `addObject` or `borrowObject` methods. Each time a new key value is provided to one of these methods, a sub-new pool is created under the given key to be managed by the containing `GenericKeyedObjectPool.`

Note that the current implementation uses a ConcurrentHashMap which uses equals() to compare keys. This means that distinct instance keys must be distinguishable using equals.

Optionally, one may configure the pool to examine and possibly evict objects as they sit idle in the pool and to ensure that a minimum number of idle objects is maintained for each key. This is performed by an "idle object eviction" thread, which runs asynchronously. Caution should be used when configuring this optional feature. Eviction runs contend with client threads for access to objects in the pool, so if they run too frequently performance issues may result.

Implementation note: To prevent possible deadlocks, care has been taken to ensure that no call to a factory method will occur within a synchronization block. See POOL-125 and DBCP-44 for more information.

This class is intended to be thread-safe.

Since:
  2.0
See Also:
  - `GenericObjectPool`

- ## Field Summary

  ### Fields inherited from class org.apache.tomcat.dbcp.pool2.impl.BaseGenericObjectPool

  `abandonedConfig, MEAN_TIMING_STATS_CACHE_SIZE`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `GenericKeyedObjectPool(KeyedPooledObjectFactory<K,T> factory)`
  Constructs a new `GenericKeyedObjectPool` using defaults from `GenericKeyedObjectPoolConfig`.
  `GenericKeyedObjectPool(KeyedPooledObjectFactory<K,T> factory, GenericKeyedObjectPoolConfig<T> config)`
  Constructs a new `GenericKeyedObjectPool` using a specific configuration.
  `GenericKeyedObjectPool(KeyedPooledObjectFactory<K,T> factory, GenericKeyedObjectPoolConfig<T> config, AbandonedConfig abandonedConfig)`
  Creates a new `GenericKeyedObjectPool` that tracks and destroys objects that are checked out, but never returned to the pool.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addObject(K key)`
  Create an object using the `factory`, passivate it, and then place it in the idle object pool.
  `T`
  `borrowObject(K key)`
  Equivalent to ``borrowObject`(key, `BaseGenericObjectPool.getMaxWaitDuration()`)`.
  `T`
  `borrowObject(K key, long borrowMaxWaitMillis)`
  Borrows an object from the sub-pool associated with the given key using the specified waiting time which only applies if `BaseGenericObjectPool.getBlockWhenExhausted()` is true.
  `void`
  `clear()`
  Clears any objects sitting idle in the pool by removing them from the idle instance sub-pools and then invoking the configured PoolableObjectFactory's `KeyedPooledObjectFactory.destroyObject(Object, PooledObject)` method on each idle instance.
  `void`
  `clear(K key)`
  Clears the specified sub-pool, removing all pooled instances corresponding to the given `key`.
  `void`
  `clear(K key, boolean reuseCapacity)`
  Clears the specified sub-pool, removing all pooled instances corresponding to the given `key`.
  `void`
  `clearOldest()`
  Clears oldest 15% of objects in pool.
  `void`
  `close()`
  Closes the keyed object pool.
  `void`
  `evict()`
  Perform `numTests` idle object eviction tests, evicting examined objects that meet the criteria for eviction.
  `KeyedPooledObjectFactory<K,T>`
  `getFactory()`
  Gets a reference to the factory used to create, destroy and validate the objects used by this pool.
  `List<K>`
  `getKeys()`
  Gets a copy of the pool key list.
  `int`
  `getMaxIdlePerKey()`
  Gets the cap on the number of "idle" instances per key in the pool.
  `int`
  `getMaxTotalPerKey()`
  Gets the limit on the number of object instances allocated by the pool (checked out or idle), per key.
  `int`
  `getMinIdlePerKey()`
  Gets the target for the minimum number of idle objects to maintain in each of the keyed sub-pools.
  `int`
  `getNumActive()`
  Gets the total number of instances currently borrowed from this pool but not yet returned.
  `int`
  `getNumActive(K key)`
  Gets the number of instances currently borrowed from but not yet returned to the pool corresponding to the given `key`.
  `Map<String,Integer>`
  `getNumActivePerKey()`
  See `getNumActivePerKey()`.
  `int`
  `getNumIdle()`
  Gets the number of instances currently idle in this pool.
  `int`
  `getNumIdle(K key)`
  Gets the number of instances corresponding to the given `key` currently idle in this pool.
  `int`
  `getNumWaiters()`
  Gets an estimate of the number of threads currently blocked waiting for an object from the pool.
  `Map<String,Integer>`
  `getNumWaitersByKey()`
  Gets an estimate of the number of threads currently blocked waiting for an object from the pool for each key.
  `void`
  `invalidateObject(K key, T obj)`
  Invalidates an object from the pool.
  `void`
  `invalidateObject(K key, T obj, DestroyMode destroyMode)`
  Invalidates an object from the pool, using the provided `DestroyMode`.
  `Map<String,List<DefaultPooledObjectInfo>>`
  `listAllObjects()`
  Provides information on all the objects in the pool, both idle (waiting to be borrowed) and active (currently borrowed).
  `void`
  `preparePool(K key)`
  Registers a key for pool control and ensures that `getMinIdlePerKey()` idle instances are created.
  `void`
  `returnObject(K key, T obj)`
  Returns an object to a keyed sub-pool.
  `void`
  `setConfig(GenericKeyedObjectPoolConfig<T> conf)`
  Sets the configuration.
  `void`
  `setMaxIdlePerKey(int maxIdlePerKey)`
  Sets the cap on the number of "idle" instances per key in the pool.
  `void`
  `setMaxTotalPerKey(int maxTotalPerKey)`
  Sets the limit on the number of object instances allocated by the pool (checked out or idle), per key.
  `void`
  `setMinIdlePerKey(int minIdlePerKey)`
  Sets the target for the minimum number of idle objects to maintain in each of the keyed sub-pools.
  `protected void`
  `toStringAppendFields(StringBuilder builder)`
  Used by sub-classes to include the fields defined by the sub-class in the `BaseObject.toString()` output.
  `void`
  `use(T pooledObject)`
  Called every time a pooled object is used to enable the pool to better track borrowed objects.

  ### Methods inherited from class org.apache.tomcat.dbcp.pool2.impl.BaseGenericObjectPool

  `getBlockWhenExhausted, getBorrowedCount, getCreatedCount, getCreationStackTrace, getDestroyedByBorrowValidationCount, getDestroyedByEvictorCount, getDestroyedCount, getDurationBetweenEvictionRuns, getEvictionPolicy, getEvictionPolicyClassName, getEvictorShutdownTimeout, getEvictorShutdownTimeoutDuration, getEvictorShutdownTimeoutMillis, getFairness, getJmxName, getLifo, getLogAbandoned, getMaxBorrowWaitDuration, getMaxBorrowWaitTimeMillis, getMaxTotal, getMaxWaitDuration, getMaxWaitMillis, getMeanActiveDuration, getMeanActiveTimeMillis, getMeanBorrowWaitDuration, getMeanBorrowWaitTimeMillis, getMeanIdleDuration, getMeanIdleTimeMillis, getMessageStatistics, getMinEvictableIdleDuration, getMinEvictableIdleTime, getMinEvictableIdleTimeMillis, getNumTestsPerEvictionRun, getRemoveAbandonedOnBorrow, getRemoveAbandonedOnMaintenance, getRemoveAbandonedTimeout, getRemoveAbandonedTimeoutDuration, getReturnedCount, getSoftMinEvictableIdleDuration, getSoftMinEvictableIdleTime, getSoftMinEvictableIdleTimeMillis, getSwallowedExceptionListener, getTestOnBorrow, getTestOnCreate, getTestOnReturn, getTestWhileIdle, getTimeBetweenEvictionRuns, getTimeBetweenEvictionRunsMillis, isAbandonedConfig, isClosed, markReturningState, setAbandonedConfig, setBlockWhenExhausted, setConfig, setDurationBetweenEvictionRuns, setEvictionPolicy, setEvictionPolicyClassName, setEvictionPolicyClassName, setEvictorShutdownTimeout, setEvictorShutdownTimeoutMillis, setLifo, setMaxTotal, setMaxWait, setMaxWaitMillis, setMessagesStatistics, setMinEvictableIdle, setMinEvictableIdleDuration, setMinEvictableIdleTime, setMinEvictableIdleTimeMillis, setNumTestsPerEvictionRun, setSoftMinEvictableIdle, setSoftMinEvictableIdleDuration, setSoftMinEvictableIdleTime, setSoftMinEvictableIdleTimeMillis, setSwallowedExceptionListener, setTestOnBorrow, setTestOnCreate, setTestOnReturn, setTestWhileIdle, setTimeBetweenEvictionRuns, setTimeBetweenEvictionRunsMillis`

  ### Methods inherited from class org.apache.tomcat.dbcp.pool2.BaseObject

  `toString`

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

  ### Methods inherited from interface org.apache.tomcat.dbcp.pool2.impl.GenericKeyedObjectPoolMXBean

  `getBlockWhenExhausted, getBorrowedCount, getCreatedCount, getCreationStackTrace, getDestroyedByBorrowValidationCount, getDestroyedByEvictorCount, getDestroyedCount, getFairness, getLifo, getLogAbandoned, getMaxBorrowWaitTimeMillis, getMaxTotal, getMaxWaitMillis, getMeanActiveTimeMillis, getMeanBorrowWaitTimeMillis, getMeanIdleTimeMillis, getMinEvictableIdleTimeMillis, getNumTestsPerEvictionRun, getRemoveAbandonedOnBorrow, getRemoveAbandonedOnMaintenance, getRemoveAbandonedTimeout, getReturnedCount, getTestOnBorrow, getTestOnCreate, getTestOnReturn, getTestWhileIdle, getTimeBetweenEvictionRunsMillis, isAbandonedConfig, isClosed`

  ### Methods inherited from interface org.apache.tomcat.dbcp.pool2.KeyedObjectPool

  `addObjects, addObjects`

- ## Constructor Details

  - ### GenericKeyedObjectPool

    public GenericKeyedObjectPool(KeyedPooledObjectFactory<K,T> factory)
    Constructs a new `GenericKeyedObjectPool` using defaults from `GenericKeyedObjectPoolConfig`.
    Parameters:
      `factory` - the factory to be used to create entries

  - ### GenericKeyedObjectPool

    public GenericKeyedObjectPool(KeyedPooledObjectFactory<K,T> factory, GenericKeyedObjectPoolConfig<T> config)
    Constructs a new `GenericKeyedObjectPool` using a specific configuration.
    Parameters:
      `factory` - the factory to be used to create entries
      `config` - The configuration to use for this pool instance. The configuration is used by value. Subsequent changes to the configuration object will not be reflected in the pool.

  - ### GenericKeyedObjectPool

    public GenericKeyedObjectPool(KeyedPooledObjectFactory<K,T> factory, GenericKeyedObjectPoolConfig<T> config, AbandonedConfig abandonedConfig)
    Creates a new `GenericKeyedObjectPool` that tracks and destroys objects that are checked out, but never returned to the pool.
    Parameters:
      `factory` - The object factory to be used to create object instances used by this pool
      `config` - The base pool configuration to use for this pool instance. The configuration is used by value. Subsequent changes to the configuration object will not be reflected in the pool.
      `abandonedConfig` - Configuration for abandoned object identification and removal. The configuration is used by value.
    Since:
      2.10.0

- ## Method Details

  - ### addObject

    public void addObject(K key) throws Exception
    Create an object using the `factory`, passivate it, and then place it in the idle object pool. `addObject` is useful for "pre-loading" a pool with idle objects.

    If there is no capacity available to add to the pool under the given key, this is a no-op (no exception, no impact to the pool).

    If the factory returns null when creating an instance, a `NullPointerException` is thrown.

    Specified by:
      `addObject` in interface `KeyedObjectPool<K,T>`
    Parameters:
      `key` - the key a new instance should be added to
    Throws:
      `Exception` - when `KeyedPooledObjectFactory.makeObject(K)` fails.

  - ### borrowObject

    public T borrowObject(K key) throws Exception
    Equivalent to ``borrowObject`(key, `BaseGenericObjectPool.getMaxWaitDuration()`)`. Borrows an instance from this pool for the specified `key`.

    Instances returned from this method will have been either newly created with `makeObject` or will be a previously idle object and have been activated with `activateObject` and then (optionally) validated with `validateObject`.

    By contract, clients must return the borrowed object using `returnObject`, `invalidateObject`, or a related method as defined in an implementation or sub-interface, using a `key` that is `equivalent` to the one used to borrow the instance in the first place.

    The behavior of this method when the pool has been exhausted is not strictly specified (although it may be specified by implementations).

    Specified by:
      `borrowObject` in interface `KeyedObjectPool<K,T>`
    Parameters:
      `key` - the key used to obtain the object
    Returns:
      an instance from this pool.
    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

  - ### borrowObject

    public T borrowObject(K key, long borrowMaxWaitMillis) throws Exception
    Borrows an object from the sub-pool associated with the given key using the specified waiting time which only applies if `BaseGenericObjectPool.getBlockWhenExhausted()` is true.

    If there is one or more idle instances available in the sub-pool associated with the given key, then an idle instance will be selected based on the value of `BaseGenericObjectPool.getLifo()`, activated and returned. If activation fails, or `testOnBorrow` is set to `true` and validation fails, the instance is destroyed and the next available instance is examined. This continues until either a valid instance is returned or there are no more idle instances available.

    If there are no idle instances available in the sub-pool associated with the given key, behavior depends on the `maxTotalPerKey`, `maxTotal`, and (if applicable) `BaseGenericObjectPool.getBlockWhenExhausted()` and the value passed in to the `borrowMaxWaitMillis` parameter. If the number of instances checked out from the sub-pool under the given key is less than `maxTotalPerKey` and the total number of instances in circulation (under all keys) is less than `maxTotal`, a new instance is created, activated and (if applicable) validated and returned to the caller. If validation fails, a `NoSuchElementException` will be thrown. If the factory returns null when creating an instance, a `NullPointerException` is thrown.

    If the associated sub-pool is exhausted (no available idle instances and no capacity to create new ones), this method will either block (`BaseGenericObjectPool.getBlockWhenExhausted()` is true) or throw a `NoSuchElementException` (`BaseGenericObjectPool.getBlockWhenExhausted()` is false). The length of time that this method will block when `BaseGenericObjectPool.getBlockWhenExhausted()` is true is determined by the value passed in to the `borrowMaxWait` parameter.

    When `maxTotal` is set to a positive value and this method is invoked when at the limit with no idle instances available under the requested key, an attempt is made to create room by clearing the oldest 15% of the elements from the keyed sub-pools.

    When the pool is exhausted, multiple calling threads may be simultaneously blocked waiting for instances to become available. A "fairness" algorithm has been implemented to ensure that threads receive available instances in request arrival order.

    Parameters:
      `key` - pool key
      `borrowMaxWaitMillis` - The time to wait in milliseconds for an object to become available
    Returns:
      object instance from the keyed pool
    Throws:
      `NoSuchElementException` - if a keyed object instance cannot be returned because the pool is exhausted.
      `Exception` - if a keyed object instance cannot be returned due to an error

  - ### clear

    public void clear()
    Clears any objects sitting idle in the pool by removing them from the idle instance sub-pools and then invoking the configured PoolableObjectFactory's `KeyedPooledObjectFactory.destroyObject(Object, PooledObject)` method on each idle instance.

    Implementation notes:

    - This method does not destroy or effect in any way instances that are checked out when it is invoked.
    - Invoking this method does not prevent objects being returned to the idle instance pool, even during its execution. Additional instances may be returned while removed items are being destroyed.
    - Exceptions encountered destroying idle instances are swallowed but notified via a `SwallowedExceptionListener`.
    Specified by:
      `clear` in interface `KeyedObjectPool<K,T>`

  - ### clear

    public void clear(K key)
    Clears the specified sub-pool, removing all pooled instances corresponding to the given `key`. Exceptions encountered destroying idle instances are swallowed but notified via a `SwallowedExceptionListener`.

    If there are clients waiting to borrow objects, this method will attempt to reuse the capacity freed by this operation, adding instances to the most loaded keyed pools. To avoid triggering possible object creation, use `clear(Object, boolean)`.

    Specified by:
      `clear` in interface `KeyedObjectPool<K,T>`
    Parameters:
      `key` - the key to clear

  - ### clear

    public void clear(K key, boolean reuseCapacity)
    Clears the specified sub-pool, removing all pooled instances corresponding to the given `key`. Exceptions encountered destroying idle instances are swallowed but notified via a `SwallowedExceptionListener`.

    If reuseCapacity is true and there are clients waiting to borrow objects, this method will attempt to reuse the capacity freed by this operation, adding instances to the most loaded keyed pools.

    Parameters:
      `key` - the key to clear
      `reuseCapacity` - whether or not to reuse freed capacity
    Since:
      2.12.0

  - ### clearOldest

    public void clearOldest()
    Clears oldest 15% of objects in pool. The method sorts the objects into a TreeMap and then iterates the first 15% for removal.

  - ### close

    public void close()
    Closes the keyed object pool. Once the pool is closed, `borrowObject(Object)` will fail with IllegalStateException, but `returnObject(Object, Object)` and `invalidateObject(Object, Object)` will continue to work, with returned objects destroyed on return.

    Destroys idle instances in the pool by invoking `clear()`.

    Specified by:
      `close` in interface `AutoCloseable`
    Specified by:
      `close` in interface `Closeable`
    Specified by:
      `close` in interface `KeyedObjectPool<K,T>`
    Specified by:
      `close` in class `BaseGenericObjectPool<T>`

  - ### evict

    public void evict() throws Exception
    Perform `numTests` idle object eviction tests, evicting examined objects that meet the criteria for eviction. If `testWhileIdle` is true, examined objects are validated when visited (and removed if invalid); otherwise only objects that have been idle for more than `minEvicableIdleTimeMillis` are removed.

    Successive activations of this method examine objects in keyed sub-pools in sequence, cycling through the keys and examining objects in oldest-to-youngest order within the keyed sub-pools.

    Specified by:
      `evict` in class `BaseGenericObjectPool<T>`
    Throws:
      `Exception` - when there is a problem evicting idle objects.

  - ### getFactory

    public KeyedPooledObjectFactory<K,T> getFactory()
    Gets a reference to the factory used to create, destroy and validate the objects used by this pool.
    Returns:
      the factory

  - ### getKeys

    public List<K> getKeys()
    Gets a copy of the pool key list.
    Specified by:
      `getKeys` in interface `KeyedObjectPool<K,T>`
    Returns:
      a copy of the pool key list.
    Since:
      2.12.0

  - ### getMaxIdlePerKey

    public int getMaxIdlePerKey()
    Gets the cap on the number of "idle" instances per key in the pool. If maxIdlePerKey is set too low on heavily loaded systems it is possible you will see objects being destroyed and almost immediately new objects being created. This is a result of the active threads momentarily returning objects faster than they are requesting them, causing the number of idle objects to rise above maxIdlePerKey. The best value for maxIdlePerKey for heavily loaded system will vary but the default is a good starting point.
    Specified by:
      `getMaxIdlePerKey` in interface `GenericKeyedObjectPoolMXBean<K>`
    Returns:
      the maximum number of "idle" instances that can be held in a given keyed sub-pool or a negative value if there is no limit
    See Also:
      - `setMaxIdlePerKey(int)`

  - ### getMaxTotalPerKey

    public int getMaxTotalPerKey()
    Gets the limit on the number of object instances allocated by the pool (checked out or idle), per key. When the limit is reached, the sub-pool is said to be exhausted. A negative value indicates no limit.
    Specified by:
      `getMaxTotalPerKey` in interface `GenericKeyedObjectPoolMXBean<K>`
    Returns:
      the limit on the number of active instances per key
    See Also:
      - `setMaxTotalPerKey(int)`

  - ### getMinIdlePerKey

    public int getMinIdlePerKey()
    Gets the target for the minimum number of idle objects to maintain in each of the keyed sub-pools. This setting only has an effect if it is positive and `BaseGenericObjectPool.getDurationBetweenEvictionRuns()` is greater than zero. If this is the case, an attempt is made to ensure that each sub-pool has the required minimum number of instances during idle object eviction runs.

    If the configured value of minIdlePerKey is greater than the configured value for maxIdlePerKey then the value of maxIdlePerKey will be used instead.

    Specified by:
      `getMinIdlePerKey` in interface `GenericKeyedObjectPoolMXBean<K>`
    Returns:
      minimum size of the each keyed pool
    See Also:
      - `BaseGenericObjectPool.setTimeBetweenEvictionRunsMillis(long)`

  - ### getNumActive

    public int getNumActive()
    Description copied from interface: `KeyedObjectPool`
    Gets the total number of instances currently borrowed from this pool but not yet returned. Returns a negative value if this information is not available.
    Specified by:
      `getNumActive` in interface `GenericKeyedObjectPoolMXBean<K>`
    Specified by:
      `getNumActive` in interface `KeyedObjectPool<K,T>`
    Returns:
      the total number of instances currently borrowed from this pool but not yet returned.

  - ### getNumActive

    public int getNumActive(K key)
    Description copied from interface: `KeyedObjectPool`
    Gets the number of instances currently borrowed from but not yet returned to the pool corresponding to the given `key`. Returns a negative value if this information is not available.
    Specified by:
      `getNumActive` in interface `KeyedObjectPool<K,T>`
    Parameters:
      `key` - the key to query
    Returns:
      the number of instances currently borrowed from but not yet returned to the pool corresponding to the given `key`.

  - ### getNumActivePerKey

    public Map<String,Integer> getNumActivePerKey()
    Description copied from interface: `GenericKeyedObjectPoolMXBean`
    See `getNumActivePerKey()`.
    Specified by:
      `getNumActivePerKey` in interface `GenericKeyedObjectPoolMXBean<K>`
    Returns:
      See `getNumActivePerKey()`.

  - ### getNumIdle

    public int getNumIdle()
    Description copied from class: `BaseGenericObjectPool`
    Gets the number of instances currently idle in this pool.
    Specified by:
      `getNumIdle` in interface `GenericKeyedObjectPoolMXBean<K>`
    Specified by:
      `getNumIdle` in interface `KeyedObjectPool<K,T>`
    Specified by:
      `getNumIdle` in class `BaseGenericObjectPool<T>`
    Returns:
      count of instances available for checkout from the pool

  - ### getNumIdle

    public int getNumIdle(K key)
    Description copied from interface: `KeyedObjectPool`
    Gets the number of instances corresponding to the given `key` currently idle in this pool. Returns a negative value if this information is not available.
    Specified by:
      `getNumIdle` in interface `KeyedObjectPool<K,T>`
    Parameters:
      `key` - the key to query
    Returns:
      the number of instances corresponding to the given `key` currently idle in this pool.

  - ### getNumWaiters

    public int getNumWaiters()
    Gets an estimate of the number of threads currently blocked waiting for an object from the pool. This is intended for monitoring only, not for synchronization control.
    Specified by:
      `getNumWaiters` in interface `GenericKeyedObjectPoolMXBean<K>`
    Returns:
      The estimate of the number of threads currently blocked waiting for an object from the pool

  - ### getNumWaitersByKey

    public Map<String,Integer> getNumWaitersByKey()
    Gets an estimate of the number of threads currently blocked waiting for an object from the pool for each key. This is intended for monitoring only, not for synchronization control.
    Specified by:
      `getNumWaitersByKey` in interface `GenericKeyedObjectPoolMXBean<K>`
    Returns:
      The estimate of the number of threads currently blocked waiting for an object from the pool for each key

  - ### invalidateObject

    public void invalidateObject(K key, T obj) throws Exception
    Invalidates an object from the pool.

    By contract, `obj` must have been obtained using `borrowObject` or a related method as defined in an implementation or sub-interface 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.

    Activation of this method decrements the active count associated with the given keyed pool and attempts to destroy `obj.`

    Specified by:
      `invalidateObject` in interface `KeyedObjectPool<K,T>`
    Parameters:
      `key` - pool key
      `obj` - instance to invalidate
    Throws:
      `Exception` - if an exception occurs destroying the object
      `IllegalStateException` - if obj does not belong to the pool under the given key

  - ### invalidateObject

    public void invalidateObject(K key, T obj, DestroyMode destroyMode) throws Exception
    Invalidates an object from the pool, using the provided `DestroyMode`.

    By contract, `obj` must have been obtained using `borrowObject` or a related method as defined in an implementation or sub-interface 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.

    Activation of this method decrements the active count associated with the given keyed pool and attempts to destroy `obj.`

    Specified by:
      `invalidateObject` in interface `KeyedObjectPool<K,T>`
    Parameters:
      `key` - pool key
      `obj` - instance to invalidate
      `destroyMode` - DestroyMode context provided to factory
    Throws:
      `Exception` - if an exception occurs destroying the object
      `IllegalStateException` - if obj does not belong to the pool under the given key
    Since:
      2.9.0

  - ### listAllObjects

    public Map<String,List<DefaultPooledObjectInfo>> listAllObjects()
    Provides information on all the objects in the pool, both idle (waiting to be borrowed) and active (currently borrowed).

    Note: This is named listAllObjects so it is presented as an operation via JMX. That means it won't be invoked unless the explicitly requested whereas all attributes will be automatically requested when viewing the attributes for an object in a tool like JConsole.

    Specified by:
      `listAllObjects` in interface `GenericKeyedObjectPoolMXBean<K>`
    Returns:
      Information grouped by key on all the objects in the pool

  - ### preparePool

    public void preparePool(K key) throws Exception
    Registers a key for pool control and ensures that `getMinIdlePerKey()` idle instances are created.
    Parameters:
      `key` - - The key to register for pool control.
    Throws:
      `Exception` - If the associated factory throws an exception

  - ### returnObject

    public void returnObject(K key, T obj)
    Returns an object to a keyed sub-pool.

    If `maxIdle` is set to a positive value and the number of idle instances under the given key has reached this value, the returning instance is destroyed.

    If `testOnReturn` == true, the returning instance is validated before being returned to the idle instance sub-pool under the given key. In this case, if validation fails, the instance is destroyed.

    Exceptions encountered destroying objects for any reason are swallowed but notified via a `SwallowedExceptionListener`.

    Specified by:
      `returnObject` in interface `KeyedObjectPool<K,T>`
    Parameters:
      `key` - pool key
      `obj` - instance to return to the keyed pool
    Throws:
      `IllegalStateException` - if an object is returned to the pool that was not borrowed from it or if an object is returned to the pool multiple times

  - ### setConfig

    public void setConfig(GenericKeyedObjectPoolConfig<T> conf)
    Sets the configuration.
    Parameters:
      `conf` - the new configuration to use. This is used by value.
    See Also:
      - `GenericKeyedObjectPoolConfig`

  - ### setMaxIdlePerKey

    public void setMaxIdlePerKey(int maxIdlePerKey)
    Sets the cap on the number of "idle" instances per key in the pool. If maxIdlePerKey is set too low on heavily loaded systems it is possible you will see objects being destroyed and almost immediately new objects being created. This is a result of the active threads momentarily returning objects faster than they are requesting them, causing the number of idle objects to rise above maxIdlePerKey. The best value for maxIdlePerKey for heavily loaded system will vary but the default is a good starting point.
    Parameters:
      `maxIdlePerKey` - the maximum number of "idle" instances that can be held in a given keyed sub-pool. Use a negative value for no limit
    See Also:
      - `getMaxIdlePerKey()`

  - ### setMaxTotalPerKey

    public void setMaxTotalPerKey(int maxTotalPerKey)
    Sets the limit on the number of object instances allocated by the pool (checked out or idle), per key. When the limit is reached, the sub-pool is said to be exhausted. A negative value indicates no limit.
    Parameters:
      `maxTotalPerKey` - the limit on the number of active instances per key
    See Also:
      - `getMaxTotalPerKey()`

  - ### setMinIdlePerKey

    public void setMinIdlePerKey(int minIdlePerKey)
    Sets the target for the minimum number of idle objects to maintain in each of the keyed sub-pools. This setting only has an effect if it is positive and `BaseGenericObjectPool.getDurationBetweenEvictionRuns()` is greater than zero. If this is the case, an attempt is made to ensure that each sub-pool has the required minimum number of instances during idle object eviction runs.

    If the configured value of minIdlePerKey is greater than the configured value for maxIdlePerKey then the value of maxIdlePerKey will be used instead.

    Parameters:
      `minIdlePerKey` - The minimum size of the each keyed pool
    See Also:
      - `getMinIdlePerKey()`
      - `getMaxIdlePerKey()`
      - `BaseGenericObjectPool.setDurationBetweenEvictionRuns(Duration)`

  - ### toStringAppendFields

    protected void toStringAppendFields(StringBuilder builder)
    Description copied from class: `BaseObject`
    Used by sub-classes to include the fields defined by the sub-class in the `BaseObject.toString()` output.
    Overrides:
      `toStringAppendFields` in class `BaseGenericObjectPool<T>`
    Parameters:
      `builder` - Field names and values are appended to this object

  - ### use

    public void use(T pooledObject)
    Description copied from interface: `UsageTracking`
    Called every time a pooled object is used to enable the pool to better track borrowed objects.
    Specified by:
      `use` in interface `UsageTracking<K>`
    Parameters:
      `pooledObject` - The object that is being used.
    Since:
      2.10.0