Coverage Report - org.apache.commons.pool.KeyedObjectPool
 
Classes in this File Line Coverage Branch Coverage Complexity
KeyedObjectPool
N/A
N/A
1
 
 1  
 /*
 2  
  * Licensed to the Apache Software Foundation (ASF) under one or more
 3  
  * contributor license agreements.  See the NOTICE file distributed with
 4  
  * this work for additional information regarding copyright ownership.
 5  
  * The ASF licenses this file to You under the Apache License, Version 2.0
 6  
  * (the "License"); you may not use this file except in compliance with
 7  
  * the License.  You may obtain a copy of the License at
 8  
  *
 9  
  *      http://www.apache.org/licenses/LICENSE-2.0
 10  
  *
 11  
  * Unless required by applicable law or agreed to in writing, software
 12  
  * distributed under the License is distributed on an "AS IS" BASIS,
 13  
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 14  
  * See the License for the specific language governing permissions and
 15  
  * limitations under the License.
 16  
  */
 17  
 
 18  
 package org.apache.commons.pool;
 19  
 
 20  
 import java.util.NoSuchElementException;
 21  
 
 22  
 /**
 23  
  * A "keyed" pooling interface.
 24  
  * <p>
 25  
  * A keyed pool pools instances of multiple types. Each
 26  
  * type may be accessed using an arbitrary key.
 27  
  * </p>
 28  
  * <p>
 29  
  * Example of use:
 30  
  * <pre style="border:solid thin; padding: 1ex;"
 31  
  * > Object obj = <code style="color:#00C">null</code>;
 32  
  * Object key = <code style="color:#C00">"Key"</code>;
 33  
  *
 34  
  * <code style="color:#00C">try</code> {
 35  
  *     obj = pool.borrowObject(key);
 36  
  *     <code style="color:#0C0">//...use the object...</code>
 37  
  * } <code style="color:#00C">catch</code>(Exception e) {
 38  
  *     <code style="color:#0C0">// invalidate the object</code>
 39  
  *     pool.invalidateObject(key, obj);
 40  
  *     <code style="color:#0C0">// do not return the object to the pool twice</code>
 41  
  *     obj = <code style="color:#00C">null</code>;
 42  
  * } <code style="color:#00C">finally</code> {
 43  
  *     <code style="color:#0C0">// make sure the object is returned to the pool</code>
 44  
  *     <code style="color:#00C">if</code>(<code style="color:#00C">null</code> != obj) {
 45  
  *         pool.returnObject(key, obj);
 46  
  *     }
 47  
  * }</pre>
 48  
  * </p>
 49  
  * <p>
 50  
  * {@link KeyedObjectPool} implementations <i>may</i> choose to store at most
 51  
  * one instance per key value, or may choose to maintain a pool of instances
 52  
  * for each key (essentially creating a {@link java.util.Map Map} of
 53  
  * {@link ObjectPool pools}).
 54  
  * </p>
 55  
  *
 56  
  * <p>See {@link BaseKeyedObjectPool} for a simple base implementation.</p>
 57  
  *
 58  
  * @author Rodney Waldhoff
 59  
  * @author Sandy McArthur
 60  
  * @version $Revision: 778480 $ $Date: 2009-05-25 15:34:55 -0400 (Mon, 25 May 2009) $
 61  
  * @see KeyedPoolableObjectFactory
 62  
  * @see KeyedObjectPoolFactory
 63  
  * @see ObjectPool
 64  
  * @see BaseKeyedObjectPool
 65  
  * @since Pool 1.0
 66  
  */
 67  
 public interface KeyedObjectPool {
 68  
     /**
 69  
      * Obtains an instance from this pool for the specified <code>key</code>.
 70  
      * <p>
 71  
      * Instances returned from this method will have been either newly created with
 72  
      * {@link KeyedPoolableObjectFactory#makeObject makeObject} or will be a previously idle object and
 73  
      * have been activated with {@link KeyedPoolableObjectFactory#activateObject activateObject} and
 74  
      * then validated with {@link KeyedPoolableObjectFactory#validateObject validateObject}.
 75  
      * <p>
 76  
      * By contract, clients <strong>must</strong> return the borrowed object using
 77  
      * {@link #returnObject returnObject}, {@link #invalidateObject invalidateObject}, or a related method
 78  
      * as defined in an implementation or sub-interface,
 79  
      * using a <code>key</code> that is {@link Object#equals equivalent} to the one used to
 80  
      * borrow the instance in the first place.
 81  
      * <p>
 82  
      * The behaviour of this method when the pool has been exhausted
 83  
      * is not strictly specified (although it may be specified by implementations).
 84  
      * Older versions of this method would return <code>null</code> to indicate exhaustion,
 85  
      * newer versions are encouraged to throw a {@link NoSuchElementException}.
 86  
      *
 87  
      * @param key the key used to obtain the object
 88  
      * @return an instance from this pool.
 89  
      * @throws IllegalStateException after {@link #close close} has been called on this pool
 90  
      * @throws Exception when {@link KeyedPoolableObjectFactory#makeObject makeObject} throws an exception
 91  
      * @throws NoSuchElementException when the pool is exhausted and cannot or will not return another instance
 92  
      */
 93  
     Object borrowObject(Object key) throws Exception, NoSuchElementException, IllegalStateException;
 94  
 
 95  
     /**
 96  
      * Return an instance to the pool.
 97  
      * By contract, <code>obj</code> <strong>must</strong> have been obtained
 98  
      * using {@link #borrowObject borrowObject}
 99  
      * or a related method as defined in an implementation
 100  
      * or sub-interface
 101  
      * using a <code>key</code> that is equivalent to the one used to
 102  
      * borrow the instance in the first place.
 103  
      *
 104  
      * @param key the key used to obtain the object
 105  
      * @param obj a {@link #borrowObject borrowed} instance to be returned.
 106  
      * @throws Exception 
 107  
      */
 108  
     void returnObject(Object key, Object obj) throws Exception;
 109  
 
 110  
     /**
 111  
      * Invalidates an object from the pool
 112  
      * By contract, <code>obj</code> <strong>must</strong> have been obtained
 113  
      * using {@link #borrowObject borrowObject}
 114  
      * or a related method as defined in an implementation
 115  
      * or sub-interface
 116  
      * using a <code>key</code> that is equivalent to the one used to
 117  
      * borrow the <code>Object</code> in the first place.
 118  
      * <p>
 119  
      * This method should be used when an object that has been borrowed
 120  
      * is determined (due to an exception or other problem) to be invalid.
 121  
      * </p>
 122  
      *
 123  
      * @param key the key used to obtain the object
 124  
      * @param obj a {@link #borrowObject borrowed} instance to be returned.
 125  
      * @throws Exception 
 126  
      */
 127  
     void invalidateObject(Object key, Object obj) throws Exception;
 128  
 
 129  
     /**
 130  
      * Create an object using the {@link KeyedPoolableObjectFactory factory} or other
 131  
      * implementation dependent mechanism, passivate it, and then place it in the idle object pool.
 132  
      * <code>addObject</code> is useful for "pre-loading" a pool with idle objects
 133  
      * (Optional operation).
 134  
      *
 135  
      * @param key the key a new instance should be added to
 136  
      * @throws Exception when {@link KeyedPoolableObjectFactory#makeObject} fails.
 137  
      * @throws IllegalStateException after {@link #close} has been called on this pool.
 138  
      * @throws UnsupportedOperationException when this pool cannot add new idle objects.
 139  
      */
 140  
     void addObject(Object key) throws Exception, IllegalStateException, UnsupportedOperationException;
 141  
 
 142  
     /**
 143  
      * Returns the number of instances
 144  
      * corresponding to the given <code>key</code>
 145  
      * currently idle in this pool (optional operation).
 146  
      * Returns a negative value if this information is not available.
 147  
      *
 148  
      * @param key the key to query
 149  
      * @return the number of instances corresponding to the given <code>key</code> currently idle in this pool or a negative value if unsupported
 150  
      * @throws UnsupportedOperationException <strong>deprecated</strong>: when this implementation doesn't support the operation
 151  
      */
 152  
     int getNumIdle(Object key) throws UnsupportedOperationException;
 153  
 
 154  
     /**
 155  
      * Returns the number of instances
 156  
      * currently borrowed from but not yet returned
 157  
      * to the pool corresponding to the
 158  
      * given <code>key</code> (optional operation).
 159  
      * Returns a negative value if this information is not available.
 160  
      *
 161  
      * @param key the key to query
 162  
      * @return the number of instances corresponding to the given <code>key</code> currently borrowed in this pool or a negative value if unsupported
 163  
      * @throws UnsupportedOperationException <strong>deprecated</strong>: when this implementation doesn't support the operation
 164  
      */
 165  
     int getNumActive(Object key) throws UnsupportedOperationException;
 166  
 
 167  
     /**
 168  
      * Returns the total number of instances
 169  
      * currently idle in this pool (optional operation).
 170  
      * Returns a negative value if this information is not available.
 171  
      *
 172  
      * @return the total number of instances currently idle in this pool or a negative value if unsupported
 173  
      * @throws UnsupportedOperationException <strong>deprecated</strong>: when this implementation doesn't support the operation
 174  
      */
 175  
     int getNumIdle() throws UnsupportedOperationException;
 176  
 
 177  
     /**
 178  
      * Returns the total number of instances
 179  
      * current borrowed from this pool but not
 180  
      * yet returned (optional operation).
 181  
      * Returns a negative value if this information is not available.
 182  
      *
 183  
      * @return the total number of instances currently borrowed from this pool or a negative value if unsupported
 184  
      * @throws UnsupportedOperationException <strong>deprecated</strong>: when this implementation doesn't support the operation
 185  
      */
 186  
     int getNumActive() throws UnsupportedOperationException;
 187  
 
 188  
     /**
 189  
      * Clears the pool, removing all pooled instances (optional operation).
 190  
      * Throws {@link UnsupportedOperationException} if the pool cannot be cleared.
 191  
      *
 192  
      * @throws UnsupportedOperationException when this implementation doesn't support the operation
 193  
      */
 194  
     void clear() throws Exception, UnsupportedOperationException;
 195  
 
 196  
     /**
 197  
      * Clears the specified pool, removing all
 198  
      * pooled instances corresponding to
 199  
      * the given <code>key</code> (optional operation).
 200  
      * Throws {@link UnsupportedOperationException} if the pool cannot be cleared.
 201  
      *
 202  
      * @param key the key to clear
 203  
      * @throws UnsupportedOperationException when this implementation doesn't support the operation
 204  
      */
 205  
     void clear(Object key) throws Exception, UnsupportedOperationException;
 206  
 
 207  
     /**
 208  
      * Close this pool, and free any resources associated with it.
 209  
      * <p>
 210  
      * Calling {@link #addObject addObject} or {@link #borrowObject borrowObject} after invoking
 211  
      * this method on a pool will cause them to throw an {@link IllegalStateException}.
 212  
      * </p>
 213  
      *
 214  
      * @throws Exception
 215  
      */
 216  
     void close() throws Exception;
 217  
 
 218  
     /**
 219  
      * Sets the {@link KeyedPoolableObjectFactory factory} the pool uses
 220  
      * to create new instances (optional operation).
 221  
      * Trying to change the <code>factory</code> after a pool has been used will frequently
 222  
      * throw an {@link UnsupportedOperationException}. It is up to the pool
 223  
      * implementation to determine when it is acceptable to call this method.
 224  
      *
 225  
      * @param factory the {@link KeyedPoolableObjectFactory} used to create new instances.
 226  
      * @throws IllegalStateException when the factory cannot be set at this time
 227  
      * @throws UnsupportedOperationException when this implementation doesn't support the operation
 228  
      */
 229  
     void setFactory(KeyedPoolableObjectFactory factory) throws IllegalStateException, UnsupportedOperationException;
 230  
 }