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:#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(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(obj); | |
46 | * } | |
47 | * }</pre> | |
48 | * </p> | |
49 | * | |
50 | * <p>See {@link BaseObjectPool} for a simple base implementation.</p> | |
51 | * | |
52 | * @author Rodney Waldhoff | |
53 | * @author Sandy McArthur | |
54 | * @version $Revision: 778007 $ $Date: 2009-05-23 15:57:11 -0400 (Sat, 23 May 2009) $ | |
55 | * @see PoolableObjectFactory | |
56 | * @see ObjectPoolFactory | |
57 | * @see KeyedObjectPool | |
58 | * @see BaseObjectPool | |
59 | * @since Pool 1.0 | |
60 | */ | |
61 | public interface ObjectPool { | |
62 | /** | |
63 | * Obtains an instance from this pool. | |
64 | * <p> | |
65 | * Instances returned from this method will have been either newly created with | |
66 | * {@link PoolableObjectFactory#makeObject makeObject} or will be a previously idle object and | |
67 | * have been activated with {@link PoolableObjectFactory#activateObject activateObject} and | |
68 | * then validated with {@link PoolableObjectFactory#validateObject validateObject}. | |
69 | * </p> | |
70 | * <p> | |
71 | * By contract, clients <strong>must</strong> return the borrowed instance using | |
72 | * {@link #returnObject returnObject}, {@link #invalidateObject invalidateObject}, or a related method | |
73 | * as defined in an implementation or sub-interface. | |
74 | * </p> | |
75 | * <p> | |
76 | * The behaviour of this method when the pool has been exhausted | |
77 | * is not strictly specified (although it may be specified by implementations). | |
78 | * Older versions of this method would return <code>null</code> to indicate exhaustion, | |
79 | * newer versions are encouraged to throw a {@link NoSuchElementException}. | |
80 | * </p> | |
81 | * | |
82 | * @return an instance from this pool. | |
83 | * @throws IllegalStateException after {@link #close close} has been called on this pool. | |
84 | * @throws Exception when {@link PoolableObjectFactory#makeObject makeObject} throws an exception. | |
85 | * @throws NoSuchElementException when the pool is exhausted and cannot or will not return another instance. | |
86 | */ | |
87 | Object borrowObject() throws Exception, NoSuchElementException, IllegalStateException; | |
88 | ||
89 | /** | |
90 | * Return an instance to the pool. | |
91 | * By contract, <code>obj</code> <strong>must</strong> have been obtained | |
92 | * using {@link #borrowObject() borrowObject} | |
93 | * or a related method as defined in an implementation | |
94 | * or sub-interface. | |
95 | * | |
96 | * @param obj a {@link #borrowObject borrowed} instance to be returned. | |
97 | * @throws Exception | |
98 | */ | |
99 | void returnObject(Object obj) throws Exception; | |
100 | ||
101 | /** | |
102 | * Invalidates an object from the pool. | |
103 | * By contract, <code>obj</code> <strong>must</strong> have been obtained | |
104 | * using {@link #borrowObject borrowObject} | |
105 | * or a related method as defined in an implementation | |
106 | * or sub-interface. | |
107 | * <p> | |
108 | * This method should be used when an object that has been borrowed | |
109 | * is determined (due to an exception or other problem) to be invalid. | |
110 | * </p> | |
111 | * | |
112 | * @param obj a {@link #borrowObject borrowed} instance to be disposed. | |
113 | * @throws Exception | |
114 | */ | |
115 | void invalidateObject(Object obj) throws Exception; | |
116 | ||
117 | /** | |
118 | * Create an object using the {@link PoolableObjectFactory factory} or other | |
119 | * implementation dependent mechanism, passivate it, and then place it in the idle object pool. | |
120 | * <code>addObject</code> is useful for "pre-loading" a pool with idle objects. | |
121 | * (Optional operation). | |
122 | * | |
123 | * @throws Exception when {@link PoolableObjectFactory#makeObject} fails. | |
124 | * @throws IllegalStateException after {@link #close} has been called on this pool. | |
125 | * @throws UnsupportedOperationException when this pool cannot add new idle objects. | |
126 | */ | |
127 | void addObject() throws Exception, IllegalStateException, UnsupportedOperationException; | |
128 | ||
129 | /** | |
130 | * Return the number of instances | |
131 | * currently idle in this pool (optional operation). | |
132 | * This may be considered an approximation of the number | |
133 | * of objects that can be {@link #borrowObject borrowed} | |
134 | * without creating any new instances. | |
135 | * Returns a negative value if this information is not available. | |
136 | * | |
137 | * @return the number of instances currently idle in this pool or a negative value if unsupported | |
138 | * @throws UnsupportedOperationException <strong>deprecated</strong>: if this implementation does not support the operation | |
139 | */ | |
140 | int getNumIdle() throws UnsupportedOperationException; | |
141 | ||
142 | /** | |
143 | * Return the number of instances | |
144 | * currently borrowed from this pool | |
145 | * (optional operation). | |
146 | * Returns a negative value if this information is not available. | |
147 | * | |
148 | * @return the number of instances currently borrowed from this pool or a negative value if unsupported | |
149 | * @throws UnsupportedOperationException <strong>deprecated</strong>: if this implementation does not support the operation | |
150 | */ | |
151 | int getNumActive() throws UnsupportedOperationException; | |
152 | ||
153 | /** | |
154 | * Clears any objects sitting idle in the pool, releasing any | |
155 | * associated resources (optional operation). | |
156 | * Idle objects cleared must be {@link PoolableObjectFactory#destroyObject(Object) destroyed}. | |
157 | * | |
158 | * @throws UnsupportedOperationException if this implementation does not support the operation | |
159 | */ | |
160 | void clear() throws Exception, UnsupportedOperationException; | |
161 | ||
162 | /** | |
163 | * Close this pool, and free any resources associated with it. | |
164 | * <p> | |
165 | * Calling {@link #addObject} or {@link #borrowObject} after invoking | |
166 | * this method on a pool will cause them to throw an | |
167 | * {@link IllegalStateException}. | |
168 | * </p> | |
169 | * | |
170 | * @throws Exception <strong>deprecated</strong>: implementations should silently fail if not all resources can be freed. | |
171 | */ | |
172 | void close() throws Exception; | |
173 | ||
174 | /** | |
175 | * Sets the {@link PoolableObjectFactory factory} this pool uses | |
176 | * to create new instances (optional operation). Trying to change | |
177 | * the <code>factory</code> after a pool has been used will frequently | |
178 | * throw an {@link UnsupportedOperationException}. It is up to the pool | |
179 | * implementation to determine when it is acceptable to call this method. | |
180 | * | |
181 | * @param factory the {@link PoolableObjectFactory} used to create new instances. | |
182 | * @throws IllegalStateException when the factory cannot be set at this time | |
183 | * @throws UnsupportedOperationException if this implementation does not support the operation | |
184 | */ | |
185 | void setFactory(PoolableObjectFactory factory) throws IllegalStateException, UnsupportedOperationException; | |
186 | } |