001/* 002 * Licensed to the Apache Software Foundation (ASF) under one or more 003 * contributor license agreements. See the NOTICE file distributed with 004 * this work for additional information regarding copyright ownership. 005 * The ASF licenses this file to You under the Apache License, Version 2.0 006 * (the "License"); you may not use this file except in compliance with 007 * the License. You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017package org.apache.commons.pool2; 018 019import java.util.NoSuchElementException; 020 021/** 022 * A pooling simple interface. 023 * <p> 024 * Example of use: 025 * <pre style="border:solid thin; padding: 1ex;" 026 * > Object obj = <code style="color:#00C">null</code>; 027 * 028 * <code style="color:#00C">try</code> { 029 * obj = pool.borrowObject(); 030 * <code style="color:#00C">try</code> { 031 * <code style="color:#0C0">//...use the object...</code> 032 * } <code style="color:#00C">catch</code>(Exception e) { 033 * <code style="color:#0C0">// invalidate the object</code> 034 * pool.invalidateObject(obj); 035 * <code style="color:#0C0">// do not return the object to the pool twice</code> 036 * obj = <code style="color:#00C">null</code>; 037 * } <code style="color:#00C">finally</code> { 038 * <code style="color:#0C0">// make sure the object is returned to the pool</code> 039 * <code style="color:#00C">if</code>(<code style="color:#00C">null</code> != obj) { 040 * pool.returnObject(obj); 041 * } 042 * } 043 * } <code style="color:#00C">catch</code>(Exception e) { 044 * <code style="color:#0C0">// failed to borrow an object</code> 045 * }</pre> 046 * <p> 047 * See {@link BaseObjectPool} for a simple base implementation. 048 * 049 * @param <T> Type of element pooled in this pool. 050 * 051 * @see PooledObjectFactory 052 * @see KeyedObjectPool 053 * @see BaseObjectPool 054 * 055 * @version $Revision: 1566605 $ 056 * 057 * @since 2.0 058 */ 059public interface ObjectPool<T> { 060 /** 061 * Obtains an instance from this pool. 062 * <p> 063 * Instances returned from this method will have been either newly created 064 * with {@link PooledObjectFactory#makeObject} or will be a previously 065 * idle object and have been activated with 066 * {@link PooledObjectFactory#activateObject} and then validated with 067 * {@link PooledObjectFactory#validateObject}. 068 * <p> 069 * By contract, clients <strong>must</strong> return the borrowed instance 070 * using {@link #returnObject}, {@link #invalidateObject}, or a related 071 * method as defined in an implementation or sub-interface. 072 * <p> 073 * The behaviour of this method when the pool has been exhausted 074 * is not strictly specified (although it may be specified by 075 * implementations). 076 * 077 * @return an instance from this pool. 078 * 079 * @throws IllegalStateException 080 * after {@link #close close} has been called on this pool. 081 * @throws Exception 082 * when {@link PooledObjectFactory#makeObject} throws an 083 * exception. 084 * @throws NoSuchElementException 085 * when the pool is exhausted and cannot or will not return 086 * another instance. 087 */ 088 T borrowObject() throws Exception, NoSuchElementException, 089 IllegalStateException; 090 091 /** 092 * Return an instance to the pool. By contract, <code>obj</code> 093 * <strong>must</strong> have been obtained using {@link #borrowObject()} or 094 * a related method as defined in an implementation or sub-interface. 095 * 096 * @param obj a {@link #borrowObject borrowed} instance to be returned. 097 * 098 * @throws IllegalStateException 099 * if an attempt is made to return an object to the pool that 100 * is in any state other than allocated (i.e. borrowed). 101 * Attempting to return an object more than once or attempting 102 * to return an object that was never borrowed from the pool 103 * will trigger this exception. 104 * 105 * @throws Exception if an instance cannot be returned to the pool 106 */ 107 void returnObject(T obj) throws Exception; 108 109 /** 110 * Invalidates an object from the pool. 111 * <p> 112 * By contract, <code>obj</code> <strong>must</strong> have been obtained 113 * using {@link #borrowObject} or a related method as defined in an 114 * implementation or sub-interface. 115 * <p> 116 * This method should be used when an object that has been borrowed is 117 * determined (due to an exception or other problem) to be invalid. 118 * 119 * @param obj a {@link #borrowObject borrowed} instance to be disposed. 120 * 121 * @throws Exception if the instance cannot be invalidated 122 */ 123 void invalidateObject(T obj) throws Exception; 124 125 /** 126 * Create an object using the {@link PooledObjectFactory factory} or other 127 * implementation dependent mechanism, passivate it, and then place it in 128 * the idle object pool. <code>addObject</code> is useful for "pre-loading" 129 * a pool with idle objects. (Optional operation). 130 * 131 * @throws Exception 132 * when {@link PooledObjectFactory#makeObject} fails. 133 * @throws IllegalStateException 134 * after {@link #close} has been called on this pool. 135 * @throws UnsupportedOperationException 136 * when this pool cannot add new idle objects. 137 */ 138 void addObject() throws Exception, IllegalStateException, 139 UnsupportedOperationException; 140 141 /** 142 * Return the number of instances currently idle in this pool. This may be 143 * considered an approximation of the number of objects that can be 144 * {@link #borrowObject borrowed} without creating any new instances. 145 * Returns a negative value if this information is not available. 146 * @return the number of instances currently idle in this pool. 147 */ 148 int getNumIdle(); 149 150 /** 151 * Return the number of instances currently borrowed from this pool. Returns 152 * a negative value if this information is not available. 153 * @return the number of instances currently borrowed from this pool. 154 */ 155 int getNumActive(); 156 157 /** 158 * Clears any objects sitting idle in the pool, releasing any associated 159 * resources (optional operation). Idle objects cleared must be 160 * {@link PooledObjectFactory#destroyObject(PooledObject)}. 161 * 162 * @throws UnsupportedOperationException 163 * if this implementation does not support the operation 164 * 165 * @throws Exception if the pool cannot be cleared 166 */ 167 void clear() throws Exception, UnsupportedOperationException; 168 169 /** 170 * Close this pool, and free any resources associated with it. 171 * <p> 172 * Calling {@link #addObject} or {@link #borrowObject} after invoking this 173 * method on a pool will cause them to throw an {@link IllegalStateException}. 174 * <p> 175 * Implementations should silently fail if not all resources can be freed. 176 */ 177 void close(); 178}