KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > hsqldb > jdbc > jdbcConnection


1 /* Copyright (c) 2001-2005, The HSQL Development Group
2  * All rights reserved.
3  *
4  * Redistribution and use in source and binary forms, with or without
5  * modification, are permitted provided that the following conditions are met:
6  *
7  * Redistributions of source code must retain the above copyright notice, this
8  * list of conditions and the following disclaimer.
9  *
10  * Redistributions in binary form must reproduce the above copyright notice,
11  * this list of conditions and the following disclaimer in the documentation
12  * and/or other materials provided with the distribution.
13  *
14  * Neither the name of the HSQL Development Group nor the names of its
15  * contributors may be used to endorse or promote products derived from this
16  * software without specific prior written permission.
17  *
18  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
19  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21  * ARE DISCLAIMED. IN NO EVENT SHALL HSQL DEVELOPMENT GROUP, HSQLDB.ORG,
22  * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
23  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
24  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
25  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
26  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
27  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
28  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29  */

30
31
32 package org.hsqldb.jdbc;
33
34 import java.sql.CallableStatement JavaDoc;
35 import java.sql.Connection JavaDoc;
36 import java.sql.DatabaseMetaData JavaDoc;
37 import java.sql.PreparedStatement JavaDoc;
38 import java.sql.SQLException JavaDoc;
39 import java.sql.SQLWarning JavaDoc;
40 import java.sql.Statement JavaDoc;
41
42 //#ifdef JDBC3
43
import java.sql.Savepoint JavaDoc;
44
45 //#endif JDBC3
46
//#ifdef JAVA2
47
import java.util.Map JavaDoc;
48
49 //#endif JAVA2
50
import java.util.Locale JavaDoc;
51
52 import org.hsqldb.DatabaseManager;
53 import org.hsqldb.DatabaseURL;
54 import org.hsqldb.HSQLClientConnection;
55 import org.hsqldb.HTTPClientConnection;
56 import org.hsqldb.HsqlException;
57 import org.hsqldb.persist.HsqlProperties;
58 import org.hsqldb.Result;
59 import org.hsqldb.ResultConstants;
60 import org.hsqldb.Session;
61 import org.hsqldb.SessionInterface;
62 import org.hsqldb.Trace;
63 import org.hsqldb.lib.StringUtil;
64
65 // fredt@users 20020320 - patch 1.7.0 - JDBC 2 support and error trapping
66
// JDBC 2 methods can now be called from jdk 1.1.x - see javadoc comments
67
// boucherb@users 20020509 - added "throws SQLException" to all methods where
68
// it was missing here but specified in the java.sql.Connection interface,
69
// updated generic documentation to JDK 1.4, and added JDBC3 methods and docs
70
// boucherb@users and fredt@users 20020505 - extensive review and update
71
// of docs and behaviour to comply with java.sql specification
72
// fredt@users 20020830 - patch 487323 by xclayl@users - better synchronization
73
// fredt@users 20020930 - patch 1.7.1 - support for connection properties
74
// kneedeepincode@users 20021110 - patch 635816 - correction to properties
75
// unsaved@users 20021113 - patch 1.7.2 - SSL support
76
// boucherb@users 2003 ??? - patch 1.7.2 - SSL support moved to factory interface
77
// fredt@users 20030620 - patch 1.7.2 - reworked to use a SessionInterface
78
// boucherb@users 20030801 - JavaDoc updates to reflect new connection urls
79
// boucherb@users 20030819 - patch 1.7.2 - partial fix for broken nativeSQL method
80
// boucherb@users 20030819 - patch 1.7.2 - SQLWarning cases implemented
81

82 /**
83  * <!-- start generic documentation -->
84  * A connection (session) with a specific database. Within the context
85  * of a Connection, SQL statements are executed and results
86  * are returned. <p>
87  *
88  * A Connection's database is able to provide information describing
89  * its tables, its supported SQL grammar, its stored procedures, the
90  * capabilities of this connection, and so on. This information is
91  * obtained with the <code>getMetaData</code> method. <p>
92  *
93  * <B>Note:</B> By default the Connection automatically commits
94  * changes after executing each statement. If auto commit has been
95  * disabled, an explicit commit must be done or database changes will
96  * not be saved. <p>
97  *
98  * <!-- end generic documentation -->
99  * <!-- start release-specific documentation -->
100  * <div class="ReleaseSpecificDocumentation">
101  *
102  * <hr>
103  *
104  * <b>HSQLDB-Specific Information:</b> <p>
105  *
106  * To get a <code>Connection</code> to an HSQLDB database, the
107  * following code may be used (updated to reflect the most recent
108  * recommendations): <p>
109  *
110  * <hr>
111  *
112  * When using HSQLDB, the database connection <b>&lt;url&gt;</b> must start with
113  * <b>'jdbc:hsqldb:'</b><p>
114  *
115  * Since 1.7.2, connection properties (&lt;key-value-pairs&gt;) may be appended
116  * to the database connection <b>&lt;url&gt;</b>, using the form: <p>
117  *
118  * <blockquote>
119  * <b>'&lt;url&gt;[;key=value]*'</b>
120  * </blockquote> <p>
121  *
122  * Also since 1.7.2, the allowable forms of the HSQLDB database connection
123  * <b>&lt;url&gt;</b> have been extended. However, all legacy forms continue
124  * to work, with unchanged semantics. The extensions are as described in the
125  * following material. <p>
126  *
127  * <hr>
128  *
129  * <b>Network Server Database Connections:</b> <p>
130  *
131  * The 1.7.2 {@link Server Server} database connection <b>&lt;url&gt;</b> has
132  * changed to take one of the two following forms: <p>
133  *
134  * <div class="GeneralExample">
135  * <ol>
136  * <li> <b>'jdbc:hsqldb:hsql://host[:port][/&lt;alias&gt;][&lt;key-value-pairs&gt;]'</b>
137  *
138  * <li> <b>'jdbc:hsqldb:hsqls://host[:port][/&lt;alias&gt;][&lt;key-value-pairs&gt;]'</b>
139  * (with TLS).
140  * </ol>
141  * </div> <p>
142  *
143  * The 1.7.2 {@link WebServer WebServer} database connection <b>&lt;url&gt;</b>
144  * also changes to take one of two following forms: <p>
145  *
146  * <div class="GeneralExample">
147  * <ol>
148  * <li> <b>'jdbc:hsqldb:http://host[:port][/&lt;alias&gt;][&lt;key-value-pairs&gt;]'</b>
149  *
150  * <li> <b>'jdbc:hsqldb:https://host[:port][/&lt;alias&gt;][&lt;key-value-pairs&gt;]'</b>
151  * (with TLS).
152  * </ol>
153  * </div><p>
154  *
155  * In both network server database connection <b>&lt;url&gt;</b> forms, the
156  * optional <b>&lt;alias&gt;</b> component is used to identify one of possibly
157  * several database instances available at the indicated host and port. If the
158  * <b>&lt;alias&gt;</b> component is omitted, then a connection is made to the
159  * network server's default database instance. <p>
160  *
161  * For more information on server configuration regarding mounting multiple
162  * databases and assigning them <b>&lt;alias&gt;</b> values, please read the
163  * Java API documentation for {@link org.hsqldb.Server Server} and related
164  * chapters in the general documentation, especially the Advanced Users
165  * Guide. <p>
166  *
167  * <hr>
168  *
169  * <b>Transient, In-Process Database Connections:</b> <p>
170  *
171  * The 1.7.2 100% in-memory (transient, in-process) database connection
172  * <b>&lt;url&gt;</b> takes one of the two following forms: <p>
173  *
174  * <div class="GeneralExample">
175  * <ol>
176  * <li> <b>'jdbc:hsqldb:.[&lt;key-value-pairs&gt;]'</b>
177  * (the legacy form, extended)
178  *
179  * <li> <b>'jdbc:hsqldb:mem:&lt;alias&gt;[&lt;key-value-pairs&gt;]'</b>
180  * (the new form)
181  * </ol>
182  * </div> <p>
183  *
184  * With the 1.7.2 transient, in-process database connection <b>&lt;url&gt;</b>,
185  * the <b>&lt;alias&gt;</b> component is the key used to look up a transient,
186  * in-process database instance amongst the collection of all such instances
187  * already in existence within the current class loading context in the
188  * current JVM. If no such instance exists, one <em>may</em> be automatically
189  * created and mapped to the <b>&lt;alias&gt;</b>, as governed by the
190  * <b>'ifexists=true|false'</b> connection property. <p>
191  *
192  * <hr>
193  *
194  * <b>Persistent, In-Process Database Connections:</b> <p>
195  *
196  * The 1.7.2 standalone (persistent, in-process) database connection
197  * <b>&lt;url&gt;</b> takes one of the three following forms: <p>
198  *
199  * <div class="GeneralExample">
200  * <ol>
201  * <li> <b>'jdbc:hsqldb:&lt;path&gt;[&lt;key-value-pairs&gt;]'</b>
202  * (the legacy form, extended)
203  *
204  * <li> <b>'jdbc:hsqldb:file:&lt;path&gt;[&lt;key-value-pairs&gt;]'</b>
205  * (same semantics as the legacy form)
206  *
207  * <li> <b>'jdbc:hsqldb:res:&lt;path&gt;[&lt;key-value-pairs&gt;]'</b>
208  * (new form with 'files_in_jar' semantics)
209  * </ol>
210  * </div> <p>
211  *
212  * For the persistent, in-process database connection <b>&lt;url&gt;</b>,
213  * the <b>&lt;path&gt;</b> component is the path prefix common to all of
214  * the files that compose the database. <p>
215  *
216  * As of 1.7.2, although other files may be involved (such as transient working
217  * files and/or TEXT table CSV data source files), the essential set that may,
218  * at any particular point in time, compose an HSQLDB database are: <p>
219  *
220  * <div class="GeneralExample">
221  * <ul>
222  * <li>&lt;path&gt;.properties
223  * <li>&lt;path&gt;.script
224  * <li>&lt;path&gt;.log
225  * <li>&lt;path&gt;.data
226  * <li>&lt;path&gt;.backup
227  * <li>&lt;path&gt;.lck
228  * </ul>
229  * </div> <p>
230  *
231  * For example: <b>'jdbc:hsqldb:file:test'</b> connects to a database
232  * composed of some subset of the files listed above, where the expansion
233  * of <b>&lt;path&gt;</b> is <b>'test'</b> prefixed with the path of the
234  * working directory fixed at the time the JVM is started. <p>
235  *
236  * Under <em>Windows</em> <sup><font size="-2">TM</font> </sup>, <b>
237  * 'jdbc:hsqldb:file:c:\databases\test'</b> connects to a database located
238  * on drive <b>'C:'</b> in the directory <b>'databases'</b>, composed
239  * of some subset of the files: <p>
240  *
241  * <pre class="GeneralExample">
242  * C:\
243  * +--databases\
244  * +--test.properties
245  * +--test.script
246  * +--test.log
247  * +--test.data
248  * +--test.backup
249  * +--test.lck
250  * </pre>
251  *
252  * Under most variations of UNIX, <b>'jdbc:hsqldb:file:/databases/test'</b>
253  * connects to a database located in the directory <b>'databases'</b> directly
254  * under root, once again composed of some subset of the files: <p>
255  *
256  * <pre class="GeneralExample">
257  * /
258  * +--databases/
259  * +--test.properties
260  * +--test.script
261  * +--test.log
262  * +--test.data
263  * +--test.backup
264  * +--test.lck
265  * </pre>
266  *
267  * <b>Some Guidelines:</b> <p>
268  *
269  * <ol>
270  * <li> Both relative and absolute database file paths are supported. <p>
271  *
272  * <li> Relative database file paths can be specified in a platform independent
273  * manner as: <b>'[dir1/dir2/.../dirn/]&lt;file-name-prefix&gt;'</b>. <p>
274  *
275  * <li> Specification of absolute file paths is operating-system specific.<br>
276  * Please read your OS file system documentation. <p>
277  *
278  * <li> Specification of network mounts may be operating-system specific.<br>
279  * Please read your OS file system documentation. <p>
280  *
281  * <li> Special care may be needed w.r.t. file path specifications
282  * containing whitespace, mixed-case, special characters and/or
283  * reserved file names.<br>
284  * Please read your OS file system documentation. <p>
285  * </ol> <p>
286  *
287  * <b>Note:</b> Versions of HSQLDB previous to 1.7.0 did not support creating
288  * directories along the file path specified in the persistent, in-process mode
289  * database connection <b>&lt;url&gt;</b> form, in the case that they did
290  * not already exist. Starting with HSQLDB 1.7.0, directories <i>will</i>
291  * be created if they do not already exist., but only if HSQLDB is built under
292  * a version of the compiler greater than JDK 1.1.x. <p>
293  *
294  * <b>res: Connections</b><p>
295  *
296  * The new <b>'jdbc:hsqldb:res:&lt;path&gt;'</b> database connection
297  * <b>&lt;url&gt;</b> has different semantics than the
298  * <b>'jdbc:hsqldb:file:&lt;path&gt;'</b> form. The semantics are similar to
299  * those of a <b>'files_readonly'</b> database, but with some additional
300  * points to consider. <p>
301  *
302  * Specifically, the <b>'&lt;path&gt;'</b> component of a <b>res:</b> type
303  * database connection <b>&lt;url&gt;</b> is used to obtain resource URL
304  * objects and thereby read the database files as resources on the class path.
305  * Moreover, the URL objects <i>must</i> point only to resources contained
306  * in one or more jars on the class path (must be jar protocol). <p>
307  *
308  * This restriction is enforced to avoid the unfortunate situation in which,
309  * because <b>res:</b> database instances do not create a &lt;path&gt;.lck file
310  * (they are strictly files-read-only) and because the <b>&lt;path&gt;</b>
311  * components of <b>res:</b> and <b>file:</b> database URIs are not checked
312  * for file system equivalence, it is possible for the same database files to
313  * be accessed concurrently by both <b>file:</b> and <b>res:</b> database
314  * instances. That is, without this restriction, it is possible that
315  * &lt;path&gt;.data and &lt;path&gt;.properties file content may be written
316  * by a <b>file:</b> database instance without the knowlege or cooperation
317  * of a <b>res:</b> database instance open on the same files, potentially
318  * resulting in unexpected database errors, inconsistent operation
319  * and/or data corruption. <p>
320  *
321  * In short, a <b>res:</b> type database connection <b>&lt;url&gt;</b> is
322  * designed specifically to connect to a <b>'files_in_jar'</b> mode database
323  * instance, which in turn is designed specifically to operate under
324  * <em>Java WebStart</em><sup><font size="-2">TM</font></sup> and
325  * <em>Java Applet</em><sup><font size="-2">TM</font></sup>configurations,
326  * where co-locating the database files in the jars that make up the
327  * <em>WebStart</em> application or Applet avoids the need for special security
328  * configuration or code signing. <p>
329  *
330  * <b>Note:</b> Since it is difficult and often nearly impossible to determine
331  * or control at runtime from where all classes are being loaded or which class
332  * loader is doing the loading under <b>'files_in_jar'</b> semantics, the
333  * <b>&lt;path&gt;</b> component of the res: database connection
334  * <b>&lt;url&gt;</b> is always taken to be relative to the default package.
335  * That is, if the <b>&lt;path&gt;</b> component does not start with '/', then
336  * '/' is prepended when obtaining the resource URLs used to read the database
337  * files. <p>
338  *
339  * <hr>
340  *
341  * For more information about HSQLDB file structure, various database modes
342  * and other attributes such as those controlled through the HSQLDB properties
343  * files, please read the general documentation, especially the Advanced Users
344  * Guide. <p>
345  *
346  * <hr>
347  *
348  * <b>JRE 1.1.x Notes:</b> <p>
349  *
350  * In general, JDBC 2 support requires Java 1.2 and above, and JDBC3 requires
351  * Java 1.4 and above. In HSQLDB, support for methods introduced in different
352  * versions of JDBC depends on the JDK version used for compiling and building
353  * HSQLDB.<p>
354  *
355  * Since 1.7.0, it is possible to build the product so that
356  * all JDBC 2 methods can be called while executing under the version 1.1.x
357  * <em>Java Runtime Environment</em><sup><font size="-2">TM</font></sup>.
358  * However, in addition to this technique requiring explicit casts to the
359  * org.hsqldb.jdbcXXX classes, some of the method calls also require
360  * <code>int</code> values that are defined only in the JDBC 2 or greater
361  * version of
362  * <a HREF="http://java.sun.com/j2se/1.4/docs/api/java/sql/ResultSet.html">
363  * <code>ResultSet</code></a> interface. For this reason, when the
364  * product is compiled under JDK 1.1.x, these values are defined
365  * in {@link org.hsqldb.jdbc.jdbcResultSet jdbcResultSet}. <p>
366  *
367  * In a JRE 1.1.x environment, calling JDBC 2 methods that take or return the
368  * JDBC2-only <code>ResultSet</code> values can be achieved by referring
369  * to them in parameter specifications and return value comparisons,
370  * respectively, as follows: <p>
371  *
372  * <pre class="JavaCodeExample">
373  * jdbcResultSet.FETCH_FORWARD
374  * jdbcResultSet.TYPE_FORWARD_ONLY
375  * jdbcResultSet.TYPE_SCROLL_INSENSITIVE
376  * jdbcResultSet.CONCUR_READ_ONLY
377  * // etc.
378  * </pre>
379  *
380  * However, please note that code written to use HSQLDB JDBC 2 features under
381  * JDK 1.1.x will not be compatible for use with other JDBC 2 drivers. Please
382  * also note that this feature is offered solely as a convenience to developers
383  * who must work under JDK 1.1.x due to operating constraints, yet wish to
384  * use some of the more advanced features available under the JDBC 2
385  * specification. <p>
386  *
387  * <hr>
388  *
389  * (fredt@users)<br>
390  * (boucherb@users)<p>
391  *
392  * </div> <!-- end release-specific documentation -->
393  * @author boucherb@users
394  * @author fredt@users
395  * @version 1.7.2
396  * @see org.hsqldb.jdbcDriver
397  * @see jdbcStatement
398  * @see jdbcPreparedStatement
399  * @see jdbcCallableStatement
400  * @see jdbcResultSet
401  * @see jdbcDatabaseMetaData
402  */

