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.
GenericObjectPool
| Modifier and Type | Class and Description |
|---|---|
| private static class | GenericKeyedObjectPool.
type of objects in the pool S>Maintains information on the per key queue for a given key. |
| Modifier and Type | Field and Description |
|---|---|
| private K | |
| private Iterator | |
| private final KeyedPooledObjectFactory | |
| private final boolean | |
| private final ReadWriteLock | |
| private volatile int | |
| private volatile int | |
| private volatile int | |
| private final AtomicInteger | |
| private static final String | |
| private final ArrayList | |
| private final ConcurrentHashMap | |
| private volatile boolean | |
| private volatile boolean | |
| private static final Integer |
| Access | Constructor and Description |
|---|---|
| public | GenericKeyedObjectPool(final KeyedPooledObjectFactory<K, T>
the factory to be used to create entries factory)Constructs a new |
| public | GenericKeyedObjectPool(final KeyedPooledObjectFactory<K, T>
the factory to be used to create entries factory, final GenericKeyedObjectPoolConfig<T> 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. config)Constructs a new |
| public | GenericKeyedObjectPool(final KeyedPooledObjectFactory<K, T>
The object factory to be used to create object instances
used by this pool factory, final GenericKeyedObjectPoolConfig<T> 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. config, final AbandonedConfig Configuration for abandoned object identification
and removal. The configuration is used by value. abandonedConfig)Creates a new |
| Modifier and Type | Method and Description |
|---|---|
| private void | addIdleObject(final K
The key to associate with the idle object key, final PooledObject<T> The wrapped object to add. p)Add an object to the set of idle objects for a given key. |
| public void | addObject(final K
the key a new instance should be added to key)Implements org. Create an object using the |
| public T | borrowObject(final K key)
Implements org. Equivalent to |
| public T | Returns: object instance from the keyed poolpool key key, final Duration The time to wait for an object to become
available maxWaitDuration)Borrows an object from the sub-pool associated with the given key using
the specified waiting time which only applies if
|
| public T | Returns: object instance from the keyed poolpool key key, final long The time to wait in milliseconds for an object to become
available maxWaitMillis)Borrows an object from the sub-pool associated with the given key using
the specified waiting time which only applies if
|
| private int | Returns: The number of new objects to createThe set of objects to check objectDequeCalculate the number of objects that need to be created to attempt to maintain the minimum number of idle objects while not exceeded the limits on the maximum number of objects either per key or totally. |
| public void | clear()
Implements org. Clears any objects sitting idle in the pool by removing them from the
idle instance sub-pools and then invoking the configured
PoolableObjectFactory's
|
| public void | clear(final K
the key to clear key)Implements org. Clears the specified sub-pool, removing all pooled instances
corresponding to the given |
| public void | clear(final K
the key to clear key, final boolean whether or not to reuse freed capacity reuseCapacity)Clears the specified sub-pool, removing all pooled instances
corresponding to the given |
| public void | |
| public void | close()
Implements abstract org. Implements org. Closes the keyed object pool. |
| private PooledObject | |
| private void | |
| private boolean | Returns: true if the object was destroyed, otherwise falseThe key associated with the object to destroy key, final PooledObject<T> The wrapped object to be destroyed toDestroy, final boolean Should the object be destroyed even if it is not currently
in the set of idle objects for the given key always, final DestroyMode DestroyMode context provided to the factoryDestroy the wrapped, pooled object. |
| pack-priv void | ensureMinIdle()
Implements abstract org. Tries to ensure that the configured minimum number of idle instances are available in the pool. |
| private void | ensureMinIdle(final K
The key to check for idle objects key)Try to ensure that the configured number of minimum idle objects is available in the pool for the given key. |
| public void | evict()
Implements abstract org. Perform |
| public KeyedPooledObjectFactory | Returns: the factoryGets a reference to the factory used to create, destroy and validate the objects used by this pool. |
| public List | Returns: a copy of the pool key list.Overrides default org. Gets a copy of the pool key list. |
| public int | 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 limitImplements org. Gets the cap on the number of "idle" instances per key in the pool. |
| public int | Returns: the limit on the number of active instances per keyImplements org. Gets the limit on the number of object instances allocated by the pool (checked out or idle), per key. |
| public int | Returns: minimum size of the each keyed poolImplements org. Gets the target for the minimum number of idle objects to maintain in each of the keyed sub-pools. |
| public int | getNumActive()
Implements org. Gets the total number of instances currently borrowed from this pool but not yet returned. |
| public int | getNumActive(final K key)
Implements org. Gets the number of instances currently borrowed from but not yet
returned to the pool corresponding to the given |
| public Map | |
| public int | getNumIdle()
Implements abstract org. Implements org. Gets the total number of instances currently idle in this pool. |
| public int | getNumIdle(final K key)
Implements org. Gets the number of instances corresponding to the given
|
| private int | Returns: The number of objects to test for validityGets the number of objects to test in a run of the idle object evictor. |
| public int | Returns: The estimate of the number of threads currently blocked waiting for an object from the poolImplements org. Gets an estimate of the number of threads currently blocked waiting for an object from the pool. |
| public Map | Returns: The estimate of the number of threads currently blocked waiting for an object from the pool for each keyImplements org. Gets an estimate of the number of threads currently blocked waiting for an object from the pool for each key. |
| public boolean | Returns: true if capacity reuse is enabled during maintenance, false otherwiseGets whether to call |
| public boolean | Returns: true if capacity reuse is enabled on return, false otherwiseGets whether to call |
| pack-priv String | getStatsString()
Overrides org. Gets a statistics string. |
| private boolean | Returns: true if there is at least one thread waiting otherwise
falseTests to see if there are any threads currently waiting to borrow objects but are blocked waiting for more objects to become available. |
| public void | invalidateObject(final K
pool key key, final T instance to invalidate obj)Implements org. Invalidates an object from the pool. |
| public void | invalidateObject(final K
pool key key, final T instance to invalidate obj, final DestroyMode DestroyMode context provided to factory destroyMode)Overrides default org. Invalidates an object from the pool, using the provided
|
| public Map | Returns: Information grouped by key on all the objects in the poolImplements org. Provides information on all the objects in the pool, both idle (waiting to be borrowed) and active (currently borrowed). |
| public void | preparePool(final K
The key to register for pool control. key)Registers a key for pool control and ensures that
|
| private GenericKeyedObjectPool. | Returns: The objects currently associated with the given key. If this method returns without throwing an exception then it will never return null.The key to register k)Register the use of a key by an object. |
| private void | removeAbandoned(final AbandonedConfig
The configuration to use to identify abandoned objects abandonedConfig)Recovers abandoned objects which have been checked out but not used since longer than the removeAbandonedTimeout. |
| public void | returnObject(final K
pool key key, final T instance to return to the keyed pool obj)Implements org. Returns an object to a keyed sub-pool. |
| private void | reuseCapacity()
Attempt to create one new instance to serve from the most heavily loaded pool that can add a new instance. |
| private void | reuseCapacity(final int
number of times to call newCapacity)reuseCapacity()Call |
| public void | setConfig(final GenericKeyedObjectPoolConfig<T>
the new configuration to use. This is used by value. conf)Sets the configuration. |
| public void | setMaxIdlePerKey(final int
the maximum number of "idle" instances that can be
held in a given keyed sub-pool. Use a negative value
for no limit maxIdlePerKey)Sets the cap on the number of "idle" instances per key in the pool. |
| public void | setMaxTotalPerKey(final int
the limit on the number of active instances per key maxTotalPerKey)Sets the limit on the number of object instances allocated by the pool (checked out or idle), per key. |
| public void | setMinIdlePerKey(final int
The minimum size of the each keyed pool minIdlePerKey)Sets the target for the minimum number of idle objects to maintain in each of the keyed sub-pools. |
| public void | setReuseCapacityOnMaintenance(final boolean
true to enable capacity reuse during
maintenance, false to disableSets whether to call |
| public void | setReuseCapacityOnReturn(final boolean
true to enable capacity reuse on return,
false to disableSets whether to call |
| protected void | toStringAppendFields(final StringBuilder builder)
Overrides org. Used by sub-classes to include the fields defined by the sub-class in the
|
| public void | use(final T pooledObject)
Implements org. Called every time a pooled object is used to enable the pool to better track borrowed objects. |
| private void | whenWaitersAddObject(final K
pool key. key, final LinkedBlockingDeque<PooledObject<T>> deque backing the pool under the given key idleObjects)When there is at least one thread waiting on the given deque, try to add an instance to pool under the given key. |