KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > objectweb > jonas > resource > pool > api > Pool


1 /**
2  * JOnAS: Java(TM) Open Application Server
3  * Copyright (C) 1999 Bull S.A.
4  * Contact: jonas-team@objectweb.org
5  *
6  * ObjectWeb Connector: an implementation of JCA Sun specification along
7  * with some extensions of this specification.
8  * Copyright (C) 2001-2002 France Telecom R&D - INRIA
9  *
10  * This library is free software; you can redistribute it and/or
11  * modify it under the terms of the GNU Lesser General Public
12  * License as published by the Free Software Foundation; either
13  * version 2 of the License, or (at your option) any later version.
14  *
15  * This library is distributed in the hope that it will be useful,
16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18  * Lesser General Public License for more details.
19  *
20  * You should have received a copy of the GNU Lesser General Public
21  * License along with this library; if not, write to the Free Software
22  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
23  *
24  * Release: 1.0
25  *
26  * Author: E. Hardesty
27  *
28  * Based on Pool api in ObjectWeb common
29  *
30  */

31
32 /**
33  * Package definition.
34  */

35 package org.objectweb.jonas.resource.pool.api;
36
37 /**
38  * Import clauses: one for each external Java definition used. Do not use
39  * clauses in the form "import package.*".
40  */

41
42
43 /**
44  * The interface <b>Pool</b> defines an object that pools resources of any
45  * kind. Resources must be requested (getResource) and released
46  * (releaseResource) on demand. A Pool object can be parameterized along
47  * different dimensions. All these dimensions are represented by accessor
48  * methods (getters and setters) assigned to each of them:
49  * <ul>
50  * <li>
51  * A <b>Timeout</b> can be assigned to a Pool. It is used when no more
52  * resources are available and when the Pool has reached its maximum size.
53  * This is the timeout to wait for a free resource until exiting with an
54  * exception. It defaults to 0, which means waiting forever until a
55  * resource is freed. Its value should be greater or equal to 0 ; negative
56  * values are ignored (setTimeOut(-1) => NOP).
57  * </li>
58  * <li>
59  * A <b>MinSize</b> can be assigned to a Pool. Its value should be greater or
60  * equal to 0, and smaller or equal to MaxSize. Values that do not match these
61  * conditions are ignored (e.g., setMinSize(-1) => NOP).
62  * This size means that there is always MinSize PoolResource allocated in this
63  * Pool. If PoolResource needs to be allocated when setting this size,
64  * "getPoolMatchFactory().createResource(null)" is called. Its default value
65  * is 0.
66  * </li>
67  * <li>
68  * A <b>MatchFactory</b> (i.e., a PoolMatchFactory object) must be assigned to
69  * a Pool. It defines the way new PoolResource are created and the way a
70  * PoolResource of a Pool matches some "hints" properties when requested. It is
71  * mandatory for the Pool to be fully functional.
72  * </li>
73  * <li>
74  * A <b>MaxSize</b> can be assigned to a Pool. Its value should be greater or
75  * equal to 0, and greater or equal to MinSize. Values that do not match these
76  * conditions are ignored (e.g., setMaxSize(-1) => NOP). Its default value
77  * is 0, thus it is mandatory to set this value for making the Poll functional.
78  * </li>
79  * </ul>
80  */

