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 pooling interface.
21 * <p>
22 * <code>ObjectPool</code> defines a trivially simple pooling interface. The only
23 * required methods are {@link #borrowObject borrowObject} and {@link #returnObject returnObject}.
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 *
29 * <font color="#0000CC">try</font> {
30 * obj = pool.borrowObject();
31 * <font color="#00CC00">//...use the object...</font>
32 * } <font color="#0000CC">catch</font>(Exception e) {
33 * <font color="#00CC00">//...handle any exceptions...</font>
34 * } <font color="#0000CC">finally</font> {
35 * <font color="#00CC00">// make sure the object is returned to the pool</font>
36 * <font color="#0000CC">if</font>(<font color="#0000CC">null</font> != obj) {
37 * pool.returnObject(obj);
38 * }
39 * }</pre></td></tr></table>
40 * See {@link org.apache.commons.pool.BaseObjectPool BaseObjectPool} for a simple base implementation.
41 *
42 * @author Rodney Waldhoff
43 * @version $Revision: 155430 $ $Date: 2005-02-26 08:13:28 -0500 (Sat, 26 Feb 2005) $
44 *
45 */
46 public interface ObjectPool {
47 /***
48 * Obtain an instance from my pool.
49 * By contract, clients MUST return
50 * the borrowed instance using
51 * {@link #returnObject(java.lang.Object) returnObject}
52 * or a related method as defined in an implementation
53 * or sub-interface.
54 * <p>
55 * The behaviour of this method when the pool has been exhausted
56 * is not specified (although it may be specified by implementations).
57 *
58 * @return an instance from my pool.
59 */
60 Object borrowObject() throws Exception;
61
62 /***
63 * Return an instance to my pool.
64 * By contract, <i>obj</i> MUST have been obtained
65 * using {@link #borrowObject() borrowObject}
66 * or a related method as defined in an implementation
67 * or sub-interface.
68 *
69 * @param obj a {@link #borrowObject borrowed} instance to be returned.
70 */
71 void returnObject(Object obj) throws Exception;
72
73 /***
74 * Invalidates an object from the pool
75 * By contract, <i>obj</i> MUST have been obtained
76 * using {@link #borrowObject() borrowObject}
77 * or a related method as defined in an implementation
78 * or sub-interface.
79 * <p>
80 * This method should be used when an object that has been borrowed
81 * is determined (due to an exception or other problem) to be invalid.
82 * If the connection should be validated before or after borrowing,
83 * then the {@link PoolableObjectFactory#validateObject} method should be
84 * used instead.
85 *
86 * @param obj a {@link #borrowObject borrowed} instance to be returned.
87 */
88 void invalidateObject(Object obj) throws Exception;
89
90 /***
91 * Create an object using my {@link #setFactory factory} or other
92 * implementation dependent mechanism, and place it into the pool.
93 * addObject() is useful for "pre-loading" a pool with idle objects.
94 * (Optional operation).
95 */
96 void addObject() throws Exception;
97
98 /***
99 * Return the number of instances
100 * currently idle in my pool (optional operation).
101 * This may be considered an approximation of the number
102 * of objects that can be {@link #borrowObject borrowed}
103 * without creating any new instances.
104 *
105 * @return the number of instances currently idle in my pool
106 * @throws UnsupportedOperationException if this implementation does not support the operation
107 */
108 int getNumIdle() throws UnsupportedOperationException;
109
110 /***
111 * Return the number of instances
112 * currently borrowed from my pool
113 * (optional operation).
114 *
115 * @return the number of instances currently borrowed in my pool
116 * @throws UnsupportedOperationException if this implementation does not support the operation
117 */
118 int getNumActive() throws UnsupportedOperationException;
119
120 /***
121 * Clears any objects sitting idle in the pool, releasing any
122 * associated resources (optional operation).
123 *
124 * @throws UnsupportedOperationException if this implementation does not support the operation
125 */
126 void clear() throws Exception, UnsupportedOperationException;
127
128 /***
129 * Close this pool, and free any resources associated with it.
130 */
131 void close() throws Exception;
132
133 /***
134 * Sets the {@link PoolableObjectFactory factory} I use
135 * to create new instances (optional operation).
136 * @param factory the {@link PoolableObjectFactory} I use to create new instances.
137 *
138 * @throws IllegalStateException when the factory cannot be set at this time
139 * @throws UnsupportedOperationException if this implementation does not support the operation
140 */
141 void setFactory(PoolableObjectFactory factory) throws IllegalStateException, UnsupportedOperationException;
142 }