Classes in this File | Line Coverage | Branch Coverage | Complexity | ||||
KeyedObjectPool |
|
| 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 "keyed" pooling interface. | |
24 | * <p> | |
25 | * A keyed pool pools instances of multiple types. Each | |
26 | * type may be accessed using an arbitrary key. | |
27 | * </p> | |
28 | * <p> | |
29 | * Example of use: | |
30 | * <pre style="border:solid thin; padding: 1ex;" | |
31 | * > Object obj = <code style="color:#00C">null</code>; | |
32 | * Object key = <code style="color:#C00">"Key"</code>; | |
33 | * | |
34 | * <code style="color:#00C">try</code> { | |
35 | * obj = pool.borrowObject(key); | |
36 | * <code style="color:#0C0">//...use the object...</code> | |
37 | * } <code style="color:#00C">catch</code>(Exception e) { | |
38 | * <code style="color:#0C0">// invalidate the object</code> | |
39 | * pool.invalidateObject(key, obj); | |
40 | * <code style="color:#0C0">// do not return the object to the pool twice</code> | |
41 | * obj = <code style="color:#00C">null</code>; | |
42 | * } <code style="color:#00C">finally</code> { | |
43 | * <code style="color:#0C0">// make sure the object is returned to the pool</code> | |
44 | * <code style="color:#00C">if</code>(<code style="color:#00C">null</code> != obj) { | |
45 | * pool.returnObject(key, obj); | |
46 | * } | |
47 | * }</pre> | |
48 | * </p> | |
49 | * <p> | |
50 | * {@link KeyedObjectPool} implementations <i>may</i> choose to store at most | |
51 | * one instance per key value, or may choose to maintain a pool of instances | |
52 | * for each key (essentially creating a {@link java.util.Map Map} of | |
53 | * {@link ObjectPool pools}). | |
54 | * </p> | |
55 | * | |
56 | * <p>See {@link BaseKeyedObjectPool} for a simple base implementation.</p> | |
57 | * | |
58 | * @author Rodney Waldhoff | |
59 | * @author Sandy McArthur | |
60 | * @version $Revision: 778480 $ $Date: 2009-05-25 15:34:55 -0400 (Mon, 25 May 2009) $ | |
61 | * @see KeyedPoolableObjectFactory | |
62 | * @see KeyedObjectPoolFactory | |
63 | * @see ObjectPool | |
64 | * @see BaseKeyedObjectPool | |
65 | * @since Pool 1.0 | |
66 | */ | |
67 | public interface KeyedObjectPool { | |
68 | /** | |
69 | * Obtains an instance from this pool for the specified <code>key</code>. | |
70 | * <p> | |
71 | * Instances returned from this method will have been either newly created with | |
72 | * {@link KeyedPoolableObjectFactory#makeObject makeObject} or will be a previously idle object and | |
73 | * have been activated with {@link KeyedPoolableObjectFactory#activateObject activateObject} and | |
74 | * then validated with {@link KeyedPoolableObjectFactory#validateObject validateObject}. | |
75 | * <p> | |
76 | * By contract, clients <strong>must</strong> return the borrowed object using | |
77 | * {@link #returnObject returnObject}, {@link #invalidateObject invalidateObject}, or a related method | |
78 | * as defined in an implementation or sub-interface, | |
79 | * using a <code>key</code> that is {@link Object#equals equivalent} to the one used to | |
80 | * borrow the instance in the first place. | |
81 | * <p> | |
82 | * The behaviour of this method when the pool has been exhausted | |
83 | * is not strictly specified (although it may be specified by implementations). | |
84 | * Older versions of this method would return <code>null</code> to indicate exhaustion, | |
85 | * newer versions are encouraged to throw a {@link NoSuchElementException}. | |
86 | * | |
87 | * @param key the key used to obtain the object | |
88 | * @return an instance from this pool. | |
89 | * @throws IllegalStateException after {@link #close close} has been called on this pool | |
90 | * @throws Exception when {@link KeyedPoolableObjectFactory#makeObject makeObject} throws an exception | |
91 | * @throws NoSuchElementException when the pool is exhausted and cannot or will not return another instance | |
92 | */ | |
93 | Object borrowObject(Object key) throws Exception, NoSuchElementException, IllegalStateException; | |
94 | ||
95 | /** | |
96 | * Return an instance to the pool. | |
97 | * By contract, <code>obj</code> <strong>must</strong> have been obtained | |
98 | * using {@link #borrowObject borrowObject} | |
99 | * or a related method as defined in an implementation | |
100 | * or sub-interface | |
101 | * using a <code>key</code> that is equivalent to the one used to | |
102 | * borrow the instance in the first place. | |
103 | * | |
104 | * @param key the key used to obtain the object | |
105 | * @param obj a {@link #borrowObject borrowed} instance to be returned. | |
106 | * @throws Exception | |
107 | */ | |
108 | void returnObject(Object key, Object obj) throws Exception; | |
109 | ||
110 | /** | |
111 | * Invalidates an object from the pool | |
112 | * By contract, <code>obj</code> <strong>must</strong> have been obtained | |
113 | * using {@link #borrowObject borrowObject} | |
114 | * or a related method as defined in an implementation | |
115 | * or sub-interface | |
116 | * using a <code>key</code> that is equivalent to the one used to | |
117 | * borrow the <code>Object</code> in the first place. | |
118 | * <p> | |
119 | * This method should be used when an object that has been borrowed | |
120 | * is determined (due to an exception or other problem) to be invalid. | |
121 | * </p> | |
122 | * | |
123 | * @param key the key used to obtain the object | |
124 | * @param obj a {@link #borrowObject borrowed} instance to be returned. | |
125 | * @throws Exception | |
126 | */ | |
127 | void invalidateObject(Object key, Object obj) throws Exception; | |
128 | ||
129 | /** | |
130 | * Create an object using the {@link KeyedPoolableObjectFactory factory} or other | |
131 | * implementation dependent mechanism, passivate it, and then place it in the idle object pool. | |
132 | * <code>addObject</code> is useful for "pre-loading" a pool with idle objects | |
133 | * (Optional operation). | |
134 | * | |
135 | * @param key the key a new instance should be added to | |
136 | * @throws Exception when {@link KeyedPoolableObjectFactory#makeObject} fails. | |
137 | * @throws IllegalStateException after {@link #close} has been called on this pool. | |
138 | * @throws UnsupportedOperationException when this pool cannot add new idle objects. | |
139 | */ | |
140 | void addObject(Object key) throws Exception, IllegalStateException, UnsupportedOperationException; | |
141 | ||
142 | /** | |
143 | * Returns the number of instances | |
144 | * corresponding to the given <code>key</code> | |
145 | * currently idle in this pool (optional operation). | |
146 | * Returns a negative value if this information is not available. | |
147 | * | |
148 | * @param key the key to query | |
149 | * @return the number of instances corresponding to the given <code>key</code> currently idle in this pool or a negative value if unsupported | |
150 | * @throws UnsupportedOperationException <strong>deprecated</strong>: when this implementation doesn't support the operation | |
151 | */ | |
152 | int getNumIdle(Object key) throws UnsupportedOperationException; | |
153 | ||
154 | /** | |
155 | * Returns the number of instances | |
156 | * currently borrowed from but not yet returned | |
157 | * to the pool corresponding to the | |
158 | * given <code>key</code> (optional operation). | |
159 | * Returns a negative value if this information is not available. | |
160 | * | |
161 | * @param key the key to query | |
162 | * @return the number of instances corresponding to the given <code>key</code> currently borrowed in this pool or a negative value if unsupported | |
163 | * @throws UnsupportedOperationException <strong>deprecated</strong>: when this implementation doesn't support the operation | |
164 | */ | |
165 | int getNumActive(Object key) throws UnsupportedOperationException; | |
166 | ||
167 | /** | |
168 | * Returns the total number of instances | |
169 | * currently idle in this pool (optional operation). | |
170 | * Returns a negative value if this information is not available. | |
171 | * | |
172 | * @return the total number of instances currently idle in this pool or a negative value if unsupported | |
173 | * @throws UnsupportedOperationException <strong>deprecated</strong>: when this implementation doesn't support the operation | |
174 | */ | |
175 | int getNumIdle() throws UnsupportedOperationException; | |
176 | ||
177 | /** | |
178 | * Returns the total number of instances | |
179 | * current borrowed from this pool but not | |
180 | * yet returned (optional operation). | |
181 | * Returns a negative value if this information is not available. | |
182 | * | |
183 | * @return the total number of instances currently borrowed from this pool or a negative value if unsupported | |
184 | * @throws UnsupportedOperationException <strong>deprecated</strong>: when this implementation doesn't support the operation | |
185 | */ | |
186 | int getNumActive() throws UnsupportedOperationException; | |
187 | ||
188 | /** | |
189 | * Clears the pool, removing all pooled instances (optional operation). | |
190 | * Throws {@link UnsupportedOperationException} if the pool cannot be cleared. | |
191 | * | |
192 | * @throws UnsupportedOperationException when this implementation doesn't support the operation | |
193 | */ | |
194 | void clear() throws Exception, UnsupportedOperationException; | |
195 | ||
196 | /** | |
197 | * Clears the specified pool, removing all | |
198 | * pooled instances corresponding to | |
199 | * the given <code>key</code> (optional operation). | |
200 | * Throws {@link UnsupportedOperationException} if the pool cannot be cleared. | |
201 | * | |
202 | * @param key the key to clear | |
203 | * @throws UnsupportedOperationException when this implementation doesn't support the operation | |
204 | */ | |
205 | void clear(Object key) throws Exception, UnsupportedOperationException; | |
206 | ||
207 | /** | |
208 | * Close this pool, and free any resources associated with it. | |
209 | * <p> | |
210 | * Calling {@link #addObject addObject} or {@link #borrowObject borrowObject} after invoking | |
211 | * this method on a pool will cause them to throw an {@link IllegalStateException}. | |
212 | * </p> | |
213 | * | |
214 | * @throws Exception | |
215 | */ | |
216 | void close() throws Exception; | |
217 | ||
218 | /** | |
219 | * Sets the {@link KeyedPoolableObjectFactory factory} the pool uses | |
220 | * to create new instances (optional operation). | |
221 | * Trying to change the <code>factory</code> after a pool has been used will frequently | |
222 | * throw an {@link UnsupportedOperationException}. It is up to the pool | |
223 | * implementation to determine when it is acceptable to call this method. | |
224 | * | |
225 | * @param factory the {@link KeyedPoolableObjectFactory} used to create new instances. | |
226 | * @throws IllegalStateException when the factory cannot be set at this time | |
227 | * @throws UnsupportedOperationException when this implementation doesn't support the operation | |
228 | */ | |
229 | void setFactory(KeyedPoolableObjectFactory factory) throws IllegalStateException, UnsupportedOperationException; | |
230 | } |