K - The type of keys maintained by this pool.T - Type of element pooled in this pool.public class GenericKeyedObjectPool<K,T> extends BaseGenericObjectPool<T> implements KeyedObjectPool<K,T>, GenericKeyedObjectPoolMXBean<K>
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.
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 class |
GenericKeyedObjectPool.ObjectDeque<S>
Maintains information on the per key queue for a given key.
|
BaseGenericObjectPool.EvictionIterator, BaseGenericObjectPool.Evictor, BaseGenericObjectPool.IdentityWrapper<T>| Modifier and Type | Field and Description |
|---|---|
private K |
evictionKey |
private java.util.Iterator<K> |
evictionKeyIterator |
private KeyedPooledObjectFactory<K,T> |
factory |
private boolean |
fairness |
private java.util.concurrent.locks.ReadWriteLock |
keyLock |
private int |
maxIdlePerKey |
private int |
maxTotalPerKey |
private int |
minIdlePerKey |
private java.util.concurrent.atomic.AtomicInteger |
numTotal |
private static java.lang.String |
ONAME_BASE |
private java.util.List<K> |
poolKeyList |
private java.util.Map<K,GenericKeyedObjectPool.ObjectDeque<T>> |
poolMap |
closed, closeLock, createdCount, destroyedByBorrowValidationCount, destroyedByEvictorCount, destroyedCount, evictionIterator, evictionLock, MEAN_TIMING_STATS_CACHE_SIZE| Constructor and Description |
|---|
GenericKeyedObjectPool(KeyedPooledObjectFactory<K,T> factory)
Create a new
GenericKeyedObjectPool using defaults from
GenericKeyedObjectPoolConfig. |
GenericKeyedObjectPool(KeyedPooledObjectFactory<K,T> factory,
GenericKeyedObjectPoolConfig config)
Create a new
GenericKeyedObjectPool using a specific
configuration. |
| Modifier and Type | Method and Description |
|---|---|
private void |
addIdleObject(K key,
PooledObject<T> p)
Add an object to the set of idle objects for a given key.
|
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
|
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. |
private int |
calculateDeficit(GenericKeyedObjectPool.ObjectDeque<T> objectDeque)
Calculate 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.
|
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 |
clearOldest()
Clears oldest 15% of objects in pool.
|
void |
close()
Closes the keyed object pool.
|
private PooledObject<T> |
create(K key)
Create a new pooled object.
|
private void |
deregister(K k)
De-register the use of a key by an object.
|
private boolean |
destroy(K key,
PooledObject<T> toDestroy,
boolean always)
Destroy the wrapped, pooled object.
|
(package private) void |
ensureMinIdle()
Tries to ensure that the configured minimum number of idle instances are
available in the pool.
|
private void |
ensureMinIdle(K key)
Ensure that the configured number of minimum idle objects is available in
the pool for the given key.
|
void |
evict()
Perform
numTests idle object eviction tests, evicting
examined objects that meet the criteria for eviction. |
KeyedPooledObjectFactory<K,T> |
getFactory()
Obtain a reference to the factory used to create, destroy and validate
the objects used by this pool.
|
int |
getMaxIdlePerKey()
Returns the cap on the number of "idle" instances per key in the pool.
|
int |
getMaxTotalPerKey()
Returns the limit on the number of object instances allocated by the pool
(checked out or idle), per key.
|
int |
getMinIdlePerKey()
Returns the target for the minimum number of idle objects to maintain in
each of the keyed sub-pools.
|
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. |
java.util.Map<java.lang.String,java.lang.Integer> |
getNumActivePerKey()
|
int |
getNumIdle()
The 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. |
private int |
getNumTests()
Calculate the number of objects to test in a run of the idle object
evictor.
|
int |
getNumWaiters()
Return an estimate of the number of threads currently blocked waiting for
an object from the pool.
|
java.util.Map<java.lang.String,java.lang.Integer> |
getNumWaitersByKey()
Return an estimate of the number of threads currently blocked waiting for
an object from the pool for each key.
|
private boolean |
hasBorrowWaiters()
Checks to see if there are any threads currently waiting to borrow
objects but are blocked waiting for more objects to become available.
|
void |
invalidateObject(K key,
T obj)
Invalidates an object from the pool.
|
java.util.Map<java.lang.String,java.util.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. |
private GenericKeyedObjectPool.ObjectDeque<T> |
register(K k)
Register the use of a key by an object.
|
void |
returnObject(K key,
T obj)
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.
|
void |
setConfig(GenericKeyedObjectPoolConfig 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.
|
assertOpen, getBlockWhenExhausted, getBorrowedCount, getCreatedCount, getCreationStackTrace, getDestroyedByBorrowValidationCount, getDestroyedByEvictorCount, getDestroyedCount, getEvictionPolicy, getEvictionPolicyClassName, getFairness, getJmxName, getLifo, getMaxBorrowWaitTimeMillis, getMaxTotal, getMaxWaitMillis, getMeanActiveTimeMillis, getMeanBorrowWaitTimeMillis, getMeanIdleTimeMillis, getMinEvictableIdleTimeMillis, getNumTestsPerEvictionRun, getReturnedCount, getSoftMinEvictableIdleTimeMillis, getSwallowedExceptionListener, getTestOnBorrow, getTestOnCreate, getTestOnReturn, getTestWhileIdle, getTimeBetweenEvictionRunsMillis, isClosed, jmxUnregister, setBlockWhenExhausted, setEvictionPolicyClassName, setLifo, setMaxTotal, setMaxWaitMillis, setMinEvictableIdleTimeMillis, setNumTestsPerEvictionRun, setSoftMinEvictableIdleTimeMillis, setSwallowedExceptionListener, setTestOnBorrow, setTestOnCreate, setTestOnReturn, setTestWhileIdle, setTimeBetweenEvictionRunsMillis, startEvictor, swallowException, updateStatsBorrow, updateStatsReturnclone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, waitgetBlockWhenExhausted, getBorrowedCount, getCreatedCount, getCreationStackTrace, getDestroyedByBorrowValidationCount, getDestroyedByEvictorCount, getDestroyedCount, getFairness, getLifo, getMaxBorrowWaitTimeMillis, getMaxTotal, getMaxWaitMillis, getMeanActiveTimeMillis, getMeanBorrowWaitTimeMillis, getMeanIdleTimeMillis, getMinEvictableIdleTimeMillis, getNumTestsPerEvictionRun, getReturnedCount, getTestOnBorrow, getTestOnCreate, getTestOnReturn, getTestWhileIdle, getTimeBetweenEvictionRunsMillis, isClosedprivate volatile int maxIdlePerKey
private volatile int minIdlePerKey
private volatile int maxTotalPerKey
private final KeyedPooledObjectFactory<K,T> factory
private final boolean fairness
private final java.util.Map<K,GenericKeyedObjectPool.ObjectDeque<T>> poolMap
private final java.util.List<K> poolKeyList
private final java.util.concurrent.locks.ReadWriteLock keyLock
private final java.util.concurrent.atomic.AtomicInteger numTotal
private java.util.Iterator<K> evictionKeyIterator
private K evictionKey
private static final java.lang.String ONAME_BASE
public GenericKeyedObjectPool(KeyedPooledObjectFactory<K,T> factory)
GenericKeyedObjectPool using defaults from
GenericKeyedObjectPoolConfig.factory - the factory to be used to create entriespublic GenericKeyedObjectPool(KeyedPooledObjectFactory<K,T> factory, GenericKeyedObjectPoolConfig config)
GenericKeyedObjectPool using a specific
configuration.factory - the factory to be used to create entriesconfig - 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.public int getMaxTotalPerKey()
getMaxTotalPerKey in interface GenericKeyedObjectPoolMXBean<K>setMaxTotalPerKey(int)public void setMaxTotalPerKey(int maxTotalPerKey)
maxTotalPerKey - the limit on the number of active instances per keygetMaxTotalPerKey()public int getMaxIdlePerKey()
getMaxIdlePerKey in interface GenericKeyedObjectPoolMXBean<K>setMaxIdlePerKey(int)public void setMaxIdlePerKey(int maxIdlePerKey)
maxIdlePerKey - the maximum number of "idle" instances that can be
held in a given keyed sub-pool. Use a negative value
for no limitgetMaxIdlePerKey()public void setMinIdlePerKey(int minIdlePerKey)
BaseGenericObjectPool.getTimeBetweenEvictionRunsMillis() 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.
minIdlePerKey - The minimum size of the each keyed poolgetMinIdlePerKey(),
getMaxIdlePerKey(),
BaseGenericObjectPool.setTimeBetweenEvictionRunsMillis(long)public int getMinIdlePerKey()
BaseGenericObjectPool.getTimeBetweenEvictionRunsMillis() 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.
getMinIdlePerKey in interface GenericKeyedObjectPoolMXBean<K>BaseGenericObjectPool.setTimeBetweenEvictionRunsMillis(long)public void setConfig(GenericKeyedObjectPoolConfig conf)
conf - the new configuration to use. This is used by value.GenericKeyedObjectPoolConfigpublic KeyedPooledObjectFactory<K,T> getFactory()
public T borrowObject(K key) throws java.lang.Exception
borrowObject(key,
BaseGenericObjectPool.getMaxWaitMillis())
Obtains 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 behaviour of this method when the pool has been exhausted is not strictly specified (although it may be specified by implementations).
borrowObject in interface KeyedObjectPool<K,T>key - the key used to obtain the objectjava.lang.IllegalStateException - after close has been called on this pooljava.lang.Exception - when makeObject throws an exceptionjava.util.NoSuchElementException - when the pool is exhausted and cannot or will not return
another instancepublic T borrowObject(K key, long borrowMaxWaitMillis) throws java.lang.Exception
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 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.
key - pool keyborrowMaxWaitMillis - The time to wait in milliseconds for an object
to become availablejava.util.NoSuchElementException - if a keyed object instance cannot be
returned because the pool is exhausted.java.lang.Exception - if a keyed object instance cannot be returned due to an
errorpublic void returnObject(K key, T obj)
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.
returnObject in interface KeyedObjectPool<K,T>key - pool keyobj - instance to return to the keyed pooljava.lang.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 timespublic void invalidateObject(K key, T obj) throws java.lang.Exception
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.
invalidateObject in interface KeyedObjectPool<K,T>key - pool keyobj - instance to invalidatejava.lang.Exception - if an exception occurs destroying the
objectjava.lang.IllegalStateException - if obj does not belong to the pool
under the given keypublic void clear()
KeyedPooledObjectFactory.destroyObject(Object, PooledObject)
method on each idle instance.
Implementation notes:
SwallowedExceptionListener.clear in interface KeyedObjectPool<K,T>public void clear(K key)
key. Exceptions encountered
destroying idle instances are swallowed but notified via a
SwallowedExceptionListener.clear in interface KeyedObjectPool<K,T>key - the key to clearpublic int getNumActive()
KeyedObjectPoolgetNumActive in interface GenericKeyedObjectPoolMXBean<K>getNumActive in interface KeyedObjectPool<K,T>public int getNumIdle()
BaseGenericObjectPoolgetNumIdle in interface GenericKeyedObjectPoolMXBean<K>getNumIdle in interface KeyedObjectPool<K,T>getNumIdle in class BaseGenericObjectPool<T>public int getNumActive(K key)
KeyedObjectPoolkey.
Returns a negative value if this information is not available.getNumActive in interface KeyedObjectPool<K,T>key - the key to querykey.
=public int getNumIdle(K key)
KeyedObjectPoolkey currently idle in this pool. Returns a negative value if
this information is not available.getNumIdle in interface KeyedObjectPool<K,T>key - the key to querykey currently idle in this pool.public void close()
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().
close in interface KeyedObjectPool<K,T>close in class BaseGenericObjectPool<T>public void clearOldest()
private void reuseCapacity()
private boolean hasBorrowWaiters()
true if there is at least one thread waiting otherwise
falsepublic void evict()
throws java.lang.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.
evict in class BaseGenericObjectPool<T>java.lang.Exception - when there is a problem evicting idle objects.private PooledObject<T> create(K key) throws java.lang.Exception
key - Key associated with new pooled objectjava.lang.Exception - If the objection creation failsprivate boolean destroy(K key, PooledObject<T> toDestroy, boolean always) throws java.lang.Exception
key - The key associated with the object to destroy.toDestroy - The wrapped object to be destroyedalways - Should the object be destroyed even if it is not currently
in the set of idle objects for the given keytrue if the object was destroyed, otherwise falsejava.lang.Exception - If the object destruction failedprivate GenericKeyedObjectPool.ObjectDeque<T> register(K k)
register() and deregister() must always be used as a pair.
k - The key to registerprivate void deregister(K k)
register() and deregister() must always be used as a pair.
k - The key to de-registervoid ensureMinIdle()
throws java.lang.Exception
BaseGenericObjectPoolensureMinIdle in class BaseGenericObjectPool<T>java.lang.Exception - if an error occurs creating idle instancesprivate void ensureMinIdle(K key) throws java.lang.Exception
key - The key to check for idle objectsjava.lang.Exception - If a new object is required and cannot be createdpublic void addObject(K key) throws java.lang.Exception
factory, passivate it, and then place it in the idle object pool.
addObject is useful for "pre-loading" a pool with idle
objects.addObject in interface KeyedObjectPool<K,T>key - the key a new instance should be added tojava.lang.Exception - when KeyedPooledObjectFactory.makeObject(K)
fails.private void addIdleObject(K key, PooledObject<T> p) throws java.lang.Exception
key - The key to associate with the idle objectp - The wrapped object to add.java.lang.Exception - If the associated factory fails to passivate the objectpublic void preparePool(K key) throws java.lang.Exception
getMinIdlePerKey() idle instances are created.key - - The key to register for pool control.java.lang.Exception - If the associated factory throws an exceptionprivate int getNumTests()
private int calculateDeficit(GenericKeyedObjectPool.ObjectDeque<T> objectDeque)
objectDeque - The set of objects to checkpublic java.util.Map<java.lang.String,java.lang.Integer> getNumActivePerKey()
GenericKeyedObjectPoolMXBeangetNumActivePerKey in interface GenericKeyedObjectPoolMXBean<K>getNumActivePerKey()public int getNumWaiters()
getNumWaiters in interface GenericKeyedObjectPoolMXBean<K>public java.util.Map<java.lang.String,java.lang.Integer> getNumWaitersByKey()
getNumWaitersByKey in interface GenericKeyedObjectPoolMXBean<K>public java.util.Map<java.lang.String,java.util.List<DefaultPooledObjectInfo>> listAllObjects()
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.
listAllObjects in interface GenericKeyedObjectPoolMXBean<K>