1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17 package org.apache.commons.pool;
18
19 /***
20 * A "keyed" pooling interface.
21 * <p>
22 * A keyed pool pools instances of multiple types. Each
23 * type may be accessed using an arbitrary key.
24 * <p>
25 * Example of use:
26 * <table border="1" cellspacing="0" cellpadding="3" align="center" bgcolor="#FFFFFF"><tr><td><pre>
27 * Object obj = <font color="#0000CC">null</font>;
28 * Object key = <font color="#CC0000">"Key"</font>;
29 *
30 * <font color="#0000CC">try</font> {
31 * obj = pool.borrowObject(key);
32 * <font color="#00CC00">//...use the object...</font>
33 * } <font color="#0000CC">catch</font>(Exception e) {
34 * <font color="#00CC00">//...handle any exceptions...</font>
35 * } <font color="#0000CC">finally</font> {
36 * <font color="#00CC00">// make sure the object is returned to the pool</font>
37 * <font color="#0000CC">if</font>(<font color="#0000CC">null</font> != obj) {
38 * pool.returnObject(key,obj);
39 * }
40 * }</pre></td></tr></table>
41 *
42 * <p>
43 * {@link KeyedObjectPool} implementations <i>may</i> choose to store at most
44 * one instance per key value, or may choose to maintain a pool of instances
45 * for each key (essentially creating a {@link java.util.Map Map} of
46 * {@link ObjectPool pools}).
47 * </p>
48 *
49 * @see KeyedPoolableObjectFactory
50 * @see KeyedObjectPoolFactory
51 * @see ObjectPool
52 *
53 * @author Rodney Waldhoff
54 * @version $Revision: 155430 $ $Date: 2005-02-26 08:13:28 -0500 (Sat, 26 Feb 2005) $
55 */
56 public interface KeyedObjectPool {
57 /***
58 * Obtain an instance from my pool
59 * for the specified <i>key</i>.
60 * By contract, clients MUST return
61 * the borrowed object using
62 * {@link #returnObject(java.lang.Object,java.lang.Object) <tt>returnObject</tt>},
63 * or a related method as defined in an implementation
64 * or sub-interface,
65 * using a <i>key</i> that is equivalent to the one used to
66 * borrow the instance in the first place.
67 *
68 * @param key the key used to obtain the object
69 * @return an instance from my pool.
70 */
71 Object borrowObject(Object key) throws Exception;
72
73 /***
74 * Return an instance to my pool.
75 * By contract, <i>obj</i> MUST have been obtained
76 * using {@link #borrowObject(java.lang.Object) <tt>borrowObject</tt>}
77 * or a related method as defined in an implementation
78 * or sub-interface
79 * using a <i>key</i> that is equivalent to the one used to
80 * borrow the <tt>Object</tt> in the first place.
81 *
82 * @param key the key used to obtain the object
83 * @param obj a {@link #borrowObject(java.lang.Object) borrowed} instance to be returned.
84 */
85 void returnObject(Object key, Object obj) throws Exception;
86
87 /***
88 * Invalidates an object from the pool
89 * By contract, <i>obj</i> MUST have been obtained
90 * using {@link #borrowObject borrowObject}
91 * or a related method as defined in an implementation
92 * or sub-interface
93 * using a <i>key</i> that is equivalent to the one used to
94 * borrow the <tt>Object</tt> in the first place.
95 * <p>
96 * This method should be used when an object that has been borrowed
97 * is determined (due to an exception or other problem) to be invalid.
98 * If the connection should be validated before or after borrowing,
99 * then the {@link PoolableObjectFactory#validateObject} method should be
100 * used instead.
101 *
102 * @param obj a {@link #borrowObject borrowed} instance to be returned.
103 */
104 void invalidateObject(Object key, Object obj) throws Exception;
105
106 /***
107 * Create an object using my {@link #setFactory factory} or other
108 * implementation dependent mechanism, and place it into the pool.
109 * addObject() is useful for "pre-loading" a pool with idle objects.
110 * (Optional operation).
111 */
112 void addObject(Object key) throws Exception;
113
114 /***
115 * Returns the number of instances
116 * corresponding to the given <i>key</i>
117 * currently idle in my pool (optional operation).
118 * Throws {@link UnsupportedOperationException}
119 * if this information is not available.
120 *
121 * @param key the key
122 * @return the number of instances corresponding to the given <i>key</i> currently idle in my pool
123 * @throws UnsupportedOperationException when this implementation doesn't support the operation
124 */
125 int getNumIdle(Object key) throws UnsupportedOperationException;
126
127 /***
128 * Returns the number of instances
129 * currently borrowed from but not yet returned
130 * to my pool corresponding to the
131 * given <i>key</i> (optional operation).
132 * Throws {@link UnsupportedOperationException}
133 * if this information is not available.
134 *
135 * @param key the key
136 * @return the number of instances corresponding to the given <i>key</i> currently borrowed in my pool
137 * @throws UnsupportedOperationException when this implementation doesn't support the operation
138 */
139 int getNumActive(Object key) throws UnsupportedOperationException;
140
141 /***
142 * Returns the total number of instances
143 * currently idle in my pool (optional operation).
144 * Throws {@link UnsupportedOperationException}
145 * if this information is not available.
146 *
147 * @return the total number of instances currently idle in my pool
148 * @throws UnsupportedOperationException when this implementation doesn't support the operation
149 */
150 int getNumIdle() throws UnsupportedOperationException;
151
152 /***
153 * Returns the total number of instances
154 * current borrowed from my pool but not
155 * yet returned (optional operation).
156 * Throws {@link UnsupportedOperationException}
157 * if this information is not available.
158 *
159 * @return the total number of instances currently borrowed from my pool
160 * @throws UnsupportedOperationException when this implementation doesn't support the operation
161 */
162 int getNumActive() throws UnsupportedOperationException;
163
164 /***
165 * Clears my pool, removing all pooled instances
166 * (optional operation).
167 * Throws {@link UnsupportedOperationException}
168 * if the pool cannot be cleared.
169 * @throws UnsupportedOperationException when this implementation doesn't support the operation
170 */
171 void clear() throws Exception, UnsupportedOperationException;
172
173 /***
174 * Clears the specified pool, removing all
175 * pooled instances corresponding to
176 * the given <i>key</i> (optional operation).
177 * Throws {@link UnsupportedOperationException}
178 * if the pool cannot be cleared.
179 * @param key the key to clear
180 * @throws UnsupportedOperationException when this implementation doesn't support the operation
181 */
182 void clear(Object key) throws Exception, UnsupportedOperationException;
183
184 /***
185 * Close this pool, and free any resources associated with it.
186 */
187 void close() throws Exception;
188
189 /***
190 * Sets the {@link KeyedPoolableObjectFactory factory} I use
191 * to create new instances (optional operation).
192 * @param factory the {@link KeyedPoolableObjectFactory} I use to create new instances.
193 * @throws IllegalStateException when the factory cannot be set at this time
194 * @throws UnsupportedOperationException when this implementation doesn't support the operation
195 */
196 void setFactory(KeyedPoolableObjectFactory factory) throws IllegalStateException, UnsupportedOperationException;
197 }