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  ;
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   getResource(Object   hints) throws Exception  ;
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   resource, boolean destroy, boolean adjustment) throws Exception  ;
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  ;
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  ;
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  ;
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  ;
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  ;
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
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags