Coverage Report - org.apache.commons.pool.ObjectPool
 
Classes in this File Line Coverage Branch Coverage Complexity
ObjectPool
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 pooling interface.
 24  
  * <p>
 25  
  * <code>ObjectPool</code> defines a trivially simple pooling interface. The only
 26  
  * required methods are {@link #borrowObject borrowObject}, {@link #returnObject returnObject}
 27  
  * and {@link #invalidateObject invalidateObject}.
 28  
  * </p>
 29  
  * <p>
 30  
  * Example of use:
 31  
  * <pre style="border:solid thin; padding: 1ex;"
 32  
  * > Object obj = <code style="color:#00C">null</code>;
 33  
  *
 34  
  * <code style="color:#00C">try</code> {
 35  
  *     obj = pool.borrowObject();
 36  
  *     <code style="color:#00C">try</code> {
 37  
  *         <code style="color:#0C0">//...use the object...</code>
 38  
  *     } <code style="color:#00C">catch</code>(Exception e) {
 39  
  *         <code style="color:#0C0">// invalidate the object</code>
 40  
  *         pool.invalidateObject(obj);
 41  
  *         <code style="color:#0C0">// do not return the object to the pool twice</code>
 42  
  *         obj = <code style="color:#00C">null</code>;
 43  
  *     } <code style="color:#00C">finally</code> {
 44  
  *         <code style="color:#0C0">// make sure the object is returned to the pool</code>
 45  
  *         <code style="color:#00C">if</code>(<code style="color:#00C">null</code> != obj) {
 46  
  *             pool.returnObject(obj);
 47  
  *        }
 48  
  *     }
 49  
  * } <code style="color:#00C">catch</code>(Exception e) {
 50  
  *       <code style="color:#0C0">// failed to borrow an object</code>
 51  
  * }</pre>
 52  
  * </p>
 53  
  *
 54  
  * <p>See {@link BaseObjectPool} for a simple base implementation.</p>
 55  
  *
 56  
  * @author Rodney Waldhoff
 57  
  * @author Sandy McArthur
 58  
  * @version $Revision: 962893 $ $Date: 2010-07-10 10:37:27 -0700 (Sat, 10 Jul 2010) $
 59  
  * @see PoolableObjectFactory
 60  
  * @see ObjectPoolFactory
 61  
  * @see KeyedObjectPool
 62  
  * @see BaseObjectPool
 63  
  * @since Pool 1.0
 64  
  */
 65  
 public interface ObjectPool {
 66  
     /**
 67  
      * Obtains an instance from this pool.
 68  
      * <p>
 69  
      * Instances returned from this method will have been either newly created with
 70  
      * {@link PoolableObjectFactory#makeObject makeObject} or will be a previously idle object and
 71  
      * have been activated with {@link PoolableObjectFactory#activateObject activateObject} and
 72  
      * then validated with {@link PoolableObjectFactory#validateObject validateObject}.
 73  
      * </p>
 74  
      * <p>
 75  
      * By contract, clients <strong>must</strong> return the borrowed instance using
 76  
      * {@link #returnObject returnObject}, {@link #invalidateObject invalidateObject}, or a related method
 77  
      * as defined in an implementation or sub-interface.
 78  
      * </p>
 79  
      * <p>
 80  
      * The behaviour of this method when the pool has been exhausted
 81  
      * is not strictly specified (although it may be specified by implementations).
 82  
      * Older versions of this method would return <code>null</code> to indicate exhaustion,
 83  
      * newer versions are encouraged to throw a {@link NoSuchElementException}.
 84  
      * </p>
 85  
      *
 86  
      * @return an instance from this pool.
 87  
      * @throws IllegalStateException after {@link #close close} has been called on this pool.
 88  
      * @throws Exception when {@link PoolableObjectFactory#makeObject makeObject} throws an exception.
 89  
      * @throws NoSuchElementException when the pool is exhausted and cannot or will not return another instance.
 90  
      */
 91  
     Object borrowObject() throws Exception, NoSuchElementException, IllegalStateException;
 92  
 
 93  
     /**
 94  
      * Return an instance to the pool.
 95  
      * By contract, <code>obj</code> <strong>must</strong> have been obtained
 96  
      * using {@link #borrowObject() borrowObject}
 97  
      * or a related method as defined in an implementation
 98  
      * or sub-interface.
 99  
      *
 100  
      * @param obj a {@link #borrowObject borrowed} instance to be returned.
 101  
      * @throws Exception 
 102  
      */
 103  
     void returnObject(Object obj) throws Exception;
 104  
 
 105  
     /**
 106  
      * <p>Invalidates an object from the pool.</p>
 107  
      * 
 108  
      * <p>By contract, <code>obj</code> <strong>must</strong> have been obtained
 109  
      * using {@link #borrowObject borrowObject} or a related method as defined in
 110  
      * an implementation or sub-interface.</p>
 111  
      *
 112  
      * <p>This method should be used when an object that has been borrowed
 113  
      * is determined (due to an exception or other problem) to be invalid.</p>
 114  
      *
 115  
      * @param obj a {@link #borrowObject borrowed} instance to be disposed.
 116  
      * @throws Exception
 117  
      */
 118  
     void invalidateObject(Object obj) throws Exception;
 119  
 
 120  
     /**
 121  
      * Create an object using the {@link PoolableObjectFactory factory} or other
 122  
      * implementation dependent mechanism, passivate it, and then place it in the idle object pool.
 123  
      * <code>addObject</code> is useful for "pre-loading" a pool with idle objects.
 124  
      * (Optional operation).
 125  
      *
 126  
      * @throws Exception when {@link PoolableObjectFactory#makeObject} fails.
 127  
      * @throws IllegalStateException after {@link #close} has been called on this pool.
 128  
      * @throws UnsupportedOperationException when this pool cannot add new idle objects.
 129  
      */
 130  
     void addObject() throws Exception, IllegalStateException, UnsupportedOperationException;
 131  
 
 132  
     /**
 133  
      * Return the number of instances
 134  
      * currently idle in this pool (optional operation).
 135  
      * This may be considered an approximation of the number
 136  
      * of objects that can be {@link #borrowObject borrowed}
 137  
      * without creating any new instances.
 138  
      * Returns a negative value if this information is not available.
 139  
      *
 140  
      * @return the number of instances currently idle in this pool or a negative value if unsupported
 141  
      * @throws UnsupportedOperationException <strong>deprecated</strong>: if this implementation does not support the operation
 142  
      */
 143  
     int getNumIdle() throws UnsupportedOperationException;
 144  
 
 145  
     /**
 146  
      * Return the number of instances
 147  
      * currently borrowed from this pool
 148  
      * (optional operation).
 149  
      * Returns a negative value if this information is not available.
 150  
      *
 151  
      * @return the number of instances currently borrowed from this pool or a negative value if unsupported
 152  
      * @throws UnsupportedOperationException <strong>deprecated</strong>: if this implementation does not support the operation
 153  
      */
 154  
     int getNumActive() throws UnsupportedOperationException;
 155  
 
 156  
     /**
 157  
      * Clears any objects sitting idle in the pool, releasing any
 158  
      * associated resources (optional operation).
 159  
      * Idle objects cleared must be {@link PoolableObjectFactory#destroyObject(Object) destroyed}.
 160  
      *
 161  
      * @throws UnsupportedOperationException if this implementation does not support the operation
 162  
      */
 163  
     void clear() throws Exception, UnsupportedOperationException;
 164  
 
 165  
     /**
 166  
      * Close this pool, and free any resources associated with it.
 167  
      * <p>
 168  
      * Calling {@link #addObject} or {@link #borrowObject} after invoking
 169  
      * this method on a pool will cause them to throw an
 170  
      * {@link IllegalStateException}.
 171  
      * </p>
 172  
      *
 173  
      * @throws Exception <strong>deprecated</strong>: implementations should silently fail if not all resources can be freed.
 174  
      */
 175  
     void close() throws Exception;
 176  
 
 177  
     /**
 178  
      * Sets the {@link PoolableObjectFactory factory} this pool uses
 179  
      * to create new instances (optional operation). Trying to change
 180  
      * the <code>factory</code> after a pool has been used will frequently
 181  
      * throw an {@link UnsupportedOperationException}. It is up to the pool
 182  
      * implementation to determine when it is acceptable to call this method.
 183  
      *
 184  
      * @param factory the {@link PoolableObjectFactory} used to create new instances.
 185  
      * @throws IllegalStateException when the factory cannot be set at this time
 186  
      * @throws UnsupportedOperationException if this implementation does not support the operation
 187  
      * @deprecated to be removed in pool 2.0
 188  
      */
 189  
     void setFactory(PoolableObjectFactory factory) throws IllegalStateException, UnsupportedOperationException;
 190  
 }