ConnectionPoolDefinitionIF


1   /*
2    * This software is released under a licence similar to the Apache Software Licence.
3    * See org.logicalcobwebs.proxool.package.html for details.
4    * The latest version is available at http://proxool.sourceforge.net
5    */
6   package org.logicalcobwebs.proxool;
7   
8   import java.util.Properties  ;
9   import java.util.Set  ;
10  
11  /**
12   * A full definition of everything to do with a connection. You can get one of these
13   * from {@link ProxoolFacade#getConnectionPoolDefinition ProxoolFacade}.
14   *
15   * <pre>
16   * String alias = "myPool";
17   * ConnectionPoolDefinitionIF cpd = ProxoolFacade.getConnectionPoolDefinition(alias);
18   * </pre>
19   *
20   * If you want to update the definition you should either update the properties
21   * definition next time you
22   * {@link java.sql.Driver#connect ask} for a connection or call
23   * {@link ProxoolFacade#updateConnectionPool Proxool} directly.
24   *
25   * @version $Revision: 1.22 $, $Date: 2004/06/02 20:19:14 $
26   * @author billhorsman
27   * @author $Author: billhorsman $ (current maintainer)
28   */
29  public interface ConnectionPoolDefinitionIF {
30  
31      /** 4 * 60 * 60 * 1000 (4 hours) */
32      public static final int DEFAULT_MAXIMUM_CONNECTION_LIFETIME = 4 * 60 * 60 * 1000; // 4 hours
33  
34      /** 300000 (5 minutes) */
35      public static final int DEFAULT_MAXIMUM_ACTIVE_TIME = 300000; // 5 minutes
36  
37      /** 0 */
38      public static final int DEFAULT_PROTOTYPE_COUNT = 0;
39  
40      /** 0 */
41      public static final int DEFAULT_MINIMUM_CONNECTION_COUNT = 0;
42  
43      /** 15 */
44      public static final int DEFAULT_MAXIMUM_CONNECTION_COUNT = 15;
45  
46      /** 30000 (30 Seconds) */
47      public static final int DEFAULT_HOUSE_KEEPING_SLEEP_TIME = 30000;
48  
49      /** 10
50       * @deprecated use {@link #DEFAULT_SIMULTANEOUS_BUILD_THROTTLE} instead
51       */
52      public static final int DEFAULT_MAXIMUM_NEW_CONNECTIONS = 10;
53  
54      /** 10 */
55      public static final int DEFAULT_SIMULTANEOUS_BUILD_THROTTLE = 10;
56  
57      /** 60000 */
58      public static final int DEFAULT_OVERLOAD_WITHOUT_REFUSAL_THRESHOLD = 60000;
59  
60      /** 60000 */
61      public static final int DEFAULT_RECENTLY_STARTED_THRESHOLD = 60000;
62  
63      public static final int DEBUG_LEVEL_QUIET = 0;
64  
65      public static final int DEBUG_LEVEL_LOUD = 1;
66  
67      public static final String   USER_PROPERTY = "user";
68  
69      public static final String   PASSWORD_PROPERTY = "password";
70  
71      /**
72       * @see #getFatalSqlExceptions
73       */
74      public static final String   FATAL_SQL_EXCEPTIONS_DELIMITER = ",";
75  
76      /** This is the time the house keeping thread sleeps for between checks. (milliseconds) */
77      int getHouseKeepingSleepTime();
78  
79      /** The maximum number of connections to the database */
80      int getMaximumConnectionCount();
81  
82      /** The maximum amount of time that a connection exists for before it is killed (recycled). (milliseconds) */
83      int getMaximumConnectionLifetime();
84  
85      /**
86       * In order to prevent overloading, this is the maximum number of connections that you can have that are in the progress
87       * of being made. That is, ones we have started to make but haven't finished yet.
88       * @deprecated use more descriptive {@link  #getSimultaneousBuildThrottle} instead
89       */
90      int getMaximumNewConnections();
91  
92      /**
93       * In order to prevent overloading, this is the maximum number of connections that you can have that are in the progress
94       * of being made. That is, ones we have started to make but haven't finished yet.
95       */
96      int getSimultaneousBuildThrottle();
97  
98      /** The minimum number of connections we will keep open, regardless of whether anyone needs them or not. */
99      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 */
430
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags