001: /*
002: * This software is released under a licence similar to the Apache Software Licence.
003: * See org.logicalcobwebs.proxool.package.html for details.
004: * The latest version is available at http://proxool.sourceforge.net
005: */
006: package org.logicalcobwebs.proxool;
007:
008: import java.util.Properties;
009: import java.util.Set;
010:
011: /**
012: * A full definition of everything to do with a connection. You can get one of these
013: * from {@link ProxoolFacade#getConnectionPoolDefinition ProxoolFacade}.
014: *
015: * <pre>
016: * String alias = "myPool";
017: * ConnectionPoolDefinitionIF cpd = ProxoolFacade.getConnectionPoolDefinition(alias);
018: * </pre>
019: *
020: * If you want to update the definition you should either update the properties
021: * definition next time you
022: * {@link java.sql.Driver#connect ask} for a connection or call
023: * {@link ProxoolFacade#updateConnectionPool Proxool} directly.
024: *
025: * @version $Revision: 1.22 $, $Date: 2004/06/02 20:19:14 $
026: * @author billhorsman
027: * @author $Author: billhorsman $ (current maintainer)
028: */
029: public interface ConnectionPoolDefinitionIF {
030:
031: /** 4 * 60 * 60 * 1000 (4 hours) */
032: public static final int DEFAULT_MAXIMUM_CONNECTION_LIFETIME = 4 * 60 * 60 * 1000; // 4 hours
033:
034: /** 300000 (5 minutes) */
035: public static final int DEFAULT_MAXIMUM_ACTIVE_TIME = 300000; // 5 minutes
036:
037: /** 0 */
038: public static final int DEFAULT_PROTOTYPE_COUNT = 0;
039:
040: /** 0 */
041: public static final int DEFAULT_MINIMUM_CONNECTION_COUNT = 0;
042:
043: /** 15 */
044: public static final int DEFAULT_MAXIMUM_CONNECTION_COUNT = 15;
045:
046: /** 30000 (30 Seconds) */
047: public static final int DEFAULT_HOUSE_KEEPING_SLEEP_TIME = 30000;
048:
049: /** 10
050: * @deprecated use {@link #DEFAULT_SIMULTANEOUS_BUILD_THROTTLE} instead
051: */
052: public static final int DEFAULT_MAXIMUM_NEW_CONNECTIONS = 10;
053:
054: /** 10 */
055: public static final int DEFAULT_SIMULTANEOUS_BUILD_THROTTLE = 10;
056:
057: /** 60000 */
058: public static final int DEFAULT_OVERLOAD_WITHOUT_REFUSAL_THRESHOLD = 60000;
059:
060: /** 60000 */
061: public static final int DEFAULT_RECENTLY_STARTED_THRESHOLD = 60000;
062:
063: public static final int DEBUG_LEVEL_QUIET = 0;
064:
065: public static final int DEBUG_LEVEL_LOUD = 1;
066:
067: public static final String USER_PROPERTY = "user";
068:
069: public static final String PASSWORD_PROPERTY = "password";
070:
071: /**
072: * @see #getFatalSqlExceptions
073: */
074: public static final String FATAL_SQL_EXCEPTIONS_DELIMITER = ",";
075:
076: /** This is the time the house keeping thread sleeps for between checks. (milliseconds) */
077: int getHouseKeepingSleepTime();
078:
079: /** The maximum number of connections to the database */
080: int getMaximumConnectionCount();
081:
082: /** The maximum amount of time that a connection exists for before it is killed (recycled). (milliseconds) */
083: int getMaximumConnectionLifetime();
084:
085: /**
086: * In order to prevent overloading, this is the maximum number of connections that you can have that are in the progress
087: * of being made. That is, ones we have started to make but haven't finished yet.
088: * @deprecated use more descriptive {@link #getSimultaneousBuildThrottle} instead
089: */
090: int getMaximumNewConnections();
091:
092: /**
093: * In order to prevent overloading, this is the maximum number of connections that you can have that are in the progress
094: * of being made. That is, ones we have started to make but haven't finished yet.
095: */
096: int getSimultaneousBuildThrottle();
097:
098: /** The minimum number of connections we will keep open, regardless of whether anyone needs them or not. */
099: int getMinimumConnectionCount();
100:
101: /** @deprecated use {@link #getAlias} instead. */
102: String getName();
103:
104: /** The name associated with this connection pool. This is how you identify this pool when you need to use it. */
105: String getAlias();
106:
107: /** The password to use to login to the database */
108: String getPassword();
109:
110: /**
111: * This is the number of spare connections we will strive to have. So, if we have a prototypeCount of 5 but only 3 spare
112: * connections the prototyper will make an additional 2. This is important because it can take around a seconds to
113: * establish a connection, and if we are being very strict about killing connections when they get too
114: * old it happens a fair bit.
115: */
116: int getPrototypeCount();
117:
118: /** This is the URL used to connect to the database. e.g. driver:@host:port:database. */
119: String getUrl();
120:
121: /* The user used to login to the database. */
122:
123: String getUser();
124:
125: /* Interrogate the JDBC driver for its version (warning: this information is not always correct - be
126: very suspicious if it reports the version as 1.0) */
127: String getJdbcDriverVersion();
128:
129: /**
130: * Get all of the properties that are defined on the delegated driver.
131: * @return the delegate properties
132: * @deprecated use less ambiguous {@link #getDelegateProperties} instead
133: */
134: Properties getProperties();
135:
136: String getDriver();
137:
138: /** As long as we have one connection that was started within this threshold
139: then we consider the pool to be up. (That is, not down). This allows us to
140: differentiate between having all the connections frozen and just being really
141: busy. */
142: int getRecentlyStartedThreshold();
143:
144: /** This is the time in milliseconds after the last time that we refused a
145: connection that we still consider ourselves to be overloaded. We have to do this
146: because, even when overloaded, it's not impossible for the available connection
147: count to be high and it's possible to be serving a lot of connections.
148: Recognising an overload is easy (we refuse a connection) - it's recognising
149: when we stop being overloaded that is hard. Hence this fudge :) */
150: int getOverloadWithoutRefusalLifetime();
151:
152: /** If the housekeeper comes across a thread that has been active for longer
153: than this then it will kill it. So make sure you set this to a number bigger
154: than your slowest expected response! */
155: int getMaximumActiveTime();
156:
157: /**
158: * @deprecated use {@link #isVerbose} instead
159: */
160: int getDebugLevel();
161:
162: /**
163: * Get the list of fatal SQL exception (Strings) fragments that will
164: * trigger the death of a Connection.
165: * All SQLExceptions are caught and tested for containing this
166: * text fragment. If it matches than this connection is considered useless
167: * and it is discarded. Regardless of what happens the exception
168: * is always thrown back to the user.
169: * @return the list of exception fragments (String)
170: * @see #FATAL_SQL_EXCEPTIONS_DELIMITER
171: */
172: Set getFatalSqlExceptions();
173:
174: /**
175: * The test SQL that we perform to see if a connection is alright.
176: * Should be fast and robust.
177: * @return house keeping test SQL
178: */
179: String getHouseKeepingTestSql();
180:
181: /**
182: * Whether we test each connection before it is served
183: * @return true if we do the test
184: * @see #getHouseKeepingTestSql
185: */
186: boolean isTestBeforeUse();
187:
188: /**
189: * Whether we test each connection after it is closed
190: * (that is, returned to the pool)
191: * @return true if we do the test
192: * @see #getHouseKeepingTestSql
193: */
194: boolean isTestAfterUse();
195:
196: /**
197: * The URL that was used to define this pool. For example:
198: * proxool:org.hsqldb.jdbcDriver:jdbc:hsqldb:test
199: * @return the complete url
200: */
201: String getCompleteUrl();
202:
203: /**
204: * If this is true then we start logging a lot of stuff everytime we serve a
205: * connection and everytime the house keeper and prototyper run. Be
206: * prepared for a lot of debug!
207: *
208: * @return true if in verbose mode
209: */
210: boolean isVerbose();
211:
212: /**
213: * if this is true then we will log each execution. The SQL used and the
214: * execution time.
215: *
216: * @return true if we should log each execution
217: */
218: boolean isTrace();
219:
220: /**
221: * The sample length (in seconds) when taking statistical information,
222: * or null to disable statistics. Default is null. You can comma delimit
223: * a series of periods. The suffix for the period is either "s" (seconds),
224: * "m" (minutes), "h" (hours) or "d" (days). For example: "15s,1h" would
225: * give two separate sample rates: every 15 seconds and every hour.
226: * @return statistics definition
227: */
228: String getStatistics();
229:
230: /**
231: * Whether statistics are logged as they are produced.
232: * Range: DEBUG, INFO, WARN, ERROR, FATAL.
233: * Default is null (no logging)
234: * @return statisticsLogLevel
235: */
236: String getStatisticsLogLevel();
237:
238: /**
239: * Get all of the properties that are defined on the delegated driver.
240: * @return the delegate properties
241: */
242: Properties getDelegateProperties();
243:
244: String getDelegateProperty(String name);
245:
246: /**
247: * If this is not-null then any fatal SQLException is wrapped up inside
248: * an instance of this class. If null, then the original exception is
249: * thrown.
250: * Range: any valid class name that is a subclass of SQLException or RuntimeException
251: * Default: null (original exception is thrown)
252: * @return the class name to use for fatal SQL exceptions
253: */
254: String getFatalSqlExceptionWrapper();
255:
256: /**
257: * JNDI property
258: * @return the initial context factory
259: */
260: String getInitialContextFactory();
261:
262: /**
263: * JNDI property
264: * @return provider URL
265: */
266: String getProviderUrl();
267:
268: /**
269: * JNDI property
270: * @return security authentication
271: */
272: String getSecurityAuthentication();
273:
274: /**
275: * JNDI property
276: * @return security principal
277: */
278: String getSecurityPrincipal();
279:
280: /**
281: * JNDI property
282: * @return security credentials
283: */
284: String getSecurityCredentials();
285:
286: /**
287: * JNDI property
288: * @return JNDI name
289: */
290: String getJndiName();
291:
292: /**
293: * Indicate wether this pool should be registered with JMX or not.
294: * @return wether this pool should be registered with JMX or not.
295: */
296: boolean isJmx();
297:
298: /**
299: * Get a comma separated list of JMX agent ids (as used by
300: * <code>MBeanServerFactory.findMBeanServer(String agentId)</code>) to register the pool to.
301: * @return a comma separated list of JMX agent ids (as used by
302: * <code>MBeanServerFactory.findMBeanServer(String agentId)</code>) to register the pool to.
303: */
304: String getJmxAgentId();
305:
306: /**
307: * The class name of an interface that should be injected everytime we make a Connection.
308: * Use this when you want to access methods on a concrete class in the vendor's Connection
309: * object that aren't declared in a public interface. Without this, the connection that
310: * gets served will only give you access to public interfaces (like Connection and any
311: * other vendor provided ones)
312: * @return the interface
313: */
314: Class getInjectableConnectionInterface();
315:
316: /**
317: * The class name of an interface that should be injected everytime we make a Statement.
318: * Use this when you want to access methods on a concrete class in the vendor's Statement
319: * object that aren't declared in a public interface. Without this, the statement that
320: * is provided will only give you access to public interfaces (like Statement and any
321: * other vendor provided ones)
322: * @return the interface
323: */
324: Class getInjectableStatementInterface();
325:
326: /**
327: * The class name of an interface that should be injected everytime we make a PreparedStatement.
328: * Use this when you want to access methods on a concrete class in the vendor's PreparedStatement
329: * object that aren't declared in a public interface. Without this, the PreparedStatement that
330: * is provided will only give you access to public interfaces (like PreparedStatement and any
331: * other vendor provided ones)
332: * @return the interface
333: */
334: Class getInjectablePreparedStatementInterface();
335:
336: /**
337: * The class name of an interface that should be injected everytime we make a CallableStatement.
338: * Use this when you want to access methods on a concrete class in the vendor's CallableStatement
339: * object that aren't declared in a public interface. Without this, the CallableStatement that
340: * is provided will only give you access to public interfaces (like CallableStatement and any
341: * other vendor provided ones)
342: * @return the interface
343: */
344: Class getInjectableCallableStatementInterface();
345:
346: }
347:
348: /*
349: Revision history:
350: $Log: ConnectionPoolDefinitionIF.java,v $
351: Revision 1.22 2004/06/02 20:19:14 billhorsman
352: Added injectable interface properties
353:
354: Revision 1.21 2004/03/18 17:08:14 chr32
355: Added jmx* properties.
356:
357: Revision 1.20 2003/09/30 18:39:08 billhorsman
358: New test-before-use, test-after-use and fatal-sql-exception-wrapper-class properties.
359:
360: Revision 1.19 2003/09/29 17:48:08 billhorsman
361: New fatal-sql-exception-wrapper-class allows you to define what exception is used as a wrapper. This means that you
362: can make it a RuntimeException if you need to.
363:
364: Revision 1.18 2003/09/05 16:59:42 billhorsman
365: Added wrap-fatal-sql-exceptions property
366:
367: Revision 1.17 2003/07/23 06:54:48 billhorsman
368: draft JNDI changes (shouldn't effect normal operation)
369:
370: Revision 1.16 2003/03/05 23:28:56 billhorsman
371: deprecated maximum-new-connections property in favour of
372: more descriptive simultaneous-build-throttle
373:
374: Revision 1.15 2003/03/03 11:11:57 billhorsman
375: fixed licence
376:
377: Revision 1.14 2003/02/26 16:05:52 billhorsman
378: widespread changes caused by refactoring the way we
379: update and redefine pool definitions.
380:
381: Revision 1.13 2003/02/06 15:41:17 billhorsman
382: add statistics-log-level
383:
384: Revision 1.12 2003/01/31 00:17:04 billhorsman
385: statistics is now a string to allow multiple,
386: comma-delimited values
387:
388: Revision 1.11 2003/01/30 17:20:37 billhorsman
389: new statistics property
390:
391: Revision 1.10 2003/01/17 00:38:12 billhorsman
392: wide ranging changes to clarify use of alias and url -
393: this has led to some signature changes (new exceptions
394: thrown) on the ProxoolFacade API.
395:
396: Revision 1.9 2002/12/17 14:20:44 billhorsman
397: doc
398:
399: Revision 1.8 2002/12/15 19:21:42 chr32
400: Changed @linkplain to @link (to preserve JavaDoc for 1.2/1.3 users).
401:
402: Revision 1.7 2002/11/09 15:50:15 billhorsman
403: new trace property and better doc
404:
405: Revision 1.6 2002/10/27 13:29:38 billhorsman
406: deprecated debug-level in favour of verbose
407:
408: Revision 1.5 2002/10/27 12:09:00 billhorsman
409: default minimum connection count changed from 5 to 0
410:
411: Revision 1.4 2002/10/25 16:00:25 billhorsman
412: added better class javadoc
413:
414: Revision 1.3 2002/10/24 17:29:06 billhorsman
415: prototype count now defaults to zero
416:
417: Revision 1.2 2002/10/17 19:46:02 billhorsman
418: removed redundant reference to logFilename (we now use Jakarta's Commons Logging component
419:
420: Revision 1.1.1.1 2002/09/13 08:13:02 billhorsman
421: new
422:
423: Revision 1.6 2002/07/02 08:44:56 billhorsman
424: Removed all mutators
425:
426: Revision 1.5 2002/06/28 11:19:47 billhorsman
427: improved doc
428:
429: */
|