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 package org.apache.commons.pool2; 18 19 import java.io.Closeable; 20 import java.util.NoSuchElementException; 21 22 /** 23 * A pooling simple interface. 24 * <p> 25 * Example of use: 26 * </p> 27 * <pre style="border:solid thin; padding: 1ex;" 28 * > Object obj = <code style="color:#00C">null</code>; 29 * 30 * <code style="color:#00C">try</code> { 31 * obj = pool.borrowObject(); 32 * <code style="color:#00C">try</code> { 33 * <code style="color:#0C0">//...use the object...</code> 34 * } <code style="color:#00C">catch</code> (Exception e) { 35 * <code style="color:#0C0">// invalidate the object</code> 36 * pool.invalidateObject(obj); 37 * <code style="color:#0C0">// do not return the object to the pool twice</code> 38 * obj = <code style="color:#00C">null</code>; 39 * } <code style="color:#00C">finally</code> { 40 * <code style="color:#0C0">// make sure the object is returned to the pool</code> 41 * <code style="color:#00C">if</code> (<code style="color:#00C">null</code> != obj) { 42 * pool.returnObject(obj); 43 * } 44 * } 45 * } <code style="color:#00C">catch</code>(Exception e) { 46 * <code style="color:#0C0">// failed to borrow an object</code> 47 * }</pre> 48 * <p> 49 * See {@link BaseObjectPool} for a simple base implementation. 50 * </p> 51 * 52 * @param <T> Type of element pooled in this pool. 53 * 54 * 55 * @see PooledObjectFactory 56 * @see KeyedObjectPool 57 * @see BaseObjectPool 58 * 59 * @since 2.0 60 */ 61 public interface ObjectPool<T> extends Closeable { 62 63 /** 64 * Creates an object using the {@link PooledObjectFactory factory} or other 65 * implementation dependent mechanism, passivate it, and then place it in 66 * the idle object pool. {@code addObject} is useful for "pre-loading" 67 * a pool with idle objects. (Optional operation). 68 * 69 * @throws Exception 70 * when {@link PooledObjectFactory#makeObject} fails. 71 * @throws IllegalStateException 72 * after {@link #close} has been called on this pool. 73 * @throws UnsupportedOperationException 74 * when this pool cannot add new idle objects. 75 */ 76 void addObject() throws Exception; 77 78 /** 79 * Calls {@link ObjectPool#addObject()} {@code count} 80 * number of times. 81 * 82 * @param count 83 * the number of idle objects to add. 84 * @throws Exception See {@link ObjectPool#addObject()}. 85 * @since 2.8.0 86 */ 87 default void addObjects(final int count) throws Exception { 88 for (int i = 0; i < count; i++) { 89 addObject(); 90 } 91 } 92 93 /** 94 * Borrows an instance from this pool. 95 * <p> 96 * Instances returned from this method will have been either newly created 97 * with {@link PooledObjectFactory#makeObject} or will be a previously 98 * idle object and have been activated with 99 * {@link PooledObjectFactory#activateObject} and then validated with 100 * {@link PooledObjectFactory#validateObject}. 101 * </p> 102 * <p> 103 * By contract, clients <strong>must</strong> return the borrowed instance 104 * using {@link #returnObject}, {@link #invalidateObject}, or a related 105 * method as defined in an implementation or sub-interface. 106 * </p> 107 * <p> 108 * The behavior of this method when the pool has been exhausted 109 * is not strictly specified (although it may be specified by 110 * implementations). 111 * </p> 112 * 113 * @return an instance from this pool. 114 * 115 * @throws IllegalStateException 116 * after {@link #close close} has been called on this pool. 117 * @throws Exception 118 * when {@link PooledObjectFactory#makeObject} throws an 119 * exception. 120 * @throws NoSuchElementException 121 * when the pool is exhausted and cannot or will not return 122 * another instance. 123 */ 124 T borrowObject() throws Exception; 125 126 /** 127 * Clears any objects sitting idle in the pool, releasing any associated 128 * resources (optional operation). Idle objects cleared must be 129 * {@link PooledObjectFactory#destroyObject(PooledObject)}. 130 * 131 * @throws UnsupportedOperationException 132 * if this implementation does not support the operation 133 * 134 * @throws Exception if the pool cannot be cleared 135 */ 136 void clear() throws Exception; 137 138 /** 139 * Closes this pool, and free any resources associated with it. 140 * <p> 141 * Calling {@link #addObject} or {@link #borrowObject} after invoking this 142 * method on a pool will cause them to throw an {@link IllegalStateException}. 143 * </p> 144 * <p> 145 * Implementations should silently fail if not all resources can be freed. 146 * </p> 147 */ 148 @Override 149 void close(); 150 151 /** 152 * Gets the number of instances currently borrowed from this pool. Returns 153 * a negative value if this information is not available. 154 * @return the number of instances currently borrowed from this pool. 155 */ 156 int getNumActive(); 157 158 /** 159 * Gets the number of instances currently idle in this pool. This may be 160 * considered an approximation of the number of objects that can be 161 * {@link #borrowObject borrowed} without creating any new instances. 162 * Returns a negative value if this information is not available. 163 * @return the number of instances currently idle in this pool. 164 */ 165 int getNumIdle(); 166 167 /** 168 * Invalidates an object from the pool. 169 * <p> 170 * By contract, {@code obj} <strong>must</strong> have been obtained 171 * using {@link #borrowObject} or a related method as defined in an 172 * implementation or sub-interface. 173 * </p> 174 * <p> 175 * This method should be used when an object that has been borrowed is 176 * determined (due to an exception or other problem) to be invalid. 177 * </p> 178 * 179 * @param obj a {@link #borrowObject borrowed} instance to be disposed. 180 * 181 * @throws Exception if the instance cannot be invalidated 182 */ 183 void invalidateObject(T obj) throws Exception; 184 185 /** 186 * Invalidates an object from the pool, using the provided 187 * {@link DestroyMode} 188 * <p> 189 * By contract, {@code obj} <strong>must</strong> have been obtained 190 * using {@link #borrowObject} or a related method as defined in an 191 * implementation or sub-interface. 192 * </p> 193 * <p> 194 * This method should be used when an object that has been borrowed is 195 * determined (due to an exception or other problem) to be invalid. 196 * </p> 197 * 198 * @param obj a {@link #borrowObject borrowed} instance to be disposed. 199 * @param destroyMode destroy activation context provided to the factory 200 * @throws Exception if the instance cannot be invalidated 201 * @since 2.9.0 202 */ 203 default void invalidateObject(final T obj, final DestroyMode destroyMode) throws Exception { 204 invalidateObject(obj); 205 } 206 207 /** 208 * Returns an instance to the pool. By contract, {@code obj} 209 * <strong>must</strong> have been obtained using {@link #borrowObject()} or 210 * a related method as defined in an implementation or sub-interface. 211 * 212 * @param obj a {@link #borrowObject borrowed} instance to be returned. 213 * 214 * @throws IllegalStateException 215 * if an attempt is made to return an object to the pool that 216 * is in any state other than allocated (i.e. borrowed). 217 * Attempting to return an object more than once or attempting 218 * to return an object that was never borrowed from the pool 219 * will trigger this exception. 220 * 221 * @throws Exception if an instance cannot be returned to the pool 222 */ 223 void returnObject(T obj) throws Exception; 224 225 }