Source code: org/hsqldb/jdbcConnection.java
1 /* Copyrights and Licenses
2 *
3 * This product includes Hypersonic SQL.
4 * Originally developed by Thomas Mueller and the Hypersonic SQL Group.
5 *
6 * Copyright (c) 1995-2000 by the Hypersonic SQL Group. All rights reserved.
7 * Redistribution and use in source and binary forms, with or without modification, are permitted
8 * provided that the following conditions are met:
9 * - Redistributions of source code must retain the above copyright notice, this list of conditions
10 * and the following disclaimer.
11 * - Redistributions in binary form must reproduce the above copyright notice, this list of
12 * conditions and the following disclaimer in the documentation and/or other materials
13 * provided with the distribution.
14 * - All advertising materials mentioning features or use of this software must display the
15 * following acknowledgment: "This product includes Hypersonic SQL."
16 * - Products derived from this software may not be called "Hypersonic SQL" nor may
17 * "Hypersonic SQL" appear in their names without prior written permission of the
18 * Hypersonic SQL Group.
19 * - Redistributions of any form whatsoever must retain the following acknowledgment: "This
20 * product includes Hypersonic SQL."
21 * This software is provided "as is" and any expressed or implied warranties, including, but
22 * not limited to, the implied warranties of merchantability and fitness for a particular purpose are
23 * disclaimed. In no event shall the Hypersonic SQL Group or its contributors be liable for any
24 * direct, indirect, incidental, special, exemplary, or consequential damages (including, but
25 * not limited to, procurement of substitute goods or services; loss of use, data, or profits;
26 * or business interruption). However caused any on any theory of liability, whether in contract,
27 * strict liability, or tort (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 * This software consists of voluntary contributions made by many individuals on behalf of the
30 * Hypersonic SQL Group.
31 *
32 *
33 * For work added by the HSQL Development Group:
34 *
35 * Copyright (c) 2001-2002, The HSQL Development Group
36 * All rights reserved.
37 *
38 * Redistribution and use in source and binary forms, with or without
39 * modification, are permitted provided that the following conditions are met:
40 *
41 * Redistributions of source code must retain the above copyright notice, this
42 * list of conditions and the following disclaimer, including earlier
43 * license statements (above) and comply with all above license conditions.
44 *
45 * Redistributions in binary form must reproduce the above copyright notice,
46 * this list of conditions and the following disclaimer in the documentation
47 * and/or other materials provided with the distribution, including earlier
48 * license statements (above) and comply with all above license conditions.
49 *
50 * Neither the name of the HSQL Development Group nor the names of its
51 * contributors may be used to endorse or promote products derived from this
52 * software without specific prior written permission.
53 *
54 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
55 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
56 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
57 * ARE DISCLAIMED. IN NO EVENT SHALL HSQL DEVELOPMENT GROUP, HSQLDB.ORG,
58 * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
59 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
60 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
61 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
62 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
63 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
64 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
65 */
66
67
68 package org.hsqldb;
69
70 import java.io.BufferedInputStream;
71 import java.io.BufferedOutputStream;
72 import java.io.DataInputStream;
73 import java.io.DataOutputStream;
74 import java.io.InputStream;
75 import java.io.OutputStream;
76 import java.net.Socket;
77 import java.net.URL;
78 import java.net.URLConnection;
79 import java.sql.CallableStatement;
80 import java.sql.Connection;
81 import java.sql.DatabaseMetaData;
82 import java.sql.PreparedStatement;
83 import java.sql.ResultSet;
84 import java.sql.SQLException;
85 import java.sql.SQLWarning;
86 import java.sql.Statement;
87 import java.util.*; // for Map
88 import java.util.Hashtable;
89 import java.util.StringTokenizer;
90
91 // fredt@users 20020320 - patch 1.7.0 - JDBC 2 support and error trapping
92 // JDBC 2 methods can now be called from jdk 1.1.x - see javadoc comments
93 // boucherb@users 20020509 - added "throws SQLException" to all methods where
94 // it was missing here but specified in the java.sql.Connection interface,
95 // updated generic documentation to JDK 1.4, and added JDBC3 methods and docs
96 // boucherb@users and fredt@users 20020409/20020505 extensive review and update
97 // of docs and behaviour to comply with previous and latest java.sql specification
98 // fredt@users 20020830 - patch 487323 by xclayl@users - better synchronization
99
100 /**
101 * <!-- start generic documentation -->
102 * A connection (session) with a specific database. Within the context
103 * of a Connection, SQL statements are executed and results
104 * are returned. <p>
105 *
106 * A Connection's database is able to provide information describing
107 * its tables, its supported SQL grammar, its stored procedures, the
108 * capabilities of this connection, and so on. This information is
109 * obtained with the <code>getMetaData</code> method. <p>
110 *
111 * <B>Note:</B> By default the Connection automatically commits
112 * changes after executing each statement. If auto commit has been
113 * disabled, an explicit commit must be done or database changes will
114 * not be saved. <p>
115 *
116 * <!-- end generic documentation -->
117 * <!-- start release-specific documentation -->
118 * <span class="ReleaseSpecificDocumentation">
119 * <b>HSQLDB-Specific Information:</b> <p>
120 *
121 * To get a <code>Connection</code> to an HSQLDB database, the
122 * following code may be used: <p>
123 *
124 * <code class="JavaCodeExample">
125 * Class.<b>forName</b> (<span class="JavaStringLiteral">
126 * "org.hsqldb.jdbcDriver"</span> );<br>
127 * Connection c = DriverManager.<b>getConnection</b>
128 * (url,user,password); </code><p>
129 *
130 * For HSQLDB connections, the <B>url</B> must start with <B>
131 * 'jdbc:hsqldb'</B> .<p>
132 *
133 * The {@link Server Server} database <B>url</B> is <B>
134 * 'jdbc:hsqldb:hsql://host[:port]'</B> . <p>
135 *
136 * The {@link WebServer WebServer} database <B>url</B> is <B>
137 * 'jdbc:hsqldb:http://host[:port]'</B> . <p>
138 *
139 * The In-Memory (diskless, in-process) database <B>url</B> is <B>
140 * 'jdbc:hsqldb:.'</B> . <p>
141 *
142 * The Standalone (in-process) database connection <B>url</B> is <B>
143 * 'jdbc:hsqldb:name'</B> . <p>
144 *
145 * <B>'name'</B> is the common prefix of the files that compose the
146 * database, including the <B>path</B> .<p>
147 *
148 * For example: <B>'jdbc:hsqldb:test'</B> connects to a database
149 * named <B>'test'</B> , which is composed of the files <B>
150 * 'test.properties'</B> , <B>'test.data'</B> and <B>'test.script'
151 * </B>, all located in the working directory fixed at the time the
152 * JVM is started. <p>
153 *
154 * Under <em>Windows</em> <sup><font size="-2">TM</font> </sup> , <B>
155 * 'jdbc:hsqldb:c:\databases\test'</B> connects to a database named
156 * <B>'test'</B> , located on drive c: in the directory <B>
157 * 'databases'</B> , composed of the files: <B>'test.properties'</B>
158 * , <B>'test.data'</B> and <B>'test.script'</B> . <p>
159 *
160 * Under most variations of UNIX, <B>'jdbc:hsqldb:/databases/test'
161 * </B> connects to a database named <B>'test'</B> located in the
162 * directory <B>'databases'</B> directly under root, and composed of
163 * the files: <B>'test.properties'</B> , <B>'test.data'</B> and <B>
164 * 'test.script'</B> . <p>
165 *
166 * <B>Some Guidelines:</B>
167 * <OL>
168 * <LI> Both relative and absolute paths are supported.</LI>
169 * <LI> Relative paths can be specified in a platform independent
170 * manner as: <B>'[dir1/dir2/.../dirn/]name'.</B> </LI>
171 * <LI> Specification of absolute paths is operating-system
172 * specific.<br>
173 * Please read your OS file system documentation.</LI>
174 * <LI> Typically, special care must be taken w.r.t. path
175 * specifications containing whitespace, and mixed-case may also be
176 * a concern.<br>
177 * Please read your OS file system documentation.</LI>
178 * </OL>
179 * <B>Note:</B> Previous versions of HSQLDB did not support creating
180 * directories along the path specified in Standalone mode jdbc urls,
181 * in the case that they did not already exist. As of HSQLDB 1.7.0,
182 * directories <i>will</i> be created if they do not already exist
183 * (but not if the HSQLDB Jar is built under JDK 1.1.x).
184 * <p>
185 *
186 * For more information about HSQLDB file structure, please read the
187 * {@link Files Files} section of the documentation. <p>
188 *
189 * <b>JRE 1.1.x Notes:</b> <p>
190 *
191 * In general, JDBC 2 support requires Java 1.2 and above, and JDBC3 requires
192 * Java 1.4 and above. In HSQLDB, support for methods introduced in different
193 * versions of JDBC depends on the JDK version used for compiling and building
194 * HSQLDB.<p>
195 *
196 * Since 1.7.0, it is possible to build the product so that
197 * all JDBC 2 methods can be called while executing under the version 1.1.x
198 * <em>Java Runtime Environment</em><sup><font size="-2">TM</font></sup>.
199 * However, some of these method calls require <code>int</code> values that
200 * are defined only in the JDBC 2 or greater version of
201 * <a href="http://java.sun.com/j2se/1.4/docs/api/java/sql/ResultSet.html">
202 * <CODE>ResultSet</CODE></a> interface. For this reason, when the
203 * product is compiled under JDK 1.1.x, these values are defined here in
204 * this class.<p>
205 *
206 * In a JRE 1.1.x environment, calling JDBC 2 methods that take or return the
207 * JDBC2-only <CODE>ResultSet</CODE> values can be achieved by referring
208 * to them in parameter specifications and return value comparisons,
209 * respectively, as follows: <p>
210 *
211 * <CODE class="JavaCodeExample">
212 * jdbcResultSet.FETCH_FORWARD<br>
213 * jdbcResultSet.TYPE_FORWARD_ONLY<br>
214 * jdbcResultSet.TYPE_SCROLL_INSENSITIVE<br>
215 * jdbcResultSet.CONCUR_READ_ONLY<br>
216 * </CODE> <p>
217 *
218 * However, please note that code written in such a manner will not be
219 * compatible for use with other JDBC 2 drivers, since they expect and use
220 * <code>ResultSet</code>, rather than <code>jdbcResultSet</code>. Also
221 * note, this feature is offered solely as a convenience to developers
222 * who must work under JDK 1.1.x due to operating constraints, yet wish to
223 * use some of the more advanced features available under the JDBC 2
224 * specification.<p>
225 *
226 * (fredt@users)<br>
227 * (boucherb@users)<p>
228 *
229 * </span> <!-- end release-specific documentation -->
230 *
231 * @see jdbcDriver
232 * @see jdbcStatement
233 * @see jdbcResultSet
234 * @see jdbcDatabaseMetaData
235 */
236 public class jdbcConnection implements Connection {
237
238 // ---------------------------- Common Attributes --------------------------
239
240 /**
241 * Is this connection closed?<p>
242 *
243 * This attribute is false until the first call to {@link
244 * #close()}. If the close is successful, then this
245 * attribute is set to true and stays true until this connection
246 * is eventually garbage collected.
247 */
248 private boolean bClosed;
249
250 /**
251 * The name of this connection's {@link Database Database}, as
252 * known to this connection. <p>
253 *
254 * <B>Note:</B> Network connections know their database name as
255 * the network url of that database, without the protocol
256 * specifier. Connections to in-process database instances know
257 * their database name as the local path specifier for the
258 * database. For in-memory databases, this is always <B>"."</B>
259 */
260 private String sDatabaseName;
261
262 /**
263 * Properties for the connection
264 *
265 */
266 private HsqlProperties connProperties;
267
268 /**
269 * One of the possible values for this connection's type. <p>
270 *
271 * This value indicates a network <code>Connection</code> to a
272 * {@link org.hsqldb.WebServer WebServer} mode <code>Database</code>,
273 * using http protocol. <p>
274 */
275 final static int HTTP = 0;
276
277 /**
278 * One of the possible values for this connection's type. <p>
279 *
280 * This value indicates a <code>Connection</code> to an
281 * in-process (Standalone mode) <code>Database</code>. <p>
282 */
283 final static int STANDALONE = 1;
284
285 /**
286 * One of the possible values for this connection's type. <p>
287 *
288 * This value indicates a <code>Connection</code> created inside
289 * the database on behalf of an existing {@link Session Session},
290 * to be used as the parameter to a SQL function or stored
291 * procedure that needs to execute in the context of the calling
292 * <code>Session</code>. <p>
293 *
294 *
295 */
296 final static int INTERNAL = 2;
297
298 /**
299 * One of the possible values for this connection's type. <p>
300 *
301 * This value indicates a network <code>Connection</code> to a
302 * {@link org.hsqldb.Server Server} mode <code>Database</code>,
303 * using native hsqldb protocol. <p>
304 *
305 *
306 */
307 final static int HSQLDB = 3;
308
309 /**
310 * The type of this connection: {@link #STANDALONE STANDALONE},
311 * {@link #HSQLDB HSQLDB}, {@link #HTTP HTTP}, or {@link
312 * #INTERNAL INTERNAL}. <p>
313 */
314 private int iType;
315
316 // ----------------- In-process Database Connection Attributes -------------
317
318 /**
319 * This connection's in-process {@link Database Database}. <p>
320 *
321 * This attribute is used only for {@link #STANDALONE STANDALONE}
322 * or {@link #INTERNAL INTERNAL} type connections. <p>
323 *
324 *
325 */
326 Database dDatabase;
327
328 /**
329 * This connection's corresponding in-process {@link
330 * Session Session}.<p>
331 *
332 * This attribute is used only for {@link #STANDALONE STANDALONE}
333 * or {@link #INTERNAL INTERNAL} type connections. <p>
334 */
335 Session cSession;
336
337 /**
338 * A map from database names to open in-process {@link Database
339 * Database} instances. <p>
340 *
341 * This attribute is used to track and close open in-process
342 * <code>Database</code> instances, when it is detected that they
343 * no longer have any open connections. <p>
344 */
345 private static Hashtable tDatabase = new Hashtable();
346
347 /**
348 * A map from each open in-process {@link Database Database} to a
349 * count of its open connections. <p>
350 *
351 * This attribute is used to track and close open in-process
352 * <code>Database</code> instances, when it is detected that they
353 * no longer have any open connections. <p>
354 *
355 *
356 */
357 private static Hashtable iUsageCount = new Hashtable();
358
359 // ---------------- HSQLDB Protocol Network Connection Attributes ------------
360
361 /**
362 * The network <code>Socket</code> used communicate with this
363 * connection's {@link Database Database}. <p>
364 *
365 * This attribute is used only for {@link #HSQLDB HSQLDB} type
366 * connections. <p>
367 */
368 Socket sSocket;
369
370 /**
371 * The stream used to send requests to this connection's {@link
372 * Database Database}. <p>
373 *
374 * This attribute is used only for {@link #HSQLDB HSQLDB} type
375 * connections. <p>
376 */
377 DataOutputStream dOutput;
378
379 /**
380 * The stream used to receive results from this connection's
381 * {@link Database Database}. <p>
382 *
383 * This attribute is used only for {@link #HSQLDB HSQLDB} type
384 * connections. <p>
385 */
386 DataInputStream dInput;
387
388 /**
389 * Used when no port is explicitly specified in the url for a
390 * network <code>Connection</code> of type {@link #HSQLDB
391 * HSQLDB}. <p>
392 *
393 * This value is used as the port number for network connections
394 * to {@link Server Server} mode databases, when no port number
395 * is explictly specified in the connection url. <p>
396 *
397 * In the standard distribution, this will always be <code><b>9001</b>
398 * </code>.
399 */
400 public final static int DEFAULT_HSQLDB_PORT = 9001;
401
402 // ---------------- HTTP Protocol Network Connection Attributes -------------
403
404 /**
405 * The http url of this connection's {@link WebServer WebServer}
406 * mode {@link Database Database}, when this connection is of
407 * type {@link #HTTP HTTP}. <p>
408 *
409 *
410 */
411 private String sConnect;
412
413 /**
414 * The logon name for a connection to a {@link WebServer
415 * WebServer} mode <code>Database</code>. <p>
416 *
417 * This is the user name that this connection uses to log on to
418 * its <code>Database</code>, when this connection is of type
419 * {@link #HTTP HTTP}. <p>
420 *
421 *
422 */
423 private String sUser;
424
425 /**
426 * The password this connection uses to log on to its {@link
427 * WebServer WebServer} mode <code>Database</code>, when this
428 * connection is of type {@link #HTTP HTTP}. <p>
429 *
430 *
431 */
432 private String sPassword;
433
434 /**
435 * The encoding used to communicate with a {@link WebServer
436 * WebServer} mode {@link Database Database}, when this
437 * connection is of type {@link #HTTP HTTP}. <p>
438 *
439 * In the standard distribution, this will always be
440 * <code class="JavaStringLiteral">"8859_1"</code>
441 */
442 final static String ENCODING = "8859_1";
443
444 // ----------------------------------- JDBC 1 -------------------------------
445
446 /**
447 * <!-- start generic documentation -->
448 * Creates a <code>Statement</code>
449 * object for sending SQL statements to the database. SQL
450 * statements without parameters are normally executed using
451 * <code>Statement</code> objects. If the same SQL statement is
452 * executed many times, it may be more efficient to use a
453 * <code>PreparedStatement</code> object.<p>
454 *
455 * Result sets created using the returned <code>Statement</code>
456 * object will by default be type <code>TYPE_FORWARD_ONLY</code>
457 * and have a concurrency level of <code>CONCUR_READ_ONLY</code>.<p>
458 *
459 * <!-- end generic documentation -->
460 * <!-- start release-specific documentation -->
461 * <span class="ReleaseSpecificDocumentation">
462 * <b>HSQLDB-Specific Information:</b> <p>
463 *
464 * The standard java.sql API documentation above suggests that if
465 * the same SQL statement is executed many times, it may be more
466 * efficient to use a <code>PreparedStatement</code> object. As
467 * of HSQLDB 1.7.0, this is still not the case. However, this
468 * feature <I>is</I> slated to be part of the HSQLDB 1.7.x
469 * series. <p>
470 *
471 * Up to 1.6.1, HSQLDB supported <code>TYPE_FORWARD_ONLY</code> -
472 * <code>CONCUR_READ_ONLY</code> results only, so <code>ResultSet</code>
473 * objects created using the returned <code>Statement</code>
474 * object would <I>always</I> be type <code>TYPE_FORWARD_ONLY</code>
475 * with <code>CONCUR_READ_ONLY</code> concurrency. <p>
476 *
477 * Starting with 1.7.0, HSQLDB also supports
478 * <code>TYPE_SCROLL_INSENSITIVE</code> results. <p>
479 *
480 * <b>Notes:</b> <p>
481 *
482 * Up to 1.6.1, calling this method returned <code>null</code> if the
483 * connection was already closed. This was possibly counter-intuitive
484 * to the expectation that an exception would be thrown for
485 * closed connections. Starting with 1.7.0. the behaviour is to throw a
486 * <code>SQLException</code> if the connection is closed. <p>
487 *
488 * </span> <!-- end release-specific documentation -->
489 *
490 * @return a new default Statement object
491 * @throws SQLException if a database access error occurs<p>
492 * @see #createStatement(int,int)
493 * @see #createStatement(int,int,int)
494 */
495 public Statement createStatement() throws SQLException {
496
497 if (Trace.TRACE) {
498 Trace.trace();
499 }
500
501 checkClosed();
502
503 return new jdbcStatement(this);
504 }
505
506 /**
507 * <!-- start generic documentation -->
508 * Creates a <code>PreparedStatement</code>
509 * object for sending parameterized SQL statements to the
510 * database. <p>
511 *
512 * A SQL statement with or without IN parameters can be
513 * pre-compiled and stored in a <code>PreparedStatement</code>
514 * object. This object can then be used to efficiently execute
515 * this statement multiple times. <p>
516 *
517 * <B>Note:</B> This method is optimized for handling parametric
518 * SQL statements that benefit from precompilation. If the driver
519 * supports precompilation, the method <code>prepareStatement</code>
520 * will send the statement to the database for precompilation.
521 * Some drivers may not support precompilation. In this case, the
522 * statement may not be sent to the database until the
523 * <code>PreparedStatement</code> object is executed. This has no
524 * direct effect on users; however, it does affect which methods
525 * throw certain <code>SQLException</code> objects.<p>
526 *
527 * Result sets created using the returned <code>PreparedStatement</code>
528 * object will by default be type <code>TYPE_FORWARD_ONLY</code>
529 * and have a concurrency level of <code>CONCUR_READ_ONLY</code>.<p>
530 *
531 * <!-- end generic documentation -->
532 * <!-- start release-specific documentation -->
533 * <span class="ReleaseSpecificDocumentation">
534 * <b>HSQLDB-Specific Information:</b> <p>
535 *
536 * The standard java.sql API documentation above suggests that if
537 * the same SQL statement is executed many times, it may be more
538 * efficient to use a <code>PreparedStatement</code> object. As
539 * of HSQLDB 1.7.0, this is still not the case. Rather, the
540 * statement is stored on the client and is not sent to the
541 * database until the <code>PreparedStatement</code> object is
542 * executed. However, precompilation on the database <I>is</I> a
543 * feature slated to be part of the 1.7.x series. <p>
544 *
545 * Up to 1.6.1, HSQLDB supported <code>TYPE_FORWARD_ONLY</code> -
546 * <code>CONCUR_READ_ONLY</code> results only, so <code>ResultSet</code>
547 * objects created using the returned <code>PreparedStatement</code>
548 * object would <I>always</I> be type <code>TYPE_FORWARD_ONLY</code>
549 * with <code>CONCUR_READ_ONLY</code> concurrency. <p>
550 *
551 * Starting with 1.7.0, HSQLDB also supports
552 * <code>TYPE_SCROLL_INSENSITIVE</code> results. <p>
553 *
554 * <b>Notes:</b> <p>
555 *
556 * Up to 1.6.1, calling this method returned <code>null</code> if the
557 * connection was already closed. This was possibly counter-intuitive
558 * to the expectation that an exception would be thrown for
559 * closed connections. Starting with 1.7.0. the behaviour is to throw a
560 * <code>SQLException</code> if the connection is closed. <p>
561 *
562 * </span> <!-- end release-specific documentation -->
563 *
564 * @param sql an SQL statement that may contain one or more '?'
565 * IN parameter placeholders
566 * @return a new default <code>PreparedStatement</code> object
567 * containing the pre-compiled SQL statement
568 * @exception SQLException if a database access error occurs <p>
569 * @see #prepareStatement(String,int,int)
570 */
571 public PreparedStatement prepareStatement(String sql)
572 throws SQLException {
573
574 if (Trace.TRACE) {
575 Trace.trace(sql);
576 }
577
578 checkClosed();
579
580 return new jdbcPreparedStatement(this, sql);
581 }
582
583 /**
584 * <!-- start generic documentation -->
585 * Creates a <code>CallableStatement</code>
586 * object for calling database stored procedures. The
587 * <code>CallableStatement</code> object provides methods for setting up
588 * its IN and OUT parameters, and methods for executing the call to a
589 * stored procedure. <p>
590 *
591 * <b>Note:</b> This method is optimized for handling stored
592 * procedure call statements. Some drivers may send the call
593 * statement to the database when the method <code>prepareCall</code>
594 * is done; others may wait until the <code>CallableStatement</code>
595 * object is executed. This has no direct effect on users;
596 * however, it does affect which method throws certain
597 * SQLExceptions. <p>
598 *
599 * Result sets created using the returned <code>CallableStatement</code>
600 * object will by default be type <code>TYPE_FORWARD_ONLY</code>
601 * and have a concurrency level of <code>CONCUR_READ_ONLY</code>.<p>
602 *
603 * <!-- end generic documentation -->
604 * <!-- start release-specific documentation -->
605 * <span class="ReleaseSpecificDocumentation">
606 * <b>HSQLDB-Specific Information:</b> <p>
607 *
608 * The standard java.sql API documentation above suggests that if
609 * the same stored procedure is executed many times, it may be
610 * more efficient to use a <code>CallableStatement</code> object.
611 * As of HSQLDB 1.7.0, this is still not the case. Rather, the
612 * statement is stored on the client and is not sent to the
613 * database until the <code>CallableStatement</code> object is
614 * executed. However, protocol optimizations and statement
615 * precompilation on the database for optimization of stored
616 * procedure execution <I>are</I> a features slated to be part of
617 * the 1.7.x series. <p>
618 *
619 * Up to and including 1.7.1, HSQLDB supports only the default
620 * <code>TYPE_FORWARD_ONLY</code> - <code>CONCUR_READ_ONLY</code> for
621 * results obtained from <code>CallableStatement</code> objects. <p>
622 *
623 * <B>Notes:</B> <p>
624 *
625 * Up to 1.6.1, calling this method returned <code>null</code> if the
626 * connection was already closed. This was possibly counter-intuitive
627 * to the expectation that an exception would be thrown for
628 * closed connections. Starting with 1.7.0. the behaviour is to throw
629 * a <code>SQLException</code> if the connection is closed.<p>
630 *
631 * Up to and including 1.7.1, each HSQLDB stored procedure returns
632 * only a single value wrapped in a <code>ResultSet</code> object. That
633 * is, HSQLDB stored procedures act very much like SQL functions
634 * and can actually always be used in such a capacity. As such,
635 * there is really no point in supporting anything but
636 * <code>TYPE_FORWARD_ONLY</code>, since the result obtained by
637 * executing a <code>CallableStatement</code> object has
638 * always just one column and one row. Be aware that this
639 * behaviour will change in HSQLDB 1.7.1, in that support will be
640 * added for Java stored procedures that return multi-column,
641 * multi-row results. At that point, support will be added for
642 * <code>CallableStatement</code> objects that return
643 * <code>TYPE_SCROLL_INSENSITIVE</code> <code>ResultSet</code>
644 * objects. <p>
645 *
646 * New to 1.7.0, HSQLDB now allows calling <code>void</code> Java
647 * methods as SQL functions and stored procedures, the result being
648 * a SQL <code>NULL</code> value or a result with one column and one
649 * row whose single field is the SQL <code>NULL</code> value,
650 * respectiviely. Previously, calling such Java methods
651 * in either context resulted in throwing a <CODE>SQLException</CODE>.
652 *
653 * Finally, up to and including 1.7.1, the returned
654 * <code>CallableStatement</code> object does not support any
655 * getXXX methods. That is, HSQLDB stored procedures do not
656 * support <CODE>OUT</CODE> or <CODE>IN OUT</CODE> parameters. This
657 * behaviour <I>may</I> change at some point in the 1.7.x series, but
658 * no decisions have yet been made. <p>
659 *
660 * </span> <!-- end release-specific documentation -->
661 *
662 * @param sql a String object that is the SQL statement to be
663 * sent to the database; may contain one or more ?
664 * parameters. <p>
665 *
666 * <B>Note:</B> Typically the SQL statement is a JDBC
667 * function call escape string.
668 * @return a new default <code>CallableStatement</code> object
669 * containing the pre-compiled SQL statement
670 * @exception SQLException if a database access error occurs <p>
671 * @see #prepareCall(String,int,int)
672 */
673 public CallableStatement prepareCall(String sql) throws SQLException {
674
675 if (Trace.TRACE) {
676 Trace.trace(sql);
677 }
678
679 checkClosed();
680
681 return new jdbcPreparedStatement(this, sql);
682 }
683
684 /**
685 * <!-- start generic documentation -->
686 * Converts the given SQL statement
687 * into the system's native SQL grammar. A driver may convert the
688 * JDBC SQL grammar into its system's native SQL grammar prior to
689 * sending it. This method returns the native form of the
690 * statement that the driver would have sent. <p>
691 *
692 * <!-- end generic documentation -->
693 * <!-- start release-specific documentation -->
694 * <span class="ReleaseSpecificDocumentation">
695 * <b>HSQLDB-Specific Information:</b> <p>
696 *
697 * Up to and including 1.7.1, HSQLDB converts the JDBC SQL
698 * grammar into the system's native SQL grammar prior to sending
699 * it; this method returns the native form of the statement that
700 * the driver would send in place of client-specified JDBC SQL
701 * grammar. <p>
702 *
703 * </span> <!-- end release-specific documentation -->
704 *
705 * @param sql a SQL statement that may contain one or more '?'
706 * parameter placeholders
707 * @return the native form of this statement
708 * @throws SQLException if a database access error occurs <p>
709 */
710 public String nativeSQL(String sql) throws SQLException {
711
712 checkClosed();
713
714 if (sql.indexOf('{') == -1) {
715 return sql;
716 }
717
718 char s[] = sql.toCharArray();
719 boolean changed = false;
720 int state = 0;
721 int len = s.length;
722
723 for (int i = 0; i < len; i++) {
724 char c = s[i];
725
726 switch (state) {
727
728 case 0 : // normal
729 if (c == '\'') {
730 state = 1;
731 } else if (c == '"') {
732 state = 2;
733 } else if (c == '{') {
734 s[i] = ' ';
735 changed = true;
736
737 String sub = sql.substring(i + 1).toUpperCase();
738
739 if (sub.startsWith("?=")) {
740 i += 2;
741 } else if (sub.startsWith("CALL")) {
742 i += 4;
743 } else if (sub.startsWith("ESCAPE")) {
744 i += 6;
745 }
746
747 state = 3;
748 }
749 break;
750
751 case 1 : // inside ' '
752 case 5 : // inside { } and ' '
753 if (c == '\'') {
754 state -= 1;
755 }
756 break;
757
758 case 2 : // inside " "
759 case 6 : // inside { } and " "
760 if (c == '"') {
761 state -= 2;
762 }
763 break;
764
765 case 3 : // inside { } before whitespace
766 if (c == ' ') {
767 state = 4;
768 } else {
769 s[i] = ' ';
770 changed = true;
771 }
772 break;
773
774 case 4 : // inside { } after whitespace
775 if (c == '\'') {
776 state = 5;
777 } else if (c == '"') {
778 state = 6;
779 } else if (c == '}') {
780 s[i] = ' ';
781 changed = true;
782 state = 0;
783 }
784 }
785 }
786
787 if (changed) {
788 sql = new String(s);
789
790 if (Trace.TRACE) {
791 Trace.trace(s + " > " + sql);
792 }
793 }
794
795 return sql;
796 }
797
798 /**
799 * <!-- start generic documentation -->
800 * Sets this connection's auto-commit mode to the given state.
801 * If a connection is in auto-commit mode, then all its SQL
802 * statements will be executed and committed as individual transactions.
803 * Otherwise, its SQL statements are grouped into transactions that
804 * are terminated by a call to either the method <code>commit</code> or
805 * the method <code>rollback</code>. By default, new connections are
806 * in auto-commit mode. <p>
807 *
808 * The commit occurs when the statement completes or the next
809 * execute occurs, whichever comes first. In the case of
810 * statements returning a <code>ResultSet</code> object, the
811 * statement completes when the last row of the <code>ResultSet</code>
812 * object has been retrieved or the <code>ResultSet</code> object
813 * has been closed. In advanced cases, a single statement may
814 * return multiple results as well as output parameter values. In
815 * these cases, the commit occurs when all results and output
816 * parameter values have been retrieved. <p>
817 *
818 * <B>NOTE:</B> If this method is called during a transaction,
819 * the transaction is committed. <p>
820 *
821 * <!-- end generic documentation -->
822 * <!-- start release-specific documentation -->
823 * <span class="ReleaseSpecificDocumentation">
824 * <b>HSQLDB-Specific Information:</b> <p>
825 *
826 * Up to and including HSQLDB 1.7.0, <p>
827 *
828 *
829 * <OL>
830 * <LI> All rows of a result set are retrieved internally <I>
831 * before</I> the first row can actually be fetched.<br>
832 * Therefore, a statement can be considered complete as soon as
833 * any XXXStatement.executeXXX method returns. </LI>
834 * <LI> Multiple result sets and output parameters are not yet
835 * supported. </LI>
836 * </OL>
837 * <p>
838 *
839 * (boucherb@users) </span> <!-- end release-specific
840 * documentation -->
841 *
842 * @param autoCommit <code>true</code> to enable auto-commit
843 * mode; <code>false</code> to disable it
844 * @exception SQLException if a database access error occurs
845 * @see #getAutoCommit
846 */
847 public void setAutoCommit(boolean autoCommit) throws SQLException {
848 execute("SET AUTOCOMMIT " + (autoCommit ? "TRUE"
849 : "FALSE"));
850 }
851
852 /**
853 * Gets the current auto-commit state.
854 *
855 * @return the current state of auto-commit mode
856 * @exception SQLException Description of the Exception
857 * @see #setAutoCommit
858 */
859 public boolean getAutoCommit() throws SQLException {
860
861 // comment
862 // Test properly if new code works correctly
863 // fredt@users 20020510
864 if (Trace.TRACE) {
865 Trace.trace();
866 }
867
868 if (iType == INTERNAL || iType == STANDALONE) {
869 return cSession.getAutoCommit();
870 } else {
871 try {
872 ResultSet rs =
873 execute("call \"org.hsqldb.Library.getAutoCommit\"()");
874
875 rs.next();
876
877 return rs.getBoolean(1);
878 } catch (SQLException e) {
879 this.close();
880
881 throw Trace.error(Trace.CONNECTION_IS_BROKEN);
882 }
883 }
884 }
885
886 /**
887 * <!-- start generic documentation -->
888 * Makes all changes made since the
889 * previous commit/rollback permanent and releases any database
890 * locks currently held by the Connection. This method should be
891 * used only when auto-commit mode has been disabled. <p>
892 *
893 * <!-- end generic documentation -->
894 * <!-- start release-specific documentation -->
895 * <span class="ReleaseSpecificDocumentation">
896 * <b>HSQLDB-Specific Information:</b> <p>
897 *
898 * As of HSQLDB 1.7.0, SQL Savepoints are supported. As such,
899 * successfully calling this method now also removes all
900 * Savepoints from this connection's {@link Session Session}. <p>
901 *
902 * Up to 1.6.1, HSQLDB did not support Savepoints in
903 * transactions, named or anonymous. <p>
904 *
905 * As of 1.7.0, HSQLDB supports an arbitrary number of named
906 * Savepoints per transaction and allows explicitly rolling back
907 * to any one of them. At this time, HSQLDB does not support
908 * anonymous Savepoints. However, this feature <i>is</i> slated
909 * for the 1.7.x series. <p>
910 *
911 * Also, JDBC 3 support for java.sql.Savepoint has not yet been
912 * implemented. At present, rather, the following SQL syntax must
913 * be used: <p>
914 *
915 * <code class="JavaCodeExample">
916 * SAVEPOINT savepoint_name1;<br>
917 * ... -- perform some work<br>
918 * SAVEPOINT savepoint_name2;<br>
919 * ...-- perform some work<br>
920 * ROLLABACK TO SAVEPOINT savepoint_name2<br>
921 * ...-- perform some work<br>
922 * ROLLABACK TO SAVEPOINT savepoint_name1; </code> <p>
923 *
924 * <B>Note:</B> If two or more Savepoints with the same name are
925 * performed during the same transaction, the latest one replaces
926 * the previous one, so that it is impossible to roll back to the
927 * previous one. </span> <p>
928 *
929 * <!-- end release-specific documentation -->
930 *
931 * @exception SQLException if a database access error occurs
932 * @see #setAutoCommit
933 */
934 public void commit() throws SQLException {
935 execute("COMMIT");
936 }
937
938 /**
939 * <!-- start generic documentation -->
940 * Drops all changes made since the
941 * previous commit/rollback and releases any database locks
942 * currently held by this Connection. This method should be used
943 * only when auto- commit has been disabled. <p>
944 *
945 * <!-- end generic documentation -->
946 * <!-- start release-specific documentation -->
947 * <span class="ReleaseSpecificDocumentation">
948 * <b>HSQLDB-Specific Information:</b> <p>
949 *
950 * As of HSQLDB 1.7.0, SQL Savepoints are supported. As such,
951 * successfully calling this method also removes all Savepoints
952 * from this <code>Connection</code>'s {@link Session Session}.
953 * <p>
954 *
955 * Up to 1.6.1, HSQLDB did not support Savepoints in
956 * transactions, named or anonymous. <p>
957 *
958 * As of 1.7.0, HSQLDB supports an arbitrary number of named
959 * Savepoints per transaction and allows explicitly rolling back
960 * to any one of them. At this time, HSQLDB does not support
961 * anonymous Savepoints. However, this feature <i>is</i> slated
962 * for the 1.7.x series. <p>
963 *
964 * Also, as of 1.7.0, JDBC 3 support for java.sql.Savepoint has
965 * not yet been implemented. At present, rather, the following
966 * SQL syntax must be used: <p>
967 *
968 * <code class="JavaCodeExample">
969 * SAVEPOINT savepoint_name1;<br>
970 * ...-- perform some work<br>
971 * SAVEPOINT savepoint_name2;<br>
972 * ...-- perform some work<br>
973 * ROLLABACK TO SAVEPOINT savepoint_name2<br>
974 * ...-- perform some work<br>
975 * ROLLABACK TO SAVEPOINT savepoint_name1; </code> <p>
976 *
977 * <code>Note:</code> If two or more Savepoints with the same
978 * name are performed during the same transaction, the latest one
979 * replaces the previous one, making it impossible to roll back
980 * to the previous one. </span> <p>
981 *
982 * <!-- end release-specific documentation -->
983 *
984 * @exception SQLException if a database access error occurs
985 * @see #setAutoCommit
986 */
987 public void rollback() throws SQLException {
988 execute("ROLLBACK");
989 }
990
991 /**
992 * <!-- start generic documentation -->
993 * Releases this <code>Connection</code>
994 * object's database and JDBC resources immediately instead of
995 * waiting for them to be automatically released.<p>
996 *
997 * Calling the method <code>close</code> on a <code>Connection</code>
998 * object that is already closed is a no-op. <p>
999 *
1000 * <B>Note:</B> A <code>Connection</code> object is automatically
1001 * closed when it is garbage collected. Certain fatal errors also
1002 * close a <code>Connection</code> object. <p>
1003 *
1004 * <!-- end generic documentation -->
1005 * <!-- start release-specific documentation -->
1006 * <span class="ReleaseSpecificDocumentation">
1007 * <b>HSQLDB-Specific Information:</b> <p>
1008 *
1009 * In a future release, <code>INTERNAL</code> <code>Connection</code>
1010 * objects may not be closable from JDBC client code, and disconnect
1011 * statements issued on <code>INTERNAL</code> <code>Connection</code>
1012 * objects may be ignored. <p>
1013 *
1014 * For HSQLDB developers not involved with writing database
1015 * internals, this change will only apply to connections obtained
1016 * automatically from the database as the first parameter to
1017 * stored procedures and SQL functions. This is mainly an issue
1018 * to developers writing custom SQL function and stored procedure
1019 * libraries for HSQLDB. As we anticipate this change, it is
1020 * recommended that SQL function and stored procedure code avoid
1021 * depending on closing or issuing a disconnect on a connection
1022 * obtained in this manner. <p>
1023 *
1024 * </span> <!-- end release-specific documentation -->
1025 *
1026 * @exception SQLException if a database access error occurs
1027 */
1028 public void close() throws SQLException {
1029
1030 if (Trace.TRACE) {
1031 Trace.trace();
1032 }
1033
1034 if (iType == INTERNAL) {
1035 return;
1036 }
1037
1038 if (bClosed) {
1039 return;
1040 }
1041
1042 // FIXME:
1043 // closeStandalone() should only get called for STANDALONE
1044 // calling close on an internal connection should do nothing
1045 // Internal connections should not execute DISCONNECT or set
1046 // bClosed true
1047 // Only one instance of internal connection should exist for
1048 // each Session, and it should be open for the life of
1049 // its Session
1050 // boucherb@users 20020409
1051// fredt - patch 1.7.1 - implemented the above
1052 if (iType == STANDALONE) {
1053 closeStandalone();
1054 } else {
1055 execute("DISCONNECT");
1056 }
1057
1058 bClosed = true;
1059 }
1060
1061 /**
1062 * Tests to see if a Connection is closed.
1063 *
1064 * @return true if the connection is closed; false if it's still
1065 * open
1066 */
1067 public boolean isClosed() {
1068
1069 if (Trace.TRACE) {
1070 Trace.trace();
1071 }
1072
1073 return bClosed;
1074 }
1075
1076 /**
1077 * <!-- start generic documentation -->
1078 * Gets the metadata regarding this connection's database.
1079 * A Connection's database is able to provide information describing
1080 * its tables, its supported SQL grammar, its stored procedures,
1081 * the capabilities of this connection, and so on. This information
1082 * is made available through a <code>DatabaseMetaData</code> object. <p>
1083 *
1084 * <!-- end generic documentation -->
1085 * <!-- start release-specific documentation -->
1086 * <span class="ReleaseSpecificDocumentation">
1087 * <b>HSQLDB-Specific Information:</b> <p>
1088 *
1089 * Up to and including 1.7.1, HSQLDB does not provide accurate
1090 * results for the full range of <code>DatabaseMetaData</code>
1091 * methods returning <code>ResultSet</code>. Some of these
1092 * methods may always return empty result sets, even though they
1093 * should contain information. Other methods may not accurately
1094 * reflect all of the MetaData for the category they report on.
1095 * Also, some methods may ignore the filters provided as
1096 * parameters, returning an unfiltered result each time. <p>
1097 *
1098 * As of version 1.7.1, the only completely accurate
1099 * <code>DatabaseMetaData</code>
1100 * methods returning <code>ResultSet</code> are {@link
1101 * jdbcDatabaseMetaData#getTables getTables},
1102 * {@link jdbcDatabaseMetaData#getColumns getColumns},
1103 * {@link jdbcDatabaseMetaData#getColumns getPrimaryKeys},
1104 * and {@link jdbcDatabaseMetaData#getIndexInfo getIndexInfo}.
1105 * Also, the
1106 * majority of methods returning <code>ResultSet</code> throw a
1107 * <code>SQLException</code> when accessed by a non-admin user.
1108 * In order to provide non-admin users access to these methods,
1109 * an admin user must explicitly grant SELECT to such users or to
1110 * the PUBLIC user on each HSQLDB system table corresponding to a
1111 * DatabaseMetaData method that returns <code>ResultSet</code>.
1112 * For example, to provide access to {@link
1113 * jdbcDatabaseMetaData#getTables getTables} to all users, the
1114 * following must be issued by an admin user:<p>
1115 *
1116 * <code class = "JavaCodeExample">
1117 * GRANT SELECT ON SYSTEM_TABLES TO PUBLIC
1118 * </code> <p>
1119 *
1120 * Care should be taken when making such grants, however, since
1121 * HSQLDB makes no attempt to filter such information, based on
1122 * the grants of the accessing user. That is, in the example
1123 * above, getTables will return information about all tables
1124 * (except system tables, which are never listed in MetaData),
1125 * regardless of whether the calling user has any rights on any
1126 * of the tables. <p>
1127 *
1128 * HSQLDB 1.7.1 will provide the option of installing a full and
1129 * accurate <code>DatabaseMetaData</code> implementation that is
1130 * accessible to all database users, regardless of admin status.
1131 * In that implementation, <code>DatabaseMetaData</code> methods
1132 * returning <code>ResultSet</code> will yield results that have
1133 * been automatically pre-filtered to omit entries to which the
1134 * connected user has not been granted access, regardless of the
1135 * filter parameters specified to those methods. That is,
1136 * supplied filter parameters will only further restrict results
1137 * that already comply with the security set up by
1138 * administration, and will never give greater access than has
1139 * been granted. Also in that implementation, full MetaData will
1140 * be reported to all users about all system tables, unless
1141 * SELECT on any system table providing <code>DatabaseMetaData</code>
1142 * is specifically revoked from PUBLIC and not explicitly granted
1143 * to each user. <p>
1144 *
1145 * </span> <!-- end release-specific documentation -->
1146 *
1147 * @return a DatabaseMetaData object for this Connection
1148 * @see jdbcDatabaseMetaData
1149 */
1150 public DatabaseMetaData getMetaData() {
1151
1152 if (Trace.TRACE) {
1153 Trace.trace();
1154 }
1155
1156 return new jdbcDatabaseMetaData(this);
1157 }
1158
1159 /**
1160 * <!-- start generic documentation -->
1161 * Puts this connection in read-only mode as a hint to enable
1162 * database optimizations. <p>
1163 *
1164 * <B>Note:</B> This method should not be called while in the
1165 * middle of a transaction. <p>
1166 *
1167 * <!-- end generic documentation -->
1168 * <!-- start release-specific documentation -->
1169 * <span class="ReleaseSpecificDocumentation">
1170 * <b>HSQLDB-Specific Information:</b> <p>
1171 *
1172 * Up to and including 1.7.1, HSQLDB will commit the current
1173 * transaction automatically when this method is called. <p>
1174 *
1175 * Additionally, HSQLDB provides a way to put a whole database in
1176 * read-only mode. This is done by manually adding the line
1177 * 'readonly=true' to the database's .properties file while the
1178 * database is offline. Upon restart, all connections will be
1179 * readonly, since the entire database will be readonly. To take
1180 * a database out of readonly mode, simply take the database
1181 * offline and remove the line 'readonly=true' from the
1182 * database's .properties file. Upon restart, the database will
1183 * be in regular (read-write) mode. <p>
1184 *
1185 * When a database is put in readonly mode, its files are opened
1186 * in readonly mode, making it possible to create CDROM-based
1187 * readonly databases. To create a CDROM-based readonly database
1188 * that has CACHED tables and whose .data file is suspected of
1189 * being highly fragmented, it is recommended that the database
1190 * first be SHUTDOWN COMPACTed, taken off-line, restarted,
1191 * SHUTDOWN and taken off-line again before copying the database
1192 * files to CDROM. This will reduce the space required and may
1193 * improve access times against the .data file which holds the
1194 * CACHED table data. <p>
1195 *
1196 * </span> <!-- end release-specific documentation -->
1197 *
1198 * @param readonly The new readOnly value
1199 * @exception SQLException if a database access error occurs
1200 */
1201 public void setReadOnly(boolean readonly) throws SQLException {
1202 execute("SET READONLY " + (readonly ? "TRUE"
1203 : "FALSE"));
1204 }
1205
1206 /**
1207 * Tests to see if the connection is in read-only mode.
1208 *
1209 * @return true if connection is read-only and false otherwise
1210 * @exception SQLException if a database access error occurs
1211 */
1212 public boolean isReadOnly() throws SQLException {
1213
1214 String s = "SELECT * FROM SYSTEM_CONNECTIONINFO WHERE KEY='READONLY'";
1215 ResultSet r = execute(s);
1216
1217 r.next();
1218
1219 return r.getString(2).equals("TRUE");
1220 }
1221
1222 /**
1223 * <!-- start generic documentation -->
1224 * Sets a catalog name in order to
1225 * select a subspace of this Connection's database in which to
1226 * work. <p>
1227 *
1228 * <!-- end generic documentation -->
1229 * <!-- start release-specific documentation -->
1230 * <span class="ReleaseSpecificDocumentation">
1231 * <b>HSQLDB-Specific Information:</b> <p>
1232 *
1233 * HSQLDB does not yet support catalogs and simply ignores this
1234 * request. <p>
1235 * </span>
1236 * <!-- end release-specific documentation -->
1237 *
1238 * @param catalog the name of a catalog (subspace in this
1239 * Connection object's database) in which to work (Ignored)
1240 * @throws SQLException if a database access error occurs <p>
1241 */
1242 public void setCatalog(String catalog) throws SQLException {
1243
1244 if (Trace.TRACE) {
1245 Trace.trace(catalog);
1246 }
1247 }
1248
1249 /**
1250 * <!-- start generic documentation -->
1251 * Returns the Connection's current catalog name. <p>
1252 *
1253 * <!-- end generic documentation -->
1254 * <!-- start release-specific documentation -->
1255 * <span class="ReleaseSpecificDocumentation">
1256 * <b>HSQLDB-Specific Information:</b> <p>
1257 *
1258 * HSQLDB does not yet support catalogs and always returns null.
1259 * <p>
1260 *
1261 * </span> <!-- end release-specific documentation -->
1262 *
1263 * @return the current catalog name or null <p>
1264 *
1265 * For HSQLDB, this is always null.
1266 * @exception SQLException Description of the Exception
1267 */
1268 public String getCatalog() throws SQLException {
1269
1270 if (Trace.TRACE) {
1271 Trace.trace();
1272 }
1273
1274 checkClosed();
1275
1276 return null;
1277 }
1278
1279 /**
1280 * <!-- start generic documentation -->
1281 * Attempts to change the transaction isolation level for this
1282 * <code>Connection</code> object to the one given. The constants
1283 * defined in the interface <code>Connection</code> are the
1284 * possible transaction isolation levels. <p>
1285 *
1286 * <B>Note:</B> If this method is called during a transaction,
1287 * the result is implementation-defined. <p>
1288 *
1289 * <!-- end generic documentation -->
1290 * <!-- start release-specific documentation -->
1291 * <span class="ReleaseSpecificDocumentation">
1292 * <b>HSQLDB-Specific Information:</b> <p>
1293 *
1294 * Up to and including 1.7.1, HSQLDB supports only
1295 * <code>Connection.TRANSACTION_READ_UNCOMMITTED</code>. <p>
1296 *
1297 * </span> <!-- end release-specific documentation -->
1298 *
1299 * @param level one of the following <code>Connection</code>
1300 * constants: <code>Connection.TRANSACTION_READ_UNCOMMITTED</code>
1301 * , <code>Connection.TRANSACTION_READ_COMMITTED</code>,
1302 * <code>Connection.TRANSACTION_REPEATABLE_READ</code>, or
1303 * <code>Connection.TRANSACTION_SERIALIZABLE</code>. (Note
1304 * that <code>Connection.TRANSACTION_NONE</code> cannot be
1305 * used because it specifies that transactions are not
1306 * supported.)
1307 * @exception SQLException if a database access error occurs or
1308 * the given parameter is not one of the <code>Connection</code>
1309 * constants <p>
1310 * @see jdbcDatabaseMetaData#supportsTransactionIsolationLevel
1311 * @see #getTransactionIsolation
1312 */
1313 public void setTransactionIsolation(int level) throws SQLException {
1314
1315 if (Trace.TRACE) {
1316 Trace.trace(level);
1317 }
1318
1319 if (level != Connection.TRANSACTION_READ_UNCOMMITTED) {
1320 throw Trace.error(Trace.FUNCTION_NOT_SUPPORTED);
1321 }
1322
1323 checkClosed();
1324 }
1325
1326 /**
1327 * <!-- start generic documentation -->
1328 * Retrieves this <code>Connection</code>
1329 * object's current transaction isolation level. <p>
1330 *
1331 * <!-- end generic documentation -->
1332 * <!-- start release-specific documentation -->
1333 * <span class="ReleaseSpecificDocumentation">
1334 * <b>HSQLDB-Specific Information:</b> <p>
1335 *
1336 * HSQLDB always returns
1337 * <CODE>Connection.TRANSACTION_READ_UNCOMMITED</CODE>. <p>
1338 *
1339 * </span> <!-- end release-specific documentation -->
1340 *
1341 * @return the current transaction isolation level, which will be
1342 * one of the following constants:
1343 * <code>Connection.TRANSACTION_READ_UNCOMMITTED</code>
1344 * , <code>Connection.TRANSACTION_READ_COMMITTED</code>,
1345 * <code>Connection.TRANSACTION_REPEATABLE_READ</code>,
1346 * <code>Connection.TRANSACTION_SERIALIZABLE</code>, or
1347 * <code>Connection.TRANSACTION_NONE</code> <p>
1348 *
1349 * Up to and including 1.7.1, TRANSACTION_READ_UNCOMMITTED is
1350 * always returned
1351 * @exception SQLException if a database access error occurs <p>
1352 * @see jdbcDatabaseMetaData#supportsTransactionIsolationLevel
1353 * @see #setTransactionIsolation setTransactionIsolation
1354 */
1355 public int getTransactionIsolation() throws SQLException {
1356
1357 if (Trace.TRACE) {
1358 Trace.trace();
1359 }
1360
1361 checkClosed();
1362
1363 return Connection.TRANSACTION_READ_UNCOMMITTED;
1364 }
1365
1366 /**
1367 * <!-- start generic documentation -->
1368 * Retrieves the first warning reported by calls on this
1369 * <code>Connection</code> object. If there is more than one
1370 * warning, subsequent warnings will be chained to the first
1371 * one and can be retrieved by calling the method
1372 * <code>SQLWarning.getNextWarning</code> on the warning
1373 * that was retrieved previously. <p>
1374 *
1375 * This method may not be called on a closed connection; doing so
1376 * will cause an <code>SQLException</code> to be thrown. <p>
1377 *
1378 * <B>Note:</B> Subsequent warnings will be chained to this
1379 * SQLWarning. <p>
1380 *
1381 * <!-- end generic documentation -->
1382 * <!-- start release-specific documentation -->
1383 * <span class="ReleaseSpecificDocumentation">
1384 * <b>HSQLDB-Specific Information:</b> <p>
1385 *
1386 * Up to and including 1.7.1, HSQLDB never produces warnings,
1387 * always returns null.<p>
1388 *
1389 * </span> <!-- end release-specific documentation -->
1390 *
1391 * @return the first <code>SQLWarning</code> object or <code>null</code>
1392 * if there are none<p>
1393 * @exception SQLException if a database access error occurs or
1394 * this method is called on a closed connection <p>
1395 * @see SQLWarning
1396 */
1397 public SQLWarning getWarnings() throws SQLException {
1398
1399 if (Trace.TRACE) {
1400 Trace.trace();
1401 }
1402
1403 checkClosed();
1404
1405 return null;
1406 }
1407
1408 /**
1409 * An internal check for unsupported combinations of
1410 * <code>ResultSet</code> type and concurrency. <p>
1411 *
1412 * Up to and including HSQLDB 1.7.0, the only supported
1413 * combinations are type <code>TYPE_FORWARD_ONLY</code> or
1414 * <code>TYPE_SCROLL_INSENSITIVE</code>, combined with
1415 * concurrency <code>CONCUR_READ_ONLY</code>.
1416 *
1417 * @param type of <code>ResultSet</code>; one of
1418 * <code>ResultSet.TYPE_XXX</code>
1419 * @param concurrency of <code>ResultSet</code>; one of
1420 * <code>ResultSet.CONCUR_XXX</code>
1421 * @throws SQLException when the specified combination of type
1422 * and concurrency is not supported
1423 */
1424 static void checkTypeConcurrency(int type,
1425 int concurrency) throws SQLException {
1426
1427 if ((type != jdbcResultSet.TYPE_FORWARD_ONLY && type != jdbcResultSet
1428 .TYPE_SCROLL_INSENSITIVE) || concurrency != jdbcResultSet
1429 .CONCUR_READ_ONLY) {
1430 throw Trace.error(Trace.FUNCTION_NOT_SUPPORTED);
1431 }
1432 }
1433
1434 /**
1435 * An internal check for closed connections. <p>
1436 *
1437 * @throws SQLException when the connection is closed
1438 */
1439 void checkClosed() throws SQLException {
1440
1441 if (bClosed) {
1442 throw Trace.error(Trace.CONNECTION_IS_CLOSED);
1443 }
1444 }
1445
1446 /**
1447 * An internal method for removing a databas that has been shutdown
1448 *
1449 * @param database path/name of database to remove
1450 */
1451
1452 // bourcherb@users - 20020828 - patch 1.7.1 by boucherb@users
1453 static void removeDatabase(Database database) {
1454
1455 if (database == null) {
1456 return;
1457 }
1458
1459 tDatabase.remove(database.getName());
1460 iUsageCount.remove(database);
1461 }
1462
1463 /**
1464 * <!-- start generic documentation -->
1465 * Clears all warnings reported for this <code>Connection</code>
1466 * object. After a call to this method, the method
1467 * <code>getWarnings</code> returns null until
1468 * a new warning is reported for this Connection. <p>
1469 *
1470 * <!-- end generic documentation -->
1471 * <!-- start release-specific documentation -->
1472 * <span class="ReleaseSpecificDocumentation">
1473 * <b>HSQLDB-Specific Information:</b> <p>
1474 *
1475 * Up to and including HSQLDB 1.7.0, <CODE>SQLWarning</CODE> is not
1476 * supported, and calls to this method are simply ignored. <p>
1477 *
1478 * </span> <!-- end release-specific documentation -->
1479 *
1480 * @exception SQLException if a database access error occurs <p>
1481 */
1482 public void clearWarnings() throws SQLException {
1483
1484 if (Trace.TRACE) {
1485 Trace.trace();
1486 }
1487
1488 checkClosed();
1489 }
1490
1491 //--------------------------JDBC 2.0-----------------------------
1492
1493 /**
1494 * <!-- start generic documentation -->
1495 * Creates a <code>Statement</code> object that will generate
1496 * <code>ResultSet</code> objects with the given type and
1497 * concurrency. This method is the same as the
1498 * <code>createStatement</code> method above, but it allows the
1499 * default result set type and result set concurrency type to be
1500 * overridden. <p>
1501 *
1502 * <!-- end generic documentation -->
1503 * <!-- start release-specific documentation -->
1504 * <span class="ReleaseSpecificDocumentation">
1505 * <b>HSQLDB-Specific Information:</b> <p>
1506 *
1507 * Up to HSQLDB 1.6.1, support was provided only for type
1508 * <code>TYPE_FORWARD_ONLY</code>
1509 * and concurrency <code>CONCUR_READ_ONLY</code>. <p>
1510 *
1511 * Starting with HSQLDB 1.7.0, support is now provided for types
1512 * <code>TYPE_FORWARD_ONLY</code>, <I>and</I>
1513 * <code>TYPE_SCROLL_INSENSITIVE</code>,
1514 * with concurrency <code>CONCUR_READ_ONLY</code>. Specifying
1515 * any other values will throw a <CODE>SQLException</CODE>.<p>
1516 *
1517 * <B>Notes:</B> <p>
1518 *
1519 * Up to 1.6.1, calling this method returned <CODE>null</CODE> if the
1520 * connection was already closed and a supported combination of type and
1521 * concurrency was specified. This was possibly counter-intuitive
1522 * to the expectation that an exception would be thrown for
1523 * closed connections. Starting with 1.7.0. the behaviour is to throw a
1524 * <code>SQLException</code> if the connection is closed.<p>
1525 *
1526 * </span> <!-- end release-specific documentation -->
1527 *
1528 * @param type a result set type; one of
1529 * <code>ResultSet.TYPE_FORWARD_ONLY</code>,
1530 * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
1531 * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code> (not
1532 * supported)
1533 * @param concurrency a concurrency type; one of
1534 * <code>ResultSet.CONCUR_READ_ONLY</code>
1535 * or <code>ResultSet.CONCUR_UPDATABLE</code> (not supported)
1536 * @return a new <code>Statement</code> object that will, within
1537 * the release-specific documented limitations of support,
1538 * generate <code>ResultSet</code> objects with the given
1539 * type and concurrency
1540 * @exception SQLException if a database access error occurs or
1541 * the given parameters are not ResultSet constants
1542 * indicating a supported type and concurrency
1543 * @since JDK 1.2 (JDK 1.1.x developers: read the new overview
1544 * for jdbcConnection)
1545 */
1546 public Statement createStatement(int type,
1547 int concurrency) throws SQLException {
1548
1549 if (Trace.TRACE) {
1550