403 public class jdbcConnection implements Connection JavaDoc {
404
405 // ---------------------------- Common Attributes --------------------------
406

407     /**
408      * Properties for the connection
409      *
410      */

411     HsqlProperties connProperties;
412
413     /**
414      * This connection's interface to the corresponding Session
415      * object in the database engine.
416      */

417     SessionInterface sessionProxy;
418
419     /**
420      * Is this an internal connection?
421      */

422     boolean isInternal;
423
424     /** Is this connection to a network server instance. */
425     protected boolean isNetConn;
426
427     /**
428      * Is this connection closed?
429      */

430     boolean isClosed;
431
432     /** The first warning in the chain. Null if there are no warnings. */
433     private SQLWarning JavaDoc rootWarning;
434
435     /** Synchronizes concurrent modification of the warning chain */
436     private Object JavaDoc rootWarning_mutex = new Object JavaDoc();
437
438     /**
439      * The set of open Statement objects returned by this Connection from
440      * calls to createStatement, prepareCall and prepareStatement. This is
441      * used solely for closing the statements when this Connection is closed.
442      */

443     /*
444     private org.hsqldb.lib.HashSet statementSet =
445         new org.hsqldb.lib.HashSet();
446      */

447
448 // ----------------------------------- JDBC 1 -------------------------------
449

450     /**
451      * <!-- start generic documentation -->
452      * Creates a <code>Statement</code>
453      * object for sending SQL statements to the database. SQL
454      * statements without parameters are normally executed using
455      * <code>Statement</code> objects. If the same SQL statement is
456      * executed many times, it may be more efficient to use a
457      * <code>PreparedStatement</code> object.<p>
458      *
459      * Result sets created using the returned <code>Statement</code>
460      * object will by default be type <code>TYPE_FORWARD_ONLY</code>
461      * and have a concurrency level of <code>CONCUR_READ_ONLY</code>.<p>
462      *
463      * <!-- end generic documentation -->
464      * <!-- start release-specific documentation -->
465      * <div class="ReleaseSpecificDocumentation">
466      * <h3>HSQLDB-Specific Information:</h3> <p>
467      *
468      * Starting with HSQLDB 1.7.2, support for precompilation at the engine level
469      * has been implemented, so it is now much more efficient and performant
470      * to use a <code>PreparedStatement</code> object if the same SQL statement
471      * is executed many times. <p>
472      *
473      * Up to 1.6.1, HSQLDB supported <code>TYPE_FORWARD_ONLY</code> -
474      * <code>CONCUR_READ_ONLY</code> results only, so <code>ResultSet</code>
475      * objects created using the returned <code>Statement</code>
476      * object would <I>always</I> be type <code>TYPE_FORWARD_ONLY</code>
477      * with <code>CONCUR_READ_ONLY</code> concurrency. <p>
478      *
479      * Starting with 1.7.0, HSQLDB also supports
480      * <code>TYPE_SCROLL_INSENSITIVE</code> results. <p>
481      *
482      * <b>Notes:</b> <p>
483      *
484      * Up to 1.6.1, calling this method returned <code>null</code> if the
485      * connection was already closed. This was possibly counter-intuitive
486      * to the expectation that an exception would be thrown for
487      * closed connections. Starting with 1.7.0. the behaviour is to throw a
488      * <code>SQLException</code> if the connection is closed. <p>
489      *
490      * </div> <!-- end release-specific documentation -->
491      *
492      * @return a new default Statement object
493      * @throws SQLException if a database access error occurs<p>
494      * @see #createStatement(int,int)
495      * @see #createStatement(int,int,int)
496      */

497     public synchronized Statement JavaDoc createStatement() throws SQLException JavaDoc {
498
499         checkClosed();
500
501         Statement JavaDoc stmt = new jdbcStatement(this,
502                                            jdbcResultSet.TYPE_FORWARD_ONLY);
503
504         return stmt;
505     }
506
507     /**
508      * <!-- start generic documentation -->
509      * Creates a <code>PreparedStatement</code>
510      * object for sending parameterized SQL statements to the
511      * database. <p>
512      *
513      * A SQL statement with or without IN parameters can be
514      * pre-compiled and stored in a <code>PreparedStatement</code>
515      * object. This object can then be used to efficiently execute
516      * this statement multiple times. <p>
517      *
518      * <B>Note:</B> This method is optimized for handling parametric
519      * SQL statements that benefit from precompilation. If the driver
520      * supports precompilation, the method <code>prepareStatement</code>
521      * will send the statement to the database for precompilation.
522      * Some drivers may not support precompilation. In this case, the
523      * statement may not be sent to the database until the
524      * <code>PreparedStatement</code> object is executed. This has no
525      * direct effect on users; however, it does affect which methods
526      * throw certain <code>SQLException</code> objects.<p>
527      *
528      * Result sets created using the returned <code>PreparedStatement</code>
529      * object will by default be type <code>TYPE_FORWARD_ONLY</code>
530      * and have a concurrency level of <code>CONCUR_READ_ONLY</code>.<p>
531      *
532      * <!-- end generic documentation -->
533      * <!-- start release-specific documentation -->
534      * <div class="ReleaseSpecificDocumentation">
535      * <h3>HSQLDB-Specific Information:</h3> <p>
536      *
537      * Starting with HSQLDB 1.7.2, support for precompilation at the engine level
538      * has been implemented, so it is now much more efficient and performant
539      * to use a <code>PreparedStatement</code> object if the same SQL statement
540      * is executed many times. <p>
541      *
542      * Starting with 1.7.2, the support for and behaviour of
543      * PreparedStatment has changed. Please read the introductory section
544      * of the documentation for org.hsqldb.jdbc.jdbcPreparedStatement. <P>
545      *
546      * </div> <!-- end release-specific documentation -->
547      *
548      * @param sql an SQL statement that may contain one or more '?'
549      * IN parameter placeholders
550      * @return a new default <code>PreparedStatement</code> object
551      * containing the pre-compiled SQL statement
552      * @exception SQLException if a database access error occurs <p>
553      * @see #prepareStatement(String,int,int)
554      */

555     public synchronized PreparedStatement JavaDoc prepareStatement(String JavaDoc sql)
556     throws SQLException JavaDoc {
557
558         PreparedStatement JavaDoc stmt;
559
560         checkClosed();
561
562         try {
563             stmt = new jdbcPreparedStatement(this, sql,
564                                              jdbcResultSet.TYPE_FORWARD_ONLY);
565
566             return stmt;
567         } catch (HsqlException e) {
568             throw Util.sqlException(e);
569         }
570     }
571
572     /**
573      * <!-- start generic documentation -->
574      * Creates a <code>CallableStatement</code>
575      * object for calling database stored procedures. The
576      * <code>CallableStatement</code> object provides methods for setting up
577      * its IN and OUT parameters, and methods for executing the call to a
578      * stored procedure. <p>
579      *
580      * <b>Note:</b> This method is optimized for handling stored
581      * procedure call statements. Some drivers may send the call
582      * statement to the database when the method <code>prepareCall</code>
583      * is done; others may wait until the <code>CallableStatement</code>
584      * object is executed. This has no direct effect on users;
585      * however, it does affect which method throws certain
586      * SQLExceptions. <p>
587      *
588      * Result sets created using the returned <code>CallableStatement</code>
589      * object will by default be type <code>TYPE_FORWARD_ONLY</code>
590      * and have a concurrency level of <code>CONCUR_READ_ONLY</code>.<p>
591      *
592      * <!-- end generic documentation -->
593      * <!-- start release-specific documentation -->
594      * <div class="ReleaseSpecificDocumentation">
595      * <h3>HSQLDB-Specific Information:</h3> <p>
596      *
597      * Starting with 1.7.2, the support for and behaviour of
598      * CallableStatement has changed. Please read the introductory section
599      * of the documentation for org.hsqldb.jdbc.jdbcCallableStatement.
600      *
601      * </div> <!-- end release-specific documentation -->
602      *
603      * @param sql a String object that is the SQL statement to be
604      * sent to the database; may contain one or more ?
605      * parameters. <p>
606      *
607      * <B>Note:</B> Typically the SQL statement is a JDBC
608      * function call escape string.
609      * @return a new default <code>CallableStatement</code> object
610      * containing the pre-compiled SQL statement
611      * @exception SQLException if a database access error occurs <p>
612      * @see #prepareCall(String,int,int)
613      */

614     public synchronized CallableStatement JavaDoc prepareCall(String JavaDoc sql)
615     throws SQLException JavaDoc {
616
617         CallableStatement JavaDoc stmt;
618
619         checkClosed();
620
621         try {
622             stmt = new jdbcCallableStatement(this, sql,
623                                              jdbcResultSet.TYPE_FORWARD_ONLY);
624
625             return stmt;
626         } catch (HsqlException e) {
627             throw Util.sqlException(e);
628         }
629     }
630
631     /**
632      * <!-- start generic documentation -->
633      * Converts the given SQL statement
634      * into the system's native SQL grammar. A driver may convert the
635      * JDBC SQL grammar into its system's native SQL grammar prior to
636      * sending it. This method returns the native form of the
637      * statement that the driver would have sent. <p>
638      *
639      * <!-- end generic documentation -->
640      * <!-- start release-specific documentation -->
641      * <div class="ReleaseSpecificDocumentation">
642      * <h3>HSQLDB-Specific Information:</h3> <p>
643      *
644      * Up to and including 1.7.2, HSQLDB converts the JDBC SQL
645      * grammar into the system's native SQL grammar prior to sending
646      * it, if escape processing is set true; this method returns the
647      * native form of the statement that the driver would send in place
648      * of client-specified JDBC SQL grammar. <p>
649      *
650      * Before 1.7.2, escape processing was incomplete and
651      * also broken in terms of support for nested escapes. <p>
652      *
653      * Starting with 1.7.2, escape processing is complete and handles nesting
654      * to arbitrary depth, but enforces a very strict interpretation of the
655      * syntax and does not detect or process SQL comments. <p>
656      *
657      * In essence, the HSQLDB engine directly handles the prescribed syntax
658      * and date / time formats specified internal to the JDBC escapes.
659      * It also directly offers the XOpen / ODBC extended scalar
660      * functions specified available internal to the {fn ...} JDBC escape.
661      * As such, the driver simply removes the curly braces and JDBC escape
662      * codes in the simplest and fastest fashion possible, by replacing them
663      * with whitespace.
664      *
665      * But to avoid a great deal of complexity, certain forms of input
666      * whitespace are currently not recognised. For instance,
667      * the driver handles "{?= call ...}" but not "{ ?= call ...} or
668      * "{? = call ...}" <p>
669      *
670      * Also, comments embedded in SQL are currently not detected or
671      * processed and thus may have unexpected effects on the output
672      * of this method, for instance causing otherwise valid SQL to become
673      * invalid. It is especially important to be aware of this because escape
674      * processing is set true by default for Statement objects and is always
675      * set true when producing a PreparedStatement from prepareStatement()
676      * or CallableStatement from prepareCall(). Currently, it is simply
677      * recommended to avoid submitting SQL having comments containing JDBC
678      * escape sequence patterns and/or single or double quotation marks,
679      * as this will avoid any potential problems.
680      *
681      * It is intended to implement a less strict handling of whitespace and
682      * proper processing of SQL comments at some point in the near future,
683      * perhaps before the final 1.7.2 release.
684      *
685      * In any event, 1.7.2 now correctly processes the following JDBC escape
686      * forms to arbitrary nesting depth, but only if the exact whitespace
687      * layout described below is used: <p>
688      *
689      * <ol>
690      * <li>{call ...}
691      * <li>{?= call ...}
692      * <li>{fn ...}
693      * <li>{oj ...}
694      * <li>{d ...}
695      * <li>{t ...}
696      * <li>{ts ...}
697      * </ol> <p>
698      *
699      * </div> <!-- end release-specific documentation -->
700      *
701      * @param sql a SQL statement that may contain one or more '?'
702      * parameter placeholders
703      * @return the native form of this statement
704      * @throws SQLException if a database access error occurs <p>
705      */

706     public synchronized String JavaDoc nativeSQL(final String JavaDoc sql)
707     throws SQLException JavaDoc {
708
709         // boucherb@users 20030405
710
// FIXME: does not work properly for nested escapes
711
// e.g. {call ...(...,{ts '...'},....)} does not work
712
// boucherb@users 20030817
713
// TESTME: First kick at the FIXME cat done. Now lots of testing
714
// and refinment
715
checkClosed();
716
717         // CHECKME: Thow or return null if input is null?
718
if (sql == null || sql.length() == 0 || sql.indexOf('{') == -1) {
719             return sql;
720         }
721
722         // boolean changed = false;
723
int state = 0;
724         int len = sql.length();
725         int nest = 0;
726         StringBuffer JavaDoc sb = new StringBuffer JavaDoc(sql.length()); //avoid 16 extra
727
String JavaDoc msg;
728
729         //--
730
final int outside_all = 0;
731         final int outside_escape_inside_single_quotes = 1;
732         final int outside_escape_inside_double_quotes = 2;
733
734         //--
735
final int inside_escape = 3;
736         final int inside_escape_inside_single_quotes = 4;
737         final int inside_escape_inside_double_quotes = 5;
738
739         // TODO:
740
// final int inside_single_line_comment = 6;
741
// final int inside_multi_line_comment = 7;
742
// Better than old way for large inputs and for avoiding GC overhead;
743
// toString() reuses internal char[], reducing memory requirment
744
// and garbage items 3:2
745
sb.append(sql);
746
747         for (int i = 0; i < len; i++) {
748             char c = sb.charAt(i);
749
750             switch (state) {
751
752                 case outside_all : // Not inside an escape or quotes
753
if (c == '\'') {
754                         state = outside_escape_inside_single_quotes;
755                     } else if (c == '"') {
756                         state = outside_escape_inside_double_quotes;
757                     } else if (c == '{') {
758                         i = onStartEscapeSequence(sql, sb, i);
759
760                         // changed = true;
761
nest++;
762
763                         state = inside_escape;
764                     }
765                     break;
766
767                 case outside_escape_inside_single_quotes : // inside ' ' only
768
case inside_escape_inside_single_quotes : // inside { } and ' '
769
if (c == '\'') {
770                         state -= 1;
771                     }
772                     break;
773
774                 case outside_escape_inside_double_quotes : // inside " " only
775
case inside_escape_inside_double_quotes : // inside { } and " "
776
if (c == '"') {
777                         state -= 2;
778                     }
779                     break;
780
781                 case inside_escape : // inside { }
782
if (c == '\'') {
783                         state = inside_escape_inside_single_quotes;
784                     } else if (c == '"') {
785                         state = inside_escape_inside_double_quotes;
786                     } else if (c == '}') {
787                         sb.setCharAt(i, ' ');
788
789                         // changed = true;
790
nest--;
791
792                         state = (nest == 0) ? outside_all
793                                             : inside_escape;
794                     } else if (c == '{') {
795                         i = onStartEscapeSequence(sql, sb, i);
796
797                         // changed = true;
798
nest++;
799
800                         state = inside_escape;
801                     }
802             }
803         }
804
805         return sb.toString();
806     }
807
808     /**
809      * <!-- start generic documentation -->
810      * Sets this connection's auto-commit mode to the given state.
811      * If a connection is in auto-commit mode, then all its SQL
812      * statements will be executed and committed as individual transactions.
813      * Otherwise, its SQL statements are grouped into transactions that
814      * are terminated by a call to either the method <code>commit</code> or
815      * the method <code>rollback</code>. By default, new connections are
816      * in auto-commit mode. <p>
817      *
818      * The commit occurs when the statement completes or the next
819      * execute occurs, whichever comes first. In the case of
820      * statements returning a <code>ResultSet</code> object, the
821      * statement completes when the last row of the <code>ResultSet</code>
822      * object has been retrieved or the <code>ResultSet</code> object
823      * has been closed. In advanced cases, a single statement may
824      * return multiple results as well as output parameter values. In
825      * these cases, the commit occurs when all results and output
826      * parameter values have been retrieved. <p>
827      *
828      * <B>NOTE:</B> If this method is called during a transaction,
829      * the transaction is committed. <p>
830      *
831      * <!-- end generic documentation -->
832      * <!-- start release-specific documentation -->
833      * <div class="ReleaseSpecificDocumentation">
834      * <h3>HSQLDB-Specific Information:</h3> <p>
835      *
836      * Up to and including HSQLDB 1.7.2, <p>
837      *
838      * <ol>
839      * <li> All rows of a result set are retrieved internally <em>
840      * before</em> the first row can actually be fetched.<br>
841      * Therefore, a statement can be considered complete as soon as
842      * any XXXStatement.executeXXX method returns. </li>
843      *
844      * <li> Multiple result sets and output parameters are not yet
845      * supported. </li>
846      * </ol>
847      * <p>
848      *
849      * (boucherb@users) </div> <!-- end release-specific
850      * documentation -->
851      *
852      * @param autoCommit <code>true</code> to enable auto-commit
853      * mode; <code>false</code> to disable it
854      * @exception SQLException if a database access error occurs
855      * @see #getAutoCommit
856      */

857     public synchronized void setAutoCommit(boolean autoCommit)
858     throws SQLException JavaDoc {
859
860         checkClosed();
861
862         try {
863             sessionProxy.setAutoCommit(autoCommit);
864         } catch (HsqlException e) {
865             throw Util.sqlException(e);
866         }
867     }
868
869     /**
870      * Gets the current auto-commit state.
871      *
872      * @return the current state of auto-commit mode
873      * @exception SQLException Description of the Exception
874      * @see #setAutoCommit
875      */

876     public synchronized boolean getAutoCommit() throws SQLException JavaDoc {
877
878         checkClosed();
879
880         try {
881             return sessionProxy.isAutoCommit();
882         } catch (HsqlException e) {
883             throw Util.sqlException(e);
884         }
885     }
886
887     /**
888      * <!-- start generic documentation -->
889      * Makes all changes made since the
890      * previous commit/rollback permanent and releases any database
891      * locks currently held by the Connection. This method should be
892      * used only when auto-commit mode has been disabled. <p>
893      *
894      * <!-- end generic documentation -->
895      * <!-- start release-specific documentation -->
896      * <div class="ReleaseSpecificDocumentation">
897      * <h3>HSQLDB-Specific Information:</h3> <p>
898      *
899      * Starting with HSQLDB 1.7.2, savepoints are supported both
900      * in SQL and via the JDBC interface. <p>
901      *
902      * Using SQL, savepoints may be set, released and used in rollback
903      * as follows:
904      *
905      * <pre>
906      * SAVEPOINT &lt;savepoint-name&gt;
907      * RELEASE SAVEPOINT &lt;savepoint-name&gt;
908      * ROLLBACK TO SAVEPOINT &lt;savepoint-name&gt;
909      * </pre>
910      *
911      * </div><!-- end release-specific documentation -->
912      *
913      * @exception SQLException if a database access error occurs
914      * @see #setAutoCommit
915      */

916     public synchronized void commit() throws SQLException JavaDoc {
917
918         checkClosed();
919
920         try {
921             sessionProxy.commit();
922         } catch (HsqlException e) {
923             throw Util.sqlException(e);
924         }
925     }
926
927     /**
928      * <!-- start generic documentation -->
929      * Drops all changes made since the
930      * previous commit/rollback and releases any database locks
931      * currently held by this Connection. This method should be used
932      * only when auto- commit has been disabled. <p>
933      *
934      * <!-- end generic documentation -->
935      * <!-- start release-specific documentation -->
936      * <div class="ReleaseSpecificDocumentation">
937      * <h3>HSQLDB-Specific Information:</h3> <p>
938      *
939      * Starting with HSQLDB 1.7.2, savepoints are fully supported both
940      * in SQL and via the JDBC interface. <p>
941      *
942      * Using SQL, savepoints may be set, released and used in rollback
943      * as follows:
944      *
945      * <pre>
946      * SAVEPOINT &lt;savepoint-name&gt;
947      * RELEASE SAVEPOINT &lt;savepoint-name&gt;
948      * ROLLBACK TO SAVEPOINT &lt;savepoint-name&gt;
949      * </pre>
950      *
951      * </div> <!-- end release-specific documentation -->
952      *
953      * @exception SQLException if a database access error occurs
954      * @see #setAutoCommit
955      */

956     public synchronized void rollback() throws SQLException JavaDoc {
957
958         checkClosed();
959
960         try {
961             sessionProxy.rollback();
962         } catch (HsqlException e) {
963             throw Util.sqlException(e);
964         }
965     }
966
967     /**
968      * <!-- start generic documentation -->
969      * Releases this <code>Connection</code>
970      * object's database and JDBC resources immediately instead of
971      * waiting for them to be automatically released.<p>
972      *
973      * Calling the method <code>close</code> on a <code>Connection</code>
974      * object that is already closed is a no-op. <p>
975      *
976      * <B>Note:</B> A <code>Connection</code> object is automatically
977      * closed when it is garbage collected. Certain fatal errors also
978      * close a <code>Connection</code> object. <p>
979      *
980      * <!-- end generic documentation -->
981      * <!-- start release-specific documentation -->
982      * <div class="ReleaseSpecificDocumentation">
983      * <h3>HSQLDB-Specific Information:</h3> <p>
984      *
985      * In 1.7.2, <code>INTERNAL</code> <code>Connection</code>
986      * objects are not closable from JDBC client code. <p>
987      *
988      * </div> <!-- end release-specific documentation -->
989      *
990      * @exception SQLException if a database access error occurs
991      */

992     public synchronized void close() throws SQLException JavaDoc {
993
994         // Changed to synchronized above because
995
// we would not want a sessionProxy.close()
996
// operation to occur concurrently with a
997
// statementXXX.executeXXX operation.
998
if (isInternal || isClosed) {
999             return;
1000        }
1001
1002        isClosed = true;
1003
1004        if (sessionProxy != null) {
1005            sessionProxy.close();
1006        }
1007
1008        sessionProxy = null;
1009        rootWarning = null;
1010        connProperties = null;
1011    }
1012
1013    /**
1014     * Tests to see if a Connection is closed.
1015     *
1016     * @return true if the connection is closed; false if it's still
1017     * open
1018     */

1019    public synchronized boolean isClosed() {
1020        return isClosed;
1021    }
1022
1023    /**
1024     * <!-- start generic documentation -->
1025     * Gets the metadata regarding this connection's database.
1026     * A Connection's database is able to provide information describing
1027     * its tables, its supported SQL grammar, its stored procedures,
1028     * the capabilities of this connection, and so on. This information
1029     * is made available through a <code>DatabaseMetaData</code> object. <p>
1030     *
1031     * <!-- end generic documentation -->
1032     * <!-- start release-specific documentation -->
1033     * <div class="ReleaseSpecificDocumentation">
1034     * <h3>HSQLDB-Specific Information:</h3> <p>
1035     *
1036     * JDBC <code>DatabaseMetaData</code> methods returning
1037     * <code>ResultSet</code> were not implemented fully before 1.7.2.
1038     * Some of these methods always returned empty result sets.
1039     * Other methods did not accurately
1040     * reflect all of the MetaData for the category.
1041     * Also, some method ignored the filters provided as
1042     * par