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