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>, UsageTracking<T>
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.
GenericObjectPoolMEAN_TIMING_STATS_CACHE_SIZE| 构造器和说明 |
|---|
GenericKeyedObjectPool(KeyedPooledObjectFactory<K,T> factory)
Create a new
GenericKeyedObjectPool using defaults from
GenericKeyedObjectPoolConfig. |
GenericKeyedObjectPool(KeyedPooledObjectFactory<K,T> factory,
GenericKeyedObjectPoolConfig<T> config)
Create 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. |
| 限定符和类型 | 方法和说明 |
|---|---|
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. |
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.
|
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.
|
boolean |
getLogAbandoned()
Gets whether this pool identifies and logs any abandoned objects.
|
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. |
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)
Gets the number of instances corresponding to the given
key currently idle in this pool. |
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.
|
boolean |
getRemoveAbandonedOnBorrow()
Gets whether a check is made for abandoned objects when an object is borrowed
from this pool.
|
boolean |
getRemoveAbandonedOnMaintenance()
Gets whether a check is made for abandoned objects when the evictor runs.
|
int |
getRemoveAbandonedTimeout()
已过时。
|
java.time.Duration |
getRemoveAbandonedTimeoutDuration()
Gets the timeout before which an object will be considered to be
abandoned by this pool.
|
void |
invalidateObject(K key,
T obj)
Invalidates an object from the pool.
|
void |
invalidateObject(K key,
T obj,
DestroyMode mode)
Invalidates an object from the pool, using the provided
DestroyMode. |
boolean |
isAbandonedConfig()
Gets whether or not abandoned object removal is configured for this 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. |
void |
returnObject(K key,
T obj)
Returns an object to a keyed sub-pool.
|
void |
setAbandonedConfig(AbandonedConfig abandonedConfig)
Sets the abandoned object removal configuration.
|
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.
|
void |
use(T pooledObject)
This method is called every time a pooled object is used to enable the pool to
better track borrowed objects.
|
getBlockWhenExhausted, getBorrowedCount, getCreatedCount, getCreationStackTrace, getDestroyedByBorrowValidationCount, getDestroyedByEvictorCount, getDestroyedCount, getEvictionPolicy, getEvictionPolicyClassName, getEvictorShutdownTimeout, getEvictorShutdownTimeoutMillis, getFairness, getJmxName, getLifo, getMaxBorrowWaitTimeMillis, getMaxTotal, getMaxWaitMillis, getMeanActiveTimeMillis, getMeanBorrowWaitTimeMillis, getMeanIdleTimeMillis, getMinEvictableIdleTime, getMinEvictableIdleTimeMillis, getNumTestsPerEvictionRun, getReturnedCount, getSoftMinEvictableIdleTime, getSoftMinEvictableIdleTimeMillis, getSwallowedExceptionListener, getTestOnBorrow, getTestOnCreate, getTestOnReturn, getTestWhileIdle, getTimeBetweenEvictionRuns, getTimeBetweenEvictionRunsMillis, isClosed, setBlockWhenExhausted, setEvictionPolicy, setEvictionPolicyClassName, setEvictionPolicyClassName, setEvictorShutdownTimeout, setEvictorShutdownTimeoutMillis, setLifo, setMaxTotal, setMaxWaitMillis, setMinEvictableIdleTime, setMinEvictableIdleTimeMillis, setNumTestsPerEvictionRun, setSoftMinEvictableIdleTime, setSoftMinEvictableIdleTimeMillis, setSwallowedExceptionListener, setTestOnBorrow, setTestOnCreate, setTestOnReturn, setTestWhileIdle, setTimeBetweenEvictionRuns, setTimeBetweenEvictionRunsMillistoStringaddObjects, addObjectsgetBlockWhenExhausted, getBorrowedCount, getCreatedCount, getCreationStackTrace, getDestroyedByBorrowValidationCount, getDestroyedByEvictorCount, getDestroyedCount, getFairness, getLifo, getMaxBorrowWaitTimeMillis, getMaxTotal, getMaxWaitMillis, getMeanActiveTimeMillis, getMeanBorrowWaitTimeMillis, getMeanIdleTimeMillis, getMinEvictableIdleTimeMillis, getNumTestsPerEvictionRun, getReturnedCount, getTestOnBorrow, getTestOnCreate, getTestOnReturn, getTestWhileIdle, getTimeBetweenEvictionRunsMillis, isClosedpublic 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<T> 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 GenericKeyedObjectPool(KeyedPooledObjectFactory<K,T> factory, GenericKeyedObjectPoolConfig<T> config, AbandonedConfig abandonedConfig)
GenericKeyedObjectPool that tracks and destroys
objects that are checked out, but never returned to the pool.factory - The object factory to be used to create object instances
used by this poolconfig - 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.public 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 在接口中 KeyedObjectPool<K,T>key - the key a new instance should be added tojava.lang.Exception - when KeyedPooledObjectFactory.makeObject(K)
fails.public T borrowObject(K key) throws java.lang.Exception
borrowObject(key,
BaseGenericObjectPool.getMaxWaitMillis())
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).
borrowObject 在接口中 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 clear()
KeyedPooledObjectFactory.destroyObject(Object, PooledObject)
method on each idle instance.
Implementation notes:
SwallowedExceptionListener.clear 在接口中 KeyedObjectPool<K,T>public void clear(K key)
key. Exceptions encountered
destroying idle instances are swallowed but notified via a
SwallowedExceptionListener.clear 在接口中 KeyedObjectPool<K,T>key - the key to clearpublic void clearOldest()
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 在接口中 java.io.Closeableclose 在接口中 java.lang.AutoCloseableclose 在接口中 KeyedObjectPool<K,T>close 在类中 BaseGenericObjectPool<T>public 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 在类中 BaseGenericObjectPool<T>java.lang.Exception - when there is a problem evicting idle objects.public KeyedPooledObjectFactory<K,T> getFactory()
public boolean getLogAbandoned()
getLogAbandoned 在接口中 GenericKeyedObjectPoolMXBean<K>true if abandoned object removal is configured for this
pool and removal events are to be logged otherwise falseAbandonedConfig.getLogAbandoned()public int getMaxIdlePerKey()
getMaxIdlePerKey 在接口中 GenericKeyedObjectPoolMXBean<K>setMaxIdlePerKey(int)public int getMaxTotalPerKey()
getMaxTotalPerKey 在接口中 GenericKeyedObjectPoolMXBean<K>setMaxTotalPerKey(int)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 在接口中 GenericKeyedObjectPoolMXBean<K>BaseGenericObjectPool.setTimeBetweenEvictionRunsMillis(long)public int getNumActive()
KeyedObjectPoolgetNumActive 在接口中 GenericKeyedObjectPoolMXBean<K>getNumActive 在接口中 KeyedObjectPool<K,T>public int getNumActive(K key)
KeyedObjectPoolkey.
Returns a negative value if this information is not available.getNumActive 在接口中 KeyedObjectPool<K,T>key - the key to querykey.public java.util.Map<java.lang.String,java.lang.Integer> getNumActivePerKey()
GenericKeyedObjectPoolMXBeangetNumActivePerKey 在接口中 GenericKeyedObjectPoolMXBean<K>getNumActivePerKey()public int getNumIdle()
BaseGenericObjectPoolgetNumIdle 在接口中 GenericKeyedObjectPoolMXBean<K>getNumIdle 在接口中 KeyedObjectPool<K,T>getNumIdle 在类中 BaseGenericObjectPool<T>public int getNumIdle(K key)
KeyedObjectPoolkey currently idle in this pool. Returns a negative value if
this information is not available.getNumIdle 在接口中 KeyedObjectPool<K,T>key - the key to querykey currently idle in this pool.public int getNumWaiters()
getNumWaiters 在接口中 GenericKeyedObjectPoolMXBean<K>public java.util.Map<java.lang.String,java.lang.Integer> getNumWaitersByKey()
getNumWaitersByKey 在接口中 GenericKeyedObjectPoolMXBean<K>public boolean getRemoveAbandonedOnBorrow()
getRemoveAbandonedOnBorrow 在接口中 GenericKeyedObjectPoolMXBean<K>true if abandoned object removal is configured to be
activated by borrowObject otherwise falseAbandonedConfig.getRemoveAbandonedOnBorrow()public boolean getRemoveAbandonedOnMaintenance()
getRemoveAbandonedOnMaintenance 在接口中 GenericKeyedObjectPoolMXBean<K>true if abandoned object removal is configured to be
activated when the evictor runs otherwise falseAbandonedConfig.getRemoveAbandonedOnMaintenance()@Deprecated public int getRemoveAbandonedTimeout()
getRemoveAbandonedTimeoutDuration().getRemoveAbandonedTimeout 在接口中 GenericKeyedObjectPoolMXBean<K>AbandonedConfig.getRemoveAbandonedTimeout(),
AbandonedConfig.getRemoveAbandonedTimeoutDuration()public java.time.Duration getRemoveAbandonedTimeoutDuration()
AbandonedConfig.getRemoveAbandonedTimeout(),
AbandonedConfig.getRemoveAbandonedTimeoutDuration()public 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 在接口中 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 invalidateObject(K key, T obj, DestroyMode mode) throws java.lang.Exception
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.
invalidateObject 在接口中 KeyedObjectPool<K,T>key - pool keyobj - instance to invalidatemode - DestroyMode context provided to factoryjava.lang.Exception - if an exception occurs destroying the
objectjava.lang.IllegalStateException - if obj does not belong to the pool
under the given keypublic boolean isAbandonedConfig()
isAbandonedConfig 在接口中 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 在接口中 GenericKeyedObjectPoolMXBean<K>public 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 exceptionpublic 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 在接口中 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 setAbandonedConfig(AbandonedConfig abandonedConfig)
abandonedConfig - the new configuration to use. This is used by value.AbandonedConfigpublic void setConfig(GenericKeyedObjectPoolConfig<T> conf)
conf - the new configuration to use. This is used by value.GenericKeyedObjectPoolConfigpublic 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 setMaxTotalPerKey(int maxTotalPerKey)
maxTotalPerKey - the limit on the number of active instances per keygetMaxTotalPerKey()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 void use(T pooledObject)
UsageTrackinguse 在接口中 UsageTracking<T>pooledObject - The object that is being used