* 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) {
* //...handle any exceptions...
* } finally {
* // make sure the object is returned to the pool
* if(null != obj) {
* pool.returnObject(key,obj);
* }
* } |
* {@link 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 {@link java.util.Map Map} of * {@link ObjectPool pools}). *
* * @author Rodney Waldhoff * @version $Revision: 1.1 $ $Date: 2004/02/22 11:58:26 $ * * @see KeyedPoolableObjectFactory * @see KeyedObjectPoolFactory * @see ObjectPool */ public interface KeyedObjectPool { /** * Obtain an instance from my pool * for the specified key. * By contract, clients MUST return * the borrowed object using * {@link #returnObject(java.lang.Object,java.lang.Object) returnObject}, * 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. * * @param key the key used to obtain the object * @return an instance from my pool. */ Object borrowObject(Object key) throws Exception; /** * Return an instance to my pool. * By contract, obj MUST have been obtained * using {@link #borrowObject(java.lang.Object) 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. * * @param key the key used to obtain the object * @param obj a {@link #borrowObject(java.lang.Object) borrowed} instance to be returned. */ void returnObject(Object key, Object obj) throws Exception; /** * Invalidates an object from the pool * By contract, obj MUST have been obtained * using {@link #borrowObject 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. * If the connection should be validated before or after borrowing, * then the {@link PoolableObjectFactory#validateObject} method should be * used instead. * * @param obj a {@link #borrowObject borrowed} instance to be returned. */ void invalidateObject(Object key, Object obj) throws Exception; /** * Create an object using my {@link #setFactory factory} or other * implementation dependent mechanism, and place it into the pool. * addObject() is useful for "pre-loading" a pool with idle objects. * (Optional operation). */ void addObject(Object key) throws Exception; /** * Returns the number of instances * corresponding to the given key * currently idle in my pool (optional operation). * Throws {@link UnsupportedOperationException} * if this information is not available. * * @param key the key * @return the number of instances corresponding to the given key currently idle in my pool * @throws UnsupportedOperationException when this implementation doesn't support the operation */ int getNumIdle(Object key) throws UnsupportedOperationException; /** * Returns the number of instances * currently borrowed from but not yet returned * to my pool corresponding to the * given key (optional operation). * Throws {@link UnsupportedOperationException} * if this information is not available. * * @param key the key * @return the number of instances corresponding to the given key currently borrowed in my pool * @throws UnsupportedOperationException when this implementation doesn't support the operation */ int getNumActive(Object key) throws UnsupportedOperationException; /** * Returns the total number of instances * currently idle in my pool (optional operation). * Throws {@link UnsupportedOperationException} * if this information is not available. * * @return the total number of instances currently idle in my pool * @throws UnsupportedOperationException when this implementation doesn't support the operation */ int getNumIdle() throws UnsupportedOperationException; /** * Returns the total number of instances * current borrowed from my pool but not * yet returned (optional operation). * Throws {@link UnsupportedOperationException} * if this information is not available. * * @return the total number of instances currently borrowed from my pool * @throws UnsupportedOperationException when this implementation doesn't support the operation */ int getNumActive() throws UnsupportedOperationException; /** * Clears my pool, removing all pooled instances * (optional operation). * Throws {@link UnsupportedOperationException} * if the pool cannot be cleared. * @throws UnsupportedOperationException when this implementation doesn't support the operation */ void clear() throws Exception, UnsupportedOperationException; /** * Clears the specified pool, removing all * pooled instances corresponding to * the given key (optional operation). * Throws {@link UnsupportedOperationException} * if the pool cannot be cleared. * @param key the key to clear * @throws UnsupportedOperationException when this implementation doesn't support the operation */ void clear(Object key) throws Exception, UnsupportedOperationException; /** * Close this pool, and free any resources associated with it. */ void close() throws Exception; /** * Sets the {@link KeyedPoolableObjectFactory factory} I use * to create new instances (optional operation). * @param factory the {@link KeyedPoolableObjectFactory} I use to create new instances. * @throws IllegalStateException when the factory cannot be set at this time * @throws UnsupportedOperationException when this implementation doesn't support the operation */ void setFactory(KeyedPoolableObjectFactory factory) throws IllegalStateException, UnsupportedOperationException; }