001: /**
002: * JOnAS: Java(TM) Open Application Server
003: * Copyright (C) 1999 Bull S.A.
004: * Contact: jonas-team@objectweb.org
005: *
006: * ObjectWeb Connector: an implementation of JCA Sun specification along
007: * with some extensions of this specification.
008: * Copyright (C) 2001-2002 France Telecom R&D - INRIA
009: *
010: * This library is free software; you can redistribute it and/or
011: * modify it under the terms of the GNU Lesser General Public
012: * License as published by the Free Software Foundation; either
013: * version 2 of the License, or (at your option) any later version.
014: *
015: * This library is distributed in the hope that it will be useful,
016: * but WITHOUT ANY WARRANTY; without even the implied warranty of
017: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
018: * Lesser General Public License for more details.
019: *
020: * You should have received a copy of the GNU Lesser General Public
021: * License along with this library; if not, write to the Free Software
022: * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
023: *
024: * Release: 1.0
025: *
026: * Author: E. Hardesty
027: *
028: * Based on Pool api in ObjectWeb common
029: *
030: */
031:
032: /**
033: * Package definition.
034: */package org.objectweb.jonas.resource.pool.api;
035:
036: /**
037: * Import clauses: one for each external Java definition used. Do not use
038: * clauses in the form "import package.*".
039: */
040:
041: /**
042: * The interface <b>Pool</b> defines an object that pools resources of any
043: * kind. Resources must be requested (getResource) and released
044: * (releaseResource) on demand. A Pool object can be parameterized along
045: * different dimensions. All these dimensions are represented by accessor
046: * methods (getters and setters) assigned to each of them:
047: * <ul>
048: * <li>
049: * A <b>Timeout</b> can be assigned to a Pool. It is used when no more
050: * resources are available and when the Pool has reached its maximum size.
051: * This is the timeout to wait for a free resource until exiting with an
052: * exception. It defaults to 0, which means waiting forever until a
053: * resource is freed. Its value should be greater or equal to 0 ; negative
054: * values are ignored (setTimeOut(-1) => NOP).
055: * </li>
056: * <li>
057: * A <b>MinSize</b> can be assigned to a Pool. Its value should be greater or
058: * equal to 0, and smaller or equal to MaxSize. Values that do not match these
059: * conditions are ignored (e.g., setMinSize(-1) => NOP).
060: * This size means that there is always MinSize PoolResource allocated in this
061: * Pool. If PoolResource needs to be allocated when setting this size,
062: * "getPoolMatchFactory().createResource(null)" is called. Its default value
063: * is 0.
064: * </li>
065: * <li>
066: * A <b>MatchFactory</b> (i.e., a PoolMatchFactory object) must be assigned to
067: * a Pool. It defines the way new PoolResource are created and the way a
068: * PoolResource of a Pool matches some "hints" properties when requested. It is
069: * mandatory for the Pool to be fully functional.
070: * </li>
071: * <li>
072: * A <b>MaxSize</b> can be assigned to a Pool. Its value should be greater or
073: * equal to 0, and greater or equal to MinSize. Values that do not match these
074: * conditions are ignored (e.g., setMaxSize(-1) => NOP). Its default value
075: * is 0, thus it is mandatory to set this value for making the Poll functional.
076: * </li>
077: * </ul>
078: */
079: public interface Pool {
080: /**
081: * <b>adjust</b> checks the age of the entries and removes them if
082: * they are too old
083: *
084: * @throws Exception if an error occurs
085: */
086: void adjust() throws Exception;
087:
088: /**
089: * Close all connections in the pool when server is shutting down.
090: */
091: void closeAllConnections();
092:
093: /**
094: * <b>getJdbcConnLevel</b> gets the jdbc connection level
095: *
096: * @return int jdbc connection level specified
097: */
098: public int getJdbcConnLevel();
099:
100: /**
101: * <b>getJdbcTestStatement</b> gets the JDBC test statement for this pool
102: *
103: * @return String JDBC test statement
104: */
105: public String getJdbcTestStatement();
106:
107: /**
108: * <b>getMatchFactory</b> retrieves the PoolMatchFactory assigned to this
109: * Pool.
110: * @return The PoolMatchFactory currently assigned to this Pool.
111: */
112: PoolMatchFactory getMatchFactory();
113:
114: /**
115: * <b>getMaxAge</b> gets the max age for a pool entry
116: *
117: * @return int max number of minutes to keep a connection
118: * in the pool.
119: */
120: int getMaxAge();
121:
122: /**
123: * <b>getMaxOpentime</b> gets the max age for a pool entry
124: *
125: * @return int max number of minutes to keep a connection
126: * in the pool.
127: */
128: int getMaxOpentime();
129:
130: /**
131: * <b>getMaxSize</b> retrieves the maximum size assigned to this Pool.
132: * @return The maximum size currently assigned to this Pool.
133: */
134: int getMaxSize();
135:
136: /**
137: * <b>getMaxWaiters</b> gets the maximum number of waiters for a connection
138: * in this Pool.
139: *
140: * @param return int maximum number of waiters
141: */
142: int getMaxWaiters();
143:
144: /**
145: * <b>getMaxWaitTime</b> gets the maximum number of seconds to wait for a
146: * connection in this Pool.
147: *
148: * @return int maximum number of seconds to wait
149: */
150: int getMaxWaitTime();
151:
152: /**
153: * <b>getMinSize</b> retrieves the minimum size assigned to this Pool.
154: * @return The minimum size currently assigned to this Pool.
155: */
156: int getMinSize();
157:
158: /**
159: * <b>getResource</b> is used to allocate a Object from the Pool.
160: * Some hints are passed in order to specialise the matching or creation
161: * of Object.
162: * @param hints Some properties to specialise the matching or the creation
163: * of Object.
164: * @return The Object allocated from the Pool.
165: * @throws Exception if an error occurs
166: */
167: Object getResource(Object hints) throws Exception;
168:
169: /**
170: * <b>getSamplingPeriod</b> gets the number of seconds between statistics
171: * sampling for this Pool.
172: *
173: * @return int number of seconds between samplings
174: */
175: int getSamplingPeriod();
176:
177: /**
178: * <b>getTimeout</b> retrieves the timeout assigned to this Pool.
179: * @return The timeout currently assigned to this Pool.
180: */
181: long getTimeout();
182:
183: /**
184: * <b>getSize</b> retrieves the current size of this Pool.
185: * @return The current size of this Pool.
186: */
187: int getSize();
188:
189: /**
190: * @return init The pool init size.
191: */
192: int getInitSize();
193:
194: /**
195: * <b>releaseResource</b> releases a Object in order to allow the
196: * Pool to recycle this Object.
197: * @param resource The Object to be released.
198: * @param destroy boolean to remove the object from the pool and
199: * destroy it
200: * @param adjustment boolean to determine if a pool adjustment should be done
201: * @throws Exception if an error occurs
202: */
203: void releaseResource(Object resource, boolean destroy,
204: boolean adjustment) throws Exception;
205:
206: /**
207: * <b>sampling</b> updates the interval pool information
208: *
209: * @throws Exception if an error occurs
210: */
211: void sampling() throws Exception;
212:
213: /**
214: * <b>setInitSize</b> creates initsize resoures to this Pool.
215: *
216: * @param initsize The init size to be created.
217: * @throws Exception if an error occurs
218: */
219: void setInitSize(int initsize) throws Exception;
220:
221: /**
222: * <b>setJdbcConnLevel</b> sets the JDBC connection level for this pool
223: *
224: * @param jdbcConnLevel int JDBC connection level
225: */
226: public void setJdbcConnLevel(int jdbcConnLevel);
227:
228: /**
229: * <b>setJdbcTestStatement</b> sets the JDBC test statement for this pool
230: *
231: * @param jdbcTestStatement String JDBC test statement
232: */
233: public void setJdbcTestStatement(String jdbcTestStatement);
234:
235: /**
236: * <b>setMatchFactory</b> assigns a PoolMatchFactory to this Pool.
237: *
238: * @param pmf The PoolMatchFactory to be assigned.
239: */
240: void setMatchFactory(PoolMatchFactory pmf);
241:
242: /**
243: * <b>setMaxAge</b> sets the max age for a pool entry
244: *
245: * @param maxAge int max number of minutes to keep a connection
246: * in the pool.
247: */
248: void setMaxAge(int maxAge);
249:
250: /**
251: * <b>setMaxOpentime</b> sets the max age for an entry to be opened
252: *
253: * @param maxOpentime int max number of minutes to keep a connection
254: * opened.
255: */
256: void setMaxOpentime(int maxOpentime);
257:
258: /**
259: * <b>setMaxSize</b> assigns a maximum size to this Pool.
260: *
261: * @param maxsize int maximum size to be assigned.
262: * @throws Exception if an error occurs
263: */
264: void setMaxSize(int maxsize) throws Exception;
265:
266: /**
267: * <b>setMaxWaiters</b> sets the maximum number of waiters for a connection
268: * in this Pool.
269: *
270: * @param maxWaiters int maximum number of waiters
271: */
272: void setMaxWaiters(int maxWaiters);
273:
274: /**
275: * <b>setMaxWaitTime</b> sets the maximum number of seconds to wait for a
276: * connection in this Pool.
277: *
278: * @param maxWaitTime int maximum number of seconds to wait
279: */
280: void setMaxWaitTime(int maxWaitTime);
281:
282: /**
283: * <b>setMinSize</b> assigns a minimum size to this Pool.
284: *
285: * @param minsize int minimum size to be assigned.
286: * @throws Exception if an error occurs
287: */
288: void setMinSize(int minsize) throws Exception;
289:
290: /**
291: * <b>setSamplingPeriod</b> sets the number of seconds between statistics
292: * sampling for this Pool.
293: *
294: * @param samplingPeriod int number of seconds between samplings
295: */
296: void setSamplingPeriod(int samplingPeriod);
297:
298: /**
299: * <b>setTimeout</b> assigns a timeout to this Pool.
300: *
301: * @param crto long timeout to be assigned.
302: */
303: void setTimeout(long crto);
304:
305: /**
306: * <b>startMonitor</b> starts the pool monitor for this Pool.
307: *
308: */
309: void startMonitor();
310:
311: /**
312: * <b>validateMCs</b> validates ManagedConnections in Pool every 10 minutes
313: *
314: * @throws Exception if an error occurs
315: */
316: void validateMCs() throws Exception;
317:
318: /* Statistics area */
319: /**
320: * @return int number of busy connections
321: */
322: public int getCurrentBusy();
323:
324: /**
325: * @return int number of opened connections
326: */
327: public int getCurrentOpened();
328:
329: /**
330: * @return maximum nb of busy connections in last sampling period
331: */
332: int getBusyMaxRecent();
333:
334: /**
335: * @return minimum nb of busy connections in last sampling period
336: */
337: int getBusyMinRecent();
338:
339: /**
340: * @return current number of connection waiters
341: */
342: int getCurrentWaiters();
343:
344: /**
345: * @return int number of physical jdbc connection opened
346: */
347: int getOpenedCount();
348:
349: /**
350: * @return int number of connection failures on open
351: */
352: int getConnectionFailures();
353:
354: /**
355: * @return int number of connection leaks
356: */
357: int getConnectionLeaks();
358:
359: /**
360: * @return int number of connection served
361: */
362: int getServedOpen();
363:
364: /**
365: * @return int number of open calls that were rejected due to waiter overflow
366: */
367: int getRejectedFull();
368:
369: /**
370: * @return int number of open calls that were rejected by timeout
371: */
372: int getRejectedTimeout();
373:
374: /**
375: * @return int number of open calls that were rejected
376: */
377: int getRejectedOther();
378:
379: /**
380: * @return int number of open calls that were rejected
381: */
382: int getRejectedOpen();
383:
384: /**
385: * @return maximum nb of waiters since the datasource creation
386: */
387: int getWaitersHigh();
388:
389: /**
390: * @return maximum nb of waiters in last sampling period
391: */
392: int getWaitersHighRecent();
393:
394: /**
395: * @return total nb of waiters since the datasource creation
396: */
397: int getWaiterCount();
398:
399: /**
400: * @return total waiting time since the datasource creation
401: */
402: long getWaitingTime();
403:
404: /**
405: * @return max waiting time since the datasource creation
406: */
407: long getWaitingHigh();
408:
409: /**
410: * @return max waiting time in last sampling period
411: */
412: long getWaitingHighRecent();
413:
414: }
|