GenericKeyedObjectPool

A configurable <code>KeyedObjectPool</code> implementation. When coupled with the appropriate {@link KeyedPooledObjectFactory}, <code>GenericKeyedObjectPool</code> provides robust pooling functionality for keyed objects. A <code>GenericKeyedObjectPool</code> can be viewed as a map of sub-pools, keyed on the (unique) key values provided to the {@link #preparePool preparePool}, {@link #addObject addObject} or {@link #borrowObject 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 <code>GenericKeyedObjectPool.</code> 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.

@see GenericObjectPool

@param <K> The type of keys maintained by this pool. @param <T> Type of element pooled in this pool.

class GenericKeyedObjectPool : BaseGenericObjectPool!(T), KeyedObjectPool!(K, T), GenericKeyedObjectPoolMXBean!(K)(

) {

this(KeyedPooledObjectFactory!(K, T) factory);

this(KeyedPooledObjectFactory!(K, T) factory, GenericKeyedObjectPoolConfig!(T) config);

int getMaxTotalPerKey();

void setMaxTotalPerKey(int maxTotalPerKey);

int getMaxIdlePerKey();

void setMaxIdlePerKey(int maxIdlePerKey);

void setMinIdlePerKey(int minIdlePerKey);

int getMinIdlePerKey();

void setConfig(GenericKeyedObjectPoolConfig!(T) conf);

KeyedPooledObjectFactory!(K, T) getFactory();

T borrowObject(K key);

T borrowObject(K key, long borrowMaxWaitMillis);

void returnObject(K key, T obj);

void invalidateObject(K key, T obj);

void clear();

void clear(K key);

int getNumActive();

int getNumIdle();

int getNumActive(K key);

int getNumIdle(K key);

void close();

void clearOldest();

void evict();

void ensureMinIdle();

void addObject(K key);

void preparePool(K key);

Map!(string, Integer) getNumActivePerKey();

int getNumWaiters();

Map!(string, Integer) getNumWaitersByKey();

Map!(string, List!(DefaultPooledObjectInfo)) listAllObjects();

void toStringAppendFields(StringBuilder builder);

}

Constructors

this this(KeyedPooledObjectFactory!(K, T) factory): Create a new <code>GenericKeyedObjectPool</code> using defaults from {@link GenericKeyedObjectPoolConfig}. @param factory the factory to be used to create entries
this this(KeyedPooledObjectFactory!(K, T) factory, GenericKeyedObjectPoolConfig!(T) config): Create a new <code>GenericKeyedObjectPool</code> using a specific configuration.

Members

Functions

addObject void addObject(K key): Create an object using the {@link KeyedPooledObjectFactory#makeObject factory}, passivate it, and then place it in the idle object pool. <code>addObject</code> is useful for "pre-loading" a pool with idle objects.
borrowObject T borrowObject(K key): Equivalent to <code>{@link #borrowObject(Object, long) borrowObject}(key, {@link #getMaxWaitMillis()})</code>. {@inheritDoc}
borrowObject 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 {@link #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 {@link #getLifo()}, activated and returned. If activation fails, or {@link #getTestOnBorrow() testOnBorrow} is set to <code>true</code> 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 {@link #getMaxTotalPerKey() maxTotalPerKey}, {@link #getMaxTotal() maxTotal}, and (if applicable) {@link #getBlockWhenExhausted()} and the value passed in to the <code>borrowMaxWaitMillis</code> parameter. If the number of instances checked out from the sub-pool under the given key is less than <code>maxTotalPerKey</code> and the total number of instances in circulation (under all keys) is less than <code>maxTotal</code>, a new instance is created, activated and (if applicable) validated and returned to the caller. If validation fails, a <code>NoSuchElementException</code> 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 ({@link #getBlockWhenExhausted()} is true) or throw a <code>NoSuchElementException</code> ({@link #getBlockWhenExhausted()} is false). The length of time that this method will block when {@link #getBlockWhenExhausted()} is true is determined by the value passed in to the <code>borrowMaxWait</code> parameter. When <code>maxTotal</code> 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.
clear 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 {@link KeyedPooledObjectFactory#destroyObject(Object, PooledObject)} method on each idle instance. Implementation notes: <ul> <li>This method does not destroy or effect in any way instances that are checked out when it is invoked.</li> <li>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.</li> <li>Exceptions encountered destroying idle instances are swallowed but notified via a {@link SwallowedExceptionListener}.</li> </ul>
clear void clear(K key): Clears the specified sub-pool, removing all pooled instances corresponding to the given <code>key</code>. Exceptions encountered destroying idle instances are swallowed but notified via a {@link SwallowedExceptionListener}.
clearOldest 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 void close(): Closes the keyed object pool. Once the pool is closed, {@link #borrowObject(Object)} will fail with IllegalStateException, but {@link #returnObject(Object, Object)} and {@link #invalidateObject(Object, Object)} will continue to work, with returned objects destroyed on return. Destroys idle instances in the pool by invoking {@link #clear()}.
ensureMinIdle void ensureMinIdle(): Undocumented in source. Be warned that the author may not have intended to support it.
evict void evict(): {@inheritDoc} 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.
getFactory KeyedPooledObjectFactory!(K, T) getFactory(): Obtain a reference to the factory used to create, destroy and validate the objects used by this pool.
getMaxIdlePerKey int getMaxIdlePerKey(): Returns 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.
getMaxTotalPerKey int getMaxTotalPerKey(): Returns 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.
getMinIdlePerKey int getMinIdlePerKey(): Returns 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 {@link #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.
getNumActive int getNumActive(): Undocumented in source. Be warned that the author may not have intended to support it.
getNumActive int getNumActive(K key): Undocumented in source. Be warned that the author may not have intended to support it.
getNumActivePerKey Map!(string, Integer) getNumActivePerKey(): Undocumented in source. Be warned that the author may not have intended to support it.
getNumIdle int getNumIdle(): Undocumented in source. Be warned that the author may not have intended to support it.
getNumIdle int getNumIdle(K key): Undocumented in source. Be warned that the author may not have intended to support it.
getNumWaiters int getNumWaiters(): Return 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.
getNumWaitersByKey Map!(string, Integer) getNumWaitersByKey(): Return 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.
invalidateObject void invalidateObject(K key, T obj): {@inheritDoc} Activation of this method decrements the active count associated with the given keyed pool and attempts to destroy <code>obj.</code>
listAllObjects 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.
preparePool void preparePool(K key): Registers a key for pool control and ensures that {@link #getMinIdlePerKey()} idle instances are created.
returnObject void returnObject(K key, T obj): Returns an object to a keyed sub-pool. If {@link #getMaxIdlePerKey() 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 {@link #getTestOnReturn() 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 {@link SwallowedExceptionListener}.
setConfig void setConfig(GenericKeyedObjectPoolConfig!(T) conf): Sets the configuration.
setMaxIdlePerKey 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.
setMaxTotalPerKey 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.
setMinIdlePerKey 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 {@link #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.
toStringAppendFields void toStringAppendFields(StringBuilder builder): Undocumented in source. Be warned that the author may not have intended to support it.

GenericKeyedObjectPool

Constructors

Members

Functions

Meta

Source