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 module hunt.pool.ObjectPool; 18 19 import hunt.util.Common; 20 import hunt.Exceptions; 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 * @see PooledObjectFactory 55 * @see KeyedObjectPool 56 * @see BaseObjectPool 57 * 58 */ 59 interface ObjectPool(T) : Closeable { 60 61 /** 62 * Obtains an instance from this pool. 63 * <p> 64 * Instances returned from this method will have been either newly created 65 * with {@link PooledObjectFactory#makeObject} or will be a previously 66 * idle object and have been activated with 67 * {@link PooledObjectFactory#activateObject} and then validated with 68 * {@link PooledObjectFactory#validateObject}. 69 * </p> 70 * <p> 71 * By contract, clients <strong>must</strong> return the borrowed instance 72 * using {@link #returnObject}, {@link #invalidateObject}, or a related 73 * method 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 78 * implementations). 79 * </p> 80 * 81 * @return an instance from this pool. 82 * 83 * @throws IllegalStateException 84 * after {@link #close close} has been called on this pool. 85 * @throws Exception 86 * when {@link PooledObjectFactory#makeObject} throws an 87 * exception. 88 * @throws NoSuchElementException 89 * when the pool is exhausted and cannot or will not return 90 * another instance. 91 */ 92 T borrowObject(); 93 94 /** 95 * Returns an instance to the pool. By contract, <code>obj</code> 96 * <strong>must</strong> have been obtained using {@link #borrowObject()} or 97 * a related method as defined in an implementation or sub-interface. 98 * 99 * @param obj a {@link #borrowObject borrowed} instance to be returned. 100 * 101 * @throws IllegalStateException 102 * if an attempt is made to return an object to the pool that 103 * is in any state other than allocated (i.e. borrowed). 104 * Attempting to return an object more than once or attempting 105 * to return an object that was never borrowed from the pool 106 * will trigger this exception. 107 * 108 * @throws Exception if an instance cannot be returned to the pool 109 */ 110 void returnObject(T obj); 111 112 /** 113 * Invalidates an object from the pool. 114 * <p> 115 * By contract, <code>obj</code> <strong>must</strong> have been obtained 116 * using {@link #borrowObject} or a related method as defined in an 117 * implementation or sub-interface. 118 * </p> 119 * <p> 120 * This method should be used when an object that has been borrowed is 121 * determined (due to an exception or other problem) to be invalid. 122 * </p> 123 * 124 * @param obj a {@link #borrowObject borrowed} instance to be disposed. 125 * 126 * @throws Exception if the instance cannot be invalidated 127 */ 128 void invalidateObject(T obj); 129 130 /** 131 * Creates an object using the {@link PooledObjectFactory factory} or other 132 * implementation dependent mechanism, passivate it, and then place it in 133 * the idle object pool. <code>addObject</code> is useful for "pre-loading" 134 * a pool with idle objects. (Optional operation). 135 * 136 * @throws Exception 137 * when {@link PooledObjectFactory#makeObject} fails. 138 * @throws IllegalStateException 139 * after {@link #close} has been called on this pool. 140 * @throws UnsupportedOperationException 141 * when this pool cannot add new idle objects. 142 */ 143 void addObject(); 144 145 /** 146 * Returns the number of instances currently idle in this pool. This may be 147 * considered an approximation of the number of objects that can be 148 * {@link #borrowObject borrowed} without creating any new instances. 149 * Returns a negative value if this information is not available. 150 * @return the number of instances currently idle in this pool. 151 */ 152 int getNumIdle(); 153 154 /** 155 * Returns the number of instances currently borrowed from this pool. Returns 156 * a negative value if this information is not available. 157 * @return the number of instances currently borrowed from this pool. 158 */ 159 int getNumActive(); 160 161 /** 162 * Clears any objects sitting idle in the pool, releasing any associated 163 * resources (optional operation). Idle objects cleared must be 164 * {@link PooledObjectFactory#destroyObject(PooledObject)}. 165 * 166 * @throws UnsupportedOperationException 167 * if this implementation does not support the operation 168 * 169 * @throws Exception if the pool cannot be cleared 170 */ 171 void clear(); 172 173 /** 174 * Closes this pool, and free any resources associated with it. 175 * <p> 176 * Calling {@link #addObject} or {@link #borrowObject} after invoking this 177 * method on a pool will cause them to throw an {@link IllegalStateException}. 178 * </p> 179 * <p> 180 * Implementations should silently fail if not all resources can be freed. 181 * </p> 182 */ 183 void close(); 184 }