org.apache.commons.pool: public interface: KeyedObjectPool

org.apache.commons.pool
public interface: KeyedObjectPool [javadoc | source]

All Known Implementing Classes:
StackKeyedObjectPool, KeyedObjectPoolAdaptor, ErodingKeyedObjectPool, BaseKeyedObjectPool, CheckedKeyedObjectPool, ErodingPerKeyKeyedObjectPool, SynchronizedKeyedObjectPool, GenericKeyedObjectPool

A "keyed" pooling interface.

A keyed pool pools instances of multiple types. Each type may be accessed using an arbitrary key.

Example of use:

 Object obj = null;
Object key = "Key";

try {
obj = pool.borrowObject(key);
//...use the object...
} catch(Exception e) {
// invalidate the object
pool.invalidateObject(key, obj);
// do not return the object to the pool twice
obj = null;
} finally {
// make sure the object is returned to the pool
if(null != obj) {
pool.returnObject(key, obj);
}
}

KeyedObjectPool implementations may choose to store at most one instance per key value, or may choose to maintain a pool of instances for each key (essentially creating a Map of pools ).

See BaseKeyedObjectPool for a simple base implementation.

Also see:

KeyedPoolableObjectFactory

KeyedObjectPoolFactory

ObjectPool

BaseKeyedObjectPool

author: Rodney - Waldhoff

author: Sandy - McArthur

version: $ - Revision: 480413 $ $Date: 2006-11-28 22:16:05 -0700 (Tue, 28 Nov 2006) $

since: Pool - 1.0

Method from org.apache.commons.pool.KeyedObjectPool Summary:
addObject, borrowObject, clear, clear, close, getNumActive, getNumActive, getNumIdle, getNumIdle, invalidateObject, returnObject, setFactory

Method from org.apache.commons.pool.KeyedObjectPool Detail:
public void addObject(Object key) throws Exception, UnsupportedOperationException, IllegalStateException Create an object using the factory or other implementation dependent mechanism, passivate it, and then place it in the idle object pool. `addObject` is useful for "pre-loading" a pool with idle objects (Optional operation).
public Object borrowObject(Object key) throws Exception, NoSuchElementException, IllegalStateException 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 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). Older versions of this method would return `null` to indicate exhaustion, newer versions are encouraged to throw a NoSuchElementException .
public void clear() throws Exception, UnsupportedOperationException Clears the pool, removing all pooled instances (optional operation). Throws UnsupportedOperationException if the pool cannot be cleared.
public void clear(Object key) throws Exception, UnsupportedOperationException Clears the specified pool, removing all pooled instances corresponding to the given `key` (optional operation). Throws UnsupportedOperationException if the pool cannot be cleared.
public void close() throws Exception Close this pool, and free any resources associated with it. Calling addObject or borrowObject after invoking this method on a pool will cause them to throw an IllegalStateException .
public int getNumActive() throws UnsupportedOperationException Returns the total number of instances current borrowed from this pool but not yet returned (optional operation). Returns a negative value if this information is not available.
public int getNumActive(Object key) throws UnsupportedOperationException Returns the number of instances currently borrowed from but not yet returned to the pool corresponding to the given `key` (optional operation). Returns a negative value if this information is not available.
public int getNumIdle() throws UnsupportedOperationException Returns the total number of instances currently idle in this pool (optional operation). Returns a negative value if this information is not available.
public int getNumIdle(Object key) throws UnsupportedOperationException Returns the number of instances corresponding to the given `key` currently idle in this pool (optional operation). Returns a negative value if this information is not available.
public void invalidateObject(Object key, Object 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.
public void returnObject(Object key, Object obj) throws Exception Return an instance to 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 instance in the first place.
public void setFactory(KeyedPoolableObjectFactory factory) throws UnsupportedOperationException, IllegalStateException Sets the factory the pool uses to create new instances (optional operation). Trying to change the `factory` after a pool has been used will frequently throw an UnsupportedOperationException . It is up to the pool implementation to determine when it is acceptable to call this method.