org.apache.commons.pool2.impl
Class GenericKeyedObjectPool<K,T>

java.lang.Object
  extended by org.apache.commons.pool2.impl.BaseGenericObjectPool<T>
      extended by org.apache.commons.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:
GenericKeyedObjectPoolMXBean<K>, KeyedObjectPool<K,T>

public class GenericKeyedObjectPool<K,T>
extends BaseGenericObjectPool<T>
implements KeyedObjectPool<K,T>, GenericKeyedObjectPoolMXBean<K>

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.

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
Version:
$Revision: 1537359 $
See Also:
GenericObjectPool

Field Summary
 
Fields inherited from class org.apache.commons.pool2.impl.BaseGenericObjectPool
MEAN_TIMING_STATS_CACHE_SIZE
 
Constructor Summary
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.
 
Method Summary
 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.getMaxWaitMillis()).
 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.
 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.
 Map<String,Integer> getNumActivePerKey()
          See 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.
 int getNumWaiters()
          Return an estimate of the number of threads currently blocked waiting for an object from the pool.
 Map<String,Integer> getNumWaitersByKey()
          Return 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.
 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 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.
 
Methods inherited from class org.apache.commons.pool2.impl.BaseGenericObjectPool
getBlockWhenExhausted, getBorrowedCount, getCreatedCount, getCreationStackTrace, getDestroyedByBorrowValidationCount, getDestroyedByEvictorCount, getDestroyedCount, getEvictionPolicyClassName, getJmxName, getLifo, getMaxBorrowWaitTimeMillis, getMaxTotal, getMaxWaitMillis, getMeanActiveTimeMillis, getMeanBorrowWaitTimeMillis, getMeanIdleTimeMillis, getMinEvictableIdleTimeMillis, getNumTestsPerEvictionRun, getReturnedCount, getSoftMinEvictableIdleTimeMillis, getSwallowedExceptionListener, getTestOnBorrow, getTestOnReturn, getTestWhileIdle, getTimeBetweenEvictionRunsMillis, isClosed, setBlockWhenExhausted, setEvictionPolicyClassName, setLifo, setMaxTotal, setMaxWaitMillis, setMinEvictableIdleTimeMillis, setNumTestsPerEvictionRun, setSoftMinEvictableIdleTimeMillis, setSwallowedExceptionListener, setTestOnBorrow, setTestOnReturn, setTestWhileIdle, setTimeBetweenEvictionRunsMillis
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface org.apache.commons.pool2.impl.GenericKeyedObjectPoolMXBean
getBlockWhenExhausted, getBorrowedCount, getCreatedCount, getCreationStackTrace, getDestroyedByBorrowValidationCount, getDestroyedByEvictorCount, getDestroyedCount, getLifo, getMaxBorrowWaitTimeMillis, getMaxTotal, getMaxWaitMillis, getMeanActiveTimeMillis, getMeanBorrowWaitTimeMillis, getMeanIdleTimeMillis, getMinEvictableIdleTimeMillis, getNumTestsPerEvictionRun, getReturnedCount, getTestOnBorrow, getTestOnReturn, getTestWhileIdle, getTimeBetweenEvictionRunsMillis, isClosed
 

Constructor Detail

GenericKeyedObjectPool

public GenericKeyedObjectPool(KeyedPooledObjectFactory<K,T> factory)
Create 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 config)
Create 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.
Method Detail

getMaxTotalPerKey

public 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.

Specified by:
getMaxTotalPerKey in interface GenericKeyedObjectPoolMXBean<K>
Returns:
the limit on the number of active instances per key
See Also:
setMaxTotalPerKey(int)

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()

getMaxIdlePerKey

public 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 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)

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 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()

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.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.

Parameters:
minIdlePerKey - The minimum size of the each keyed pool
See Also:
getMinIdlePerKey(), getMaxIdlePerKey(), BaseGenericObjectPool.setTimeBetweenEvictionRunsMillis(long)

getMinIdlePerKey

public 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 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.

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

setConfig

public void setConfig(GenericKeyedObjectPoolConfig conf)
Sets the configuration.

Parameters:
conf - the new configuration to use. This is used by value.
See Also:
GenericKeyedObjectPoolConfig

getFactory

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

Returns:
the factory

borrowObject

public T borrowObject(K key)
               throws Exception
Equivalent to 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).

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 borrowMaxWait 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 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, 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.
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

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

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:

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.

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

getNumActive

public int getNumActive()
Description copied from interface: KeyedObjectPool
Returns the total number of instances current 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 current borrowed from this pool but not yet returned.

getNumIdle

public int getNumIdle()
Description copied from class: BaseGenericObjectPool
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

getNumActive

public int getNumActive(K key)
Description copied from interface: KeyedObjectPool
Returns 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. =

getNumIdle

public int getNumIdle(K key)
Description copied from interface: KeyedObjectPool
Returns 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.

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 KeyedObjectPool<K,T>
Specified by:
close in class BaseGenericObjectPool<T>

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.


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.

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.

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.

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

getNumActivePerKey

public Map<String,Integer> getNumActivePerKey()
Description copied from interface: GenericKeyedObjectPoolMXBean
See getNumActivePerKey()

Specified by:
getNumActivePerKey in interface GenericKeyedObjectPoolMXBean<K>
Returns:
See getNumActivePerKey()

getNumWaiters

public 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.

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()
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.

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

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


Copyright © 2001-2013 The Apache Software Foundation. All Rights Reserved.