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