81 public interface Pool {
82     /**
83      * <b>adjust</b> checks the age of the entries and removes them if
84      * they are too old
85      *
86      * @throws Exception if an error occurs
87      */

88     void adjust() throws Exception JavaDoc;
89
90     /**
91      * <b>getMatchFactory</b> retrieves the PoolMatchFactory assigned to this
92      * Pool.
93      * @return The PoolMatchFactory currently assigned to this Pool.
94      */

95     PoolMatchFactory getMatchFactory();
96
97     /**
98      * <b>getMaxAge</b> gets the max age for a pool entry
99      *
100      * @return int max number of minutes to keep a connection
101      * in the pool.
102      */

103     int getMaxAge();
104
105     /**
106      * <b>getMaxOpentime</b> gets the max age for a pool entry
107      *
108      * @return int max number of minutes to keep a connection
109      * in the pool.
110      */

111     int getMaxOpentime();
112
113     /**
114      * <b>getMaxSize</b> retrieves the maximum size assigned to this Pool.
115      * @return The maximum size currently assigned to this Pool.
116      */

117     int getMaxSize();
118
119     /**
120      * <b>getMaxWaiters</b> gets the maximum number of waiters for a connection
121      * in this Pool.
122      *
123      * @param return int maximum number of waiters
124      */

125     int getMaxWaiters();
126
127     /**
128      * <b>getMaxWaitTime</b> gets the maximum number of seconds to wait for a
129      * connection in this Pool.
130      *
131      * @return int maximum number of seconds to wait
132      */

133     int getMaxWaitTime();
134
135     /**
136      * <b>getMinSize</b> retrieves the minimum size assigned to this Pool.
137      * @return The minimum size currently assigned to this Pool.
138      */

139     int getMinSize();
140
141     /**
142      * <b>getResource</b> is used to allocate a Object from the Pool.
143      * Some hints are passed in order to specialise the matching or creation
144      * of Object.
145      * @param hints Some properties to specialise the matching or the creation
146      * of Object.
147      * @return The Object allocated from the Pool.
148      * @throws Exception if an error occurs
149      */

150     Object JavaDoc getResource(Object JavaDoc hints) throws Exception JavaDoc;
151
152     /**
153      * <b>getSamplingPeriod</b> gets the number of seconds between statistics
154      * sampling for this Pool.
155      *
156      * @return int number of seconds between samplings
157      */

158     int getSamplingPeriod();
159
160     /**
161      * <b>getTimeout</b> retrieves the timeout assigned to this Pool.
162      * @return The timeout currently assigned to this Pool.
163      */

164     long getTimeout();
165
166     /**
167      * <b>getSize</b> retrieves the current size of this Pool.
168      * @return The current size of this Pool.
169      */

170     int getSize();
171
172     /**
173      * <b>releaseResource</b> releases a Object in order to allow the
174      * Pool to recycle this Object.
175      * @param resource The Object to be released.
176      * @param destroy boolean to remove the object from the pool and
177      * destroy it
178      * @param adjustment boolean to determine if a pool adjustment should be done
179      * @throws Exception if an error occurs
180      */

181     void releaseResource(Object JavaDoc resource, boolean destroy, boolean adjustment) throws Exception JavaDoc;
182
183     /**
184      * <b>sampling</b> updates the interval pool information
185      *
186      * @throws Exception if an error occurs
187      */

188     void sampling() throws Exception JavaDoc;
189
190     /**
191      * <b>setInitSize</b> creates initsize resoures to this Pool.
192      *
193      * @param initsize The init size to be created.
194      * @throws Exception if an error occurs
195      */

196     void setInitSize(int initsize) throws Exception JavaDoc;
197
198     /**
199      * <b>setMatchFactory</b> assigns a PoolMatchFactory to this Pool.
200      *
201      * @param pmf The PoolMatchFactory to be assigned.
202      */

203     void setMatchFactory(PoolMatchFactory pmf);
204
205     /**
206      * <b>setMaxAge</b> sets the max age for a pool entry
207      *
208      * @param maxAge int max number of minutes to keep a connection
209      * in the pool.
210      */

211     void setMaxAge(int maxAge);
212
213     /**
214      * <b>setMaxOpentime</b> sets the max age for an entry to be opened
215      *
216      * @param maxOpentime int max number of minutes to keep a connection
217      * opened.
218      */

219     void setMaxOpentime(int maxOpentime);
220
221     /**
222      * <b>setMaxSize</b> assigns a maximum size to this Pool.
223      *
224      * @param maxsize int maximum size to be assigned.
225      * @throws Exception if an error occurs
226      */

227     void setMaxSize(int maxsize) throws Exception JavaDoc;
228
229     /**
230      * <b>setMaxWaiters</b> sets the maximum number of waiters for a connection
231      * in this Pool.
232      *
233      * @param maxWaiters int maximum number of waiters
234      */

235     void setMaxWaiters(int maxWaiters);
236
237     /**
238      * <b>setMaxWaitTime</b> sets the maximum number of seconds to wait for a
239      * connection in this Pool.
240      *
241      * @param maxWaitTime int maximum number of seconds to wait
242      */

243     void setMaxWaitTime(int maxWaitTime);
244
245     /**
246      * <b>setMinSize</b> assigns a minimum size to this Pool.
247      *
248      * @param minsize int minimum size to be assigned.
249      * @throws Exception if an error occurs
250      */

251     void setMinSize(int minsize) throws Exception JavaDoc;
252
253     /**
254      * <b>setSamplingPeriod</b> sets the number of seconds between statistics
255      * sampling for this Pool.
256      *
257      * @param samplingPeriod int number of seconds between samplings
258      */

259     void setSamplingPeriod(int samplingPeriod);
260
261     /**
262      * <b>setTimeout</b> assigns a timeout to this Pool.
263      *
264      * @param crto long timeout to be assigned.
265      */

266     void setTimeout(long crto);
267
268     /**
269      * <b>startMonitor</b> starts the pool monitor for this Pool.
270      *
271      */

272     void startMonitor();
273
274     /**
275      * <b>validateMCs</b> validates ManagedConnections in Pool every 10 minutes
276      *
277      * @throws Exception if an error occurs
278      */

279     void validateMCs() throws Exception JavaDoc;
280     
281     /* Statistics area */
282     /**
283      * @return int number of busy connections
284      */

285     public int getCurrentBusy();
286
287     /**
288      * @return int number of opened connections
289      */

290     public int getCurrentOpened();
291     
292     /**
293      * @return maximum nb of busy connections in last sampling period
294      */

295     int getBusyMaxRecent();
296
297     /**
298      * @return minimum nb of busy connections in last sampling period
299      */

300     int getBusyMinRecent();
301
302     /**
303      * @return current number of connection waiters
304      */

305     int getCurrentWaiters();
306
307     /**
308      * @return int number of physical jdbc connection opened
309      */

310     int getOpenedCount();
311
312     /**
313      * @return int number of connection failures on open
314      */

315     int getConnectionFailures();
316
317     /**
318      * @return int number of connection leaks
319      */

320     int getConnectionLeaks();
321
322     /**
323      * @return int number of connection served
324      */

325     int getServedOpen();
326
327     /**
328      * @return int number of open calls that were rejected due to waiter overflow
329      */

330     int getRejectedFull();
331
332     /**
333      * @return int number of open calls that were rejected by timeout
334      */

335     int getRejectedTimeout();
336
337     /**
338      * @return int number of open calls that were rejected
339      */

340     int getRejectedOther();
341
342     /**
343      * @return int number of open calls that were rejected
344      */

345     int getRejectedOpen();
346
347     /**
348      * @return maximum nb of waiters since the datasource creation
349      */

350     int getWaitersHigh();
351
352     /**
353      * @return maximum nb of waiters in last sampling period
354      */

355     int getWaitersHighRecent();
356
357     /**
358      * @return total nb of waiters since the datasource creation
359      */

360     int getWaiterCount();
361
362     /**
363      * @return total waiting time since the datasource creation
364      */

365     long getWaitingTime();
366
367     /**
368      * @return max waiting time since the datasource creation
369      */

370     long getWaitingHigh();
371
372     /**
373      * @return max waiting time in last sampling period
374      */

375     long getWaitingHighRecent();
376
377 }
378
379
380
Popular Tags