Classes in this File | Line Coverage | Branch Coverage | Complexity | ||||
ObjectPool |
|
| 1.0;1 |
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 | ||
18 | package org.apache.commons.pool; | |
19 | ||
20 | import java.util.NoSuchElementException; | |
21 | ||
22 | /** | |
23 | * A pooling interface. | |
24 | * <p> | |
25 | * <code>ObjectPool</code> defines a trivially simple pooling interface. The only | |
26 | * required methods are {@link #borrowObject borrowObject}, {@link #returnObject returnObject} | |
27 | * and {@link #invalidateObject invalidateObject}. | |
28 | * </p> | |
29 | * <p> | |
30 | * Example of use: | |
31 | * <pre style="border:solid thin; padding: 1ex;" | |
32 | * > Object obj = <code style="color:#00C">null</code>; | |
33 | * | |
34 | * <code style="color:#00C">try</code> { | |
35 | * obj = pool.borrowObject(); | |
36 | * <code style="color:#00C">try</code> { | |
37 | * <code style="color:#0C0">//...use the object...</code> | |
38 | * } <code style="color:#00C">catch</code>(Exception e) { | |
39 | * <code style="color:#0C0">// invalidate the object</code> | |
40 | * pool.invalidateObject(obj); | |
41 | * <code style="color:#0C0">// do not return the object to the pool twice</code> | |
42 | * obj = <code style="color:#00C">null</code>; | |
43 | * } <code style="color:#00C">finally</code> { | |
44 | * <code style="color:#0C0">// make sure the object is returned to the pool</code> | |
45 | * <code style="color:#00C">if</code>(<code style="color:#00C">null</code> != obj) { | |
46 | * pool.returnObject(obj); | |
47 | * } | |
48 | * } | |
49 | * } <code style="color:#00C">catch</code>(Exception e) { | |
50 | * <code style="color:#0C0">// failed to borrow an object</code> | |
51 | * }</pre> | |
52 | * </p> | |
53 | * | |
54 | * <p>See {@link BaseObjectPool} for a simple base implementation.</p> | |
55 | * | |
56 | * @author Rodney Waldhoff | |
57 | * @author Sandy McArthur | |
58 | * @version $Revision: 962893 $ $Date: 2010-07-10 10:37:27 -0700 (Sat, 10 Jul 2010) $ | |
59 | * @see PoolableObjectFactory | |
60 | * @see ObjectPoolFactory | |
61 | * @see KeyedObjectPool | |
62 | * @see BaseObjectPool | |
63 | * @since Pool 1.0 | |
64 | */ | |
65 | public interface ObjectPool { | |
66 | /** | |
67 | * Obtains an instance from this pool. | |
68 | * <p> | |
69 | * Instances returned from this method will have been either newly created with | |
70 | * {@link PoolableObjectFactory#makeObject makeObject} or will be a previously idle object and | |
71 | * have been activated with {@link PoolableObjectFactory#activateObject activateObject} and | |
72 | * then validated with {@link PoolableObjectFactory#validateObject validateObject}. | |
73 | * </p> | |
74 | * <p> | |
75 | * By contract, clients <strong>must</strong> return the borrowed instance using | |
76 | * {@link #returnObject returnObject}, {@link #invalidateObject invalidateObject}, or a related method | |
77 | * as defined in an implementation or sub-interface. | |
78 | * </p> | |
79 | * <p> | |
80 | * The behaviour of this method when the pool has been exhausted | |
81 | * is not strictly specified (although it may be specified by implementations). | |
82 | * Older versions of this method would return <code>null</code> to indicate exhaustion, | |
83 | * newer versions are encouraged to throw a {@link NoSuchElementException}. | |
84 | * </p> | |
85 | * | |
86 | * @return an instance from this pool. | |
87 | * @throws IllegalStateException after {@link #close close} has been called on this pool. | |
88 | * @throws Exception when {@link PoolableObjectFactory#makeObject makeObject} throws an exception. | |
89 | * @throws NoSuchElementException when the pool is exhausted and cannot or will not return another instance. | |
90 | */ | |
91 | Object borrowObject() throws Exception, NoSuchElementException, IllegalStateException; | |
92 | ||
93 | /** | |
94 | * Return an instance to the pool. | |
95 | * By contract, <code>obj</code> <strong>must</strong> have been obtained | |
96 | * using {@link #borrowObject() borrowObject} | |
97 | * or a related method as defined in an implementation | |
98 | * or sub-interface. | |
99 | * | |
100 | * @param obj a {@link #borrowObject borrowed} instance to be returned. | |
101 | * @throws Exception | |
102 | */ | |
103 | void returnObject(Object obj) throws Exception; | |
104 | ||
105 | /** | |
106 | * <p>Invalidates an object from the pool.</p> | |
107 | * | |
108 | * <p>By contract, <code>obj</code> <strong>must</strong> have been obtained | |
109 | * using {@link #borrowObject borrowObject} or a related method as defined in | |
110 | * an implementation or sub-interface.</p> | |
111 | * | |
112 | * <p>This method should be used when an object that has been borrowed | |
113 | * is determined (due to an exception or other problem) to be invalid.</p> | |
114 | * | |
115 | * @param obj a {@link #borrowObject borrowed} instance to be disposed. | |
116 | * @throws Exception | |
117 | */ | |
118 | void invalidateObject(Object obj) throws Exception; | |
119 | ||
120 | /** | |
121 | * Create an object using the {@link PoolableObjectFactory factory} or other | |
122 | * implementation dependent mechanism, passivate it, and then place it in the idle object pool. | |
123 | * <code>addObject</code> is useful for "pre-loading" a pool with idle objects. | |
124 | * (Optional operation). | |
125 | * | |
126 | * @throws Exception when {@link PoolableObjectFactory#makeObject} fails. | |
127 | * @throws IllegalStateException after {@link #close} has been called on this pool. | |
128 | * @throws UnsupportedOperationException when this pool cannot add new idle objects. | |
129 | */ | |
130 | void addObject() throws Exception, IllegalStateException, UnsupportedOperationException; | |
131 | ||
132 | /** | |
133 | * Return the number of instances | |
134 | * currently idle in this pool (optional operation). | |
135 | * This may be considered an approximation of the number | |
136 | * of objects that can be {@link #borrowObject borrowed} | |
137 | * without creating any new instances. | |
138 | * Returns a negative value if this information is not available. | |
139 | * | |
140 | * @return the number of instances currently idle in this pool or a negative value if unsupported | |
141 | * @throws UnsupportedOperationException <strong>deprecated</strong>: if this implementation does not support the operation | |
142 | */ | |
143 | int getNumIdle() throws UnsupportedOperationException; | |
144 | ||
145 | /** | |
146 | * Return the number of instances | |
147 | * currently borrowed from this pool | |
148 | * (optional operation). | |
149 | * Returns a negative value if this information is not available. | |
150 | * | |
151 | * @return the number of instances currently borrowed from this pool or a negative value if unsupported | |
152 | * @throws UnsupportedOperationException <strong>deprecated</strong>: if this implementation does not support the operation | |
153 | */ | |
154 | int getNumActive() throws UnsupportedOperationException; | |
155 | ||
156 | /** | |
157 | * Clears any objects sitting idle in the pool, releasing any | |
158 | * associated resources (optional operation). | |
159 | * Idle objects cleared must be {@link PoolableObjectFactory#destroyObject(Object) destroyed}. | |
160 | * | |
161 | * @throws UnsupportedOperationException if this implementation does not support the operation | |
162 | */ | |
163 | void clear() throws Exception, UnsupportedOperationException; | |
164 | ||
165 | /** | |
166 | * Close this pool, and free any resources associated with it. | |
167 | * <p> | |
168 | * Calling {@link #addObject} or {@link #borrowObject} after invoking | |
169 | * this method on a pool will cause them to throw an | |
170 | * {@link IllegalStateException}. | |
171 | * </p> | |
172 | * | |
173 | * @throws Exception <strong>deprecated</strong>: implementations should silently fail if not all resources can be freed. | |
174 | */ | |
175 | void close() throws Exception; | |
176 | ||
177 | /** | |
178 | * Sets the {@link PoolableObjectFactory factory} this pool uses | |
179 | * to create new instances (optional operation). Trying to change | |
180 | * the <code>factory</code> after a pool has been used will frequently | |
181 | * throw an {@link UnsupportedOperationException}. It is up to the pool | |
182 | * implementation to determine when it is acceptable to call this method. | |
183 | * | |
184 | * @param factory the {@link PoolableObjectFactory} used to create new instances. | |
185 | * @throws IllegalStateException when the factory cannot be set at this time | |
186 | * @throws UnsupportedOperationException if this implementation does not support the operation | |
187 | * @deprecated to be removed in pool 2.0 | |
188 | */ | |
189 | void setFactory(PoolableObjectFactory factory) throws IllegalStateException, UnsupportedOperationException; | |
190 | } |