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: 1533126 $ 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 Exception 099 */ 100 void returnObject(T obj) throws Exception; 101 102 /** 103 * Invalidates an object from the pool. 104 * <p> 105 * By contract, <code>obj</code> <strong>must</strong> have been obtained 106 * using {@link #borrowObject} or a related method as defined in an 107 * implementation or sub-interface. 108 * <p> 109 * This method should be used when an object that has been borrowed is 110 * determined (due to an exception or other problem) to be invalid. 111 * 112 * @param obj a {@link #borrowObject borrowed} instance to be disposed. 113 * 114 * @throws Exception 115 */ 116 void invalidateObject(T obj) throws Exception; 117 118 /** 119 * Create an object using the {@link PooledObjectFactory factory} or other 120 * implementation dependent mechanism, passivate it, and then place it in 121 * the idle object pool. <code>addObject</code> is useful for "pre-loading" 122 * a pool with idle objects. (Optional operation). 123 * 124 * @throws Exception 125 * when {@link PooledObjectFactory#makeObject} fails. 126 * @throws IllegalStateException 127 * after {@link #close} has been called on this pool. 128 * @throws UnsupportedOperationException 129 * when this pool cannot add new idle objects. 130 */ 131 void addObject() throws Exception, IllegalStateException, 132 UnsupportedOperationException; 133 134 /** 135 * Return the number of instances currently idle in this pool. This may be 136 * considered an approximation of the number of objects that can be 137 * {@link #borrowObject borrowed} without creating any new instances. 138 * Returns a negative value if this information is not available. 139 * @return the number of instances currently idle in this pool. 140 */ 141 int getNumIdle(); 142 143 /** 144 * Return the number of instances currently borrowed from this pool. Returns 145 * a negative value if this information is not available. 146 * @return the number of instances currently borrowed from this pool. 147 */ 148 int getNumActive(); 149 150 /** 151 * Clears any objects sitting idle in the pool, releasing any associated 152 * resources (optional operation). Idle objects cleared must be 153 * {@link PooledObjectFactory#destroyObject(PooledObject)}. 154 * 155 * @throws UnsupportedOperationException 156 * if this implementation does not support the operation 157 */ 158 void clear() throws Exception, UnsupportedOperationException; 159 160 /** 161 * Close this pool, and free any resources associated with it. 162 * <p> 163 * Calling {@link #addObject} or {@link #borrowObject} after invoking this 164 * method on a pool will cause them to throw an {@link IllegalStateException}. 165 * <p> 166 * Implementations should silently fail if not all resources can be freed. 167 */ 168 void close(); 169}