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 }