KickJava   Java API By Example, From Geeks To Geeks.

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


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.Connection JavaDoc;
35 import java.sql.DatabaseMetaData JavaDoc;
36 import java.sql.ResultSet JavaDoc;
37 import java.sql.SQLException JavaDoc;
38
39 import org.hsqldb.Column;
40 import org.hsqldb.Library;
41 import org.hsqldb.Trace;
42 import org.hsqldb.lib.StringUtil;
43 import org.hsqldb.persist.HsqlDatabaseProperties;
44
45 // fredt@users 20020320 - patch 1.7.0 - JDBC 2 support and error trapping
46
// JDBC 2 methods can now be called from jdk 1.1.x - see javadoc comments
47
// boucherb@users 20020509 - added "throws SQLException" to all methods where
48
// it was missing here but specified in the java.sql.DatabaseMetaData interface,
49
// updated generic documentation to JDK 1.4, and added JDBC3 methods and docs
50
// boucherb@users and fredt@users 20020409/20020505 extensive review and update
51
// of docs and behaviour to comply with previous and latest java.sql
52
// specification
53
// boucherb@users 2002-20030121 - extensive rewrite to support new
54
// 1.7.2 metadata features.
55
// boucherb@users 20040422 - doc 1.7.2 - javadoc updates toward 1.7.2 final
56
// boucherb@users 200404xx - misc changes
57
// fredt@users 20050505 - patch 1.8.0 - enforced JDBC rules for non-pattern params
58

59 /** Comprehensive information about the database as a whole.
60  * <P>
61  * This interface is implemented by driver vendors to let users know the
62  * capabilities of a Database Management System (DBMS) in combination with
63  * the driver based on JDBC<sup><font size=-2>TM</font></sup> technology
64  * ("JDBC driver") that is used with it. Different relational DBMSs often
65  * support different features, implement features in different ways, and use
66  * different data types. In addition, a driver may implement a feature on
67  * top of what the DBMS offers. Information returned by methods in this
68  * interface applies to the capabilities of a particular driver and a
69  * particular DBMS working together. Note that as used in this documentation,
70  * the term "database" is used generically to refer to both the driver and DBMS.
71  * <P>
72  * A user for this interface is commonly a tool that needs to discover how to
73  * deal with the underlying DBMS. This is especially true for applications
74  * that are intended to be used with more than one DBMS. For example, a tool
75  * might use the method <code>getTypeInfo</code> to find out what data types
76  * can be used in a <code>CREATE TABLE</code> statement. Or a user might call
77  * the method <code>supportsCorrelatedSubqueries</code> to see if it is possible
78  * to use a correlated subquery or <code>supportsBatchUpdates</code> to see if
79  * it is possible to use batch updates.
80  * <P>
81  * Some <code>DatabaseMetaData</code> methods return lists of information
82  * in the form of <code>ResultSet</code> objects. Regular <code>ResultSet</code>
83  * methods, such as <code>getString</code> and <code>getInt</code>, can be used
84  * to retrieve the data from these <code>ResultSet</code> objects. If a given
85  * form of metadata is not available, the <code>ResultSet</code> getter methods
86  * throw an <code>SQLException</code>.
87  * <P>
88  * Some <code>DatabaseMetaData</code> methods take arguments that are
89  * String patterns. These arguments all have names such as fooPattern.
90  * Within a pattern String, "%" means match any substring of 0 or more
91  * characters, and "_" means match any one character. Only metadata
92  * entries matching the search pattern are returned. If a search pattern
93  * argument is set to <code>null</code>, that argument's criterion will
94  * be dropped from the search.
95  * <P>
96  * A method that gets information about a feature that the driver does not
97  * support will throw an <code>SQLException</code>.
98  * In the case of methods that return a <code>ResultSet</code>
99  * object, either a <code>ResultSet</code> object (which may be empty) is
100  * returned or an <code>SQLException</code> is thrown.<p>
101  *
102  * <!-- start release-specific documentation -->
103  * <div class="ReleaseSpecificDocumentation">
104  * <h3>HSQLDB-Specific Information:</h3> <p>
105  *
106  * Starting with HSQLDB 1.7.2, an option is provided to allow alternate
107  * system table production implementations. In this distribution, there are
108  * three implementations whose behaviour ranges from producing no system
109  * tables at all to producing a richer and more complete body of information
110  * about an HSQLDB database than was previously available. The information
111  * provided through the default implementation is, unlike previous
112  * versions, accessible to all database users, regardless of admin status.
113  * This is now possible because the table content it produces for each
114  * user is pre-filtered, based on the user's access rights. That is, each
115  * system table now acts like a security-aware View.<p>
116  *
117  * The process of installing a system table production class is transparent and
118  * occurs dynamically at runtime during the opening sequence of a
119  * <code>Database</code> instance, in the newDatabaseInformation() factory
120  * method of the revised DatabaseInformation class, using the following
121  * steps: <p>
122  *
123  * <div class="GeneralExample">
124  * <ol>
125  * <li>If a class whose fully qualified name is org.hsqldb.DatabaseInformationFull
126  * can be found and it has an accesible constructor that takes an
127  * org.hsqldb.Database object as its single parameter, then an instance of
128  * that class is reflectively instantiated and is used by the database
129  * instance to produce its system tables. <p>
130  *
131  * <li>If 1.) fails, then the process is repeated, attempting to create an
132  * instance of org.hsqldb.DatabaseInformationMain (which provides just the
133  * core set of system tables required to service this class, but now does
134  * so in a more security aware and comprehensive fashion). <p>
135  *
136  * <li>If 2.) fails, then an instance of org.hsqldb.DatabaseInformation is
137  * installed (that, by default, produces no system tables, meaning that
138  * calls to all related methods in this class will fail, throwing an
139  * SQLException stating that a required system table is not found). <p>
140  *
141  * </ol>
142  * </div> <p>
143  *
144  * The process of searching for alternate implementations of database
145  * support classes, ending with the installation of a minimal but functional
146  * default will be refered to henceforth as <i>graceful degradation</i>.
147  * This process is advantageous in that it allows developers and administrators
148  * to easily choose packaging options, simply by adding to or deleting concerned
149  * classes from an HSQLDB installation, without worry over providing complex
150  * initialization properties or disrupting the core operation of the engine.
151  * In this particular context, <i>graceful degradation</i> allows easy choices
152  * regarding database metadata, spanning the range of full (design-time),
153  * custom-written, minimal (production-time) or <CODE>null</CODE>
154  * (space-constrained) system table production implementations. <p>
155  *
156  * In the default full implementation, a number of new system tables are
157  * provided that, although not used directly by this class, present previously
158  * unavailable information about the database, such as about its triggers and
159  * aliases. <p>
160  *
161  * In order to better support graphical database exploration tools and as an
162  * experimental intermediate step toward more fully supporting SQL9n and
163  * SQL200n, the default installed DatabaseInformation implementation
164  * is also capable of reporting pseudo name space information, such as
165  * the catalog (database URI) of database objects. <p>
166  *
167  * The catalog reporting feature is turned off by default but
168  * can be turned on by providing the appropriate entries in the database
169  * properties file (see the advanced topics section of the product
170  * documentation). <p>
171  *
172  * When the feature is turned on, catalog is reported using
173  * the following conventions: <p>
174  *
175  * <ol>
176  * <li>All objects are reported as having a catalog equal to the URI of the
177  * database, which is equivalent to the catenation of the
178  * <b>&lt;type&gt;</b> and <b>&lt;path&gt;</b> portions of the HSQLDB
179  * internal JDBC connection URL.<p>
180  *
181  * Examples: <p>
182  *
183  * <pre class="JavaCodeExample">
184  * <span class="JavaStringLiteral">&quot;jdbc:hsqldb:file:test&quot;</span> => <span class="JavaStringLiteral">&quot;file:test&quot;</span>
185  * <span class="JavaStringLiteral">&quot;jdbc:hsqldb:mem:.&quot;</span> => <span class="JavaStringLiteral">&quot;mem:.&quot;</span>
186  * <span class="JavaStringLiteral">&quot;jdbc:hsqldb:hsql:/host/<alias>...&quot;</span> => URI of aliased database
187  * <span class="JavaStringLiteral">&quot;jdbc:hsqldb:http:/host/<alias>...&quot;</span> => URI of aliased database
188  * </pre>
189  *
190  * <b>Note:</b> No provision is made for qualifying database objects
191  * by catalog in DML or DDL SQL. This feature is functional only with
192  * respect to browsing the database through the DatabaseMetaData and system
193  * table interfaces. <p>
194  *
195  * </ol>
196  *
197  * Again, it should be well understood that this feature provide an
198  * <i>emulation</i> of catalog support and is intended only
199  * as an experimental implementation to enhance the browsing experience
200  * when using graphical database explorers and to make a first foray
201  * into tackling the issue of implementing true catalog support
202  * in the future. <p>
203  *
204  * Due the nature of the new database system table production process, fewer
205  * assumptions can be made by this class about what information is made
206  * available in the system tables supporting <code>DatabaseMetaData</code>
207  * methods. Because of this, the SQL queries behind the <code>ResultSet</code>
208  * producing methods have been cleaned up and made to adhere more strictly to
209  * the JDBC contracts specified in relation to the method parameters. <p>
210  *
211  * One of the remaining assumptions concerns the <code>approximate</code>
212  * argument of {@link #getIndexInfo getIndexInfo()}. This parameter is still
213  * ignored since there is not yet any process in place to internally gather
214  * and persist table and index statistics. A primitive version of a statistics
215  * gathering and reporting subsystem <em>may</em> be introduced some time in the
216  * 1.7.x series of releases, but no hard decision has yet been made. <p>
217  *
218  * Another assumption is that simple select queries against certain system
219  * tables will return rows in JDBC contract order in the absence of an
220  * &quot;ORDER BY&quot; clause. The reason for this is that results
221  * come back much faster when no &quot;ORDER BY&quot; clause is used.
222  * Developers wishing to extend or replace an existing system table production
223  * class should be aware of this, either adding the contract
224  * &quot;ORDER BY&quot; clause to the SQL in corresponding methods in this class,
225  * or, better, by maintaing rows in the correct order in the underlying
226  * system tables, prefereably by creating appropriate primary indices. <p>
227  *
228  * <hr>
229  *
230  * <b>JRE 1.1.x Notes:</b> <p>
231  *
232  * In general, JDBC 2 support requires Java 1.2 and above, and JDBC3 requires
233  * Java 1.4 and above. In HSQLDB, support for methods introduced in different
234  * versions of JDBC depends on the JDK version used for compiling and building
235  * HSQLDB.<p>
236  *
237  * Since 1.7.0, it is possible to build the product so that
238  * all JDBC 2 methods can be called while executing under the version 1.1.x
239  * <em>Java Runtime Environment</em><sup><font size="-2">TM</font></sup>.
240  * However, some of these method calls require <code>int</code> values that
241  * are defined only in the JDBC 2 or greater version of the
242  * {@link java.sql.ResultSet ResultSet} interface. For this reason, when the
243  * product is compiled under JDK 1.1.x, these values are defined in
244  * {@link jdbcResultSet jdbcResultSet}.<p>
245  *
246  * In a JRE 1.1.x environment, calling JDBC 2 methods that take or return the
247  * JDBC2-only <code>ResultSet</code> values can be achieved by referring
248  * to them in parameter specifications and return value comparisons,
249  * respectively, as follows: <p>
250  *
251  * <pre class="JavaCodeExample">
252  * jdbcResultSet.FETCH_FORWARD
253  * jdbcResultSet.TYPE_FORWARD_ONLY
254  * jdbcResultSet.TYPE_SCROLL_INSENSITIVE
255  * jdbcResultSet.CONCUR_READ_ONLY
256  * // etc
257  * </pre>
258  *
259  * However, please note that code written in such a manner will not be
260  * compatible for use with other JDBC 2 drivers, since they expect and use
261  * <code>ResultSet</code>, rather than <code>jdbcResultSet</code>. Also
262  * note, this feature is offered solely as a convenience to developers
263  * who must work under JDK 1.1.x due to operating constraints, yet wish to
264  * use some of the more advanced features available under the JDBC 2
265  * specification.<p>
266  *
267  * (fredt@users)<br>
268  * (boucherb@users)
269  * </div>
270  * <!-- end release-specific documentation -->
271  *
272  * @author boucherb@users
273  * @author fredt@users
274  * @version 1.7.2
275  * @see org.hsqldb.DatabaseInformation
276  * @see org.hsqldb.DatabaseInformationMain
277  * @see org.hsqldb.DatabaseInformationFull
278  */

279 public class jdbcDatabaseMetaData implements DatabaseMetaData JavaDoc {
280
281     /** Used by getBestRowIdentifier to avoid extra object construction */
282     static final Integer JavaDoc INT_COLUMNS_NO_NULLS = new Integer JavaDoc(columnNoNulls);
283
284     // -----------------------------------------------------------------------
285
// private attributes
286
// -----------------------------------------------------------------------
287

288     /**
289      * The connection this object uses to retrieve database instance-specific
290      * metadata.
291      */

292     private jdbcConnection connection;
293
294     /**
295      * Connection property for schema reporting.
296      */

297     private boolean useSchemaDefault;
298
299     /**
300      * A CSV list representing the SQL IN list to use when generating
301      * queries for <code>getBestRowIdentifier</code> when the
302      * <code>scope</code> argument is <code>bestRowSession</code>.
303      * @since HSQLDB 1.7.2
304      */

305     private static final String JavaDoc BRI_SESSION_SCOPE_IN_LIST = "("
306         + bestRowSession + ")";
307
308     /**
309      * A CSV list representing the SQL IN list to use when generating
310      * queries for <code>getBestRowIdentifier</code> when the
311      * <code>scope</code> argument is <code>bestRowTemporary</code>.
312      * @since HSQLDB 1.7.2
313      */

314     private static final String JavaDoc BRI_TEMPORARY_SCOPE_IN_LIST = "("
315         + bestRowTemporary + "," + bestRowTransaction + "," + bestRowSession
316         + ")";
317
318     /**
319      * A CSV list representing the SQL IN list to use when generating
320      * queries for <code>getBestRowIdentifier</code> when the
321      * <code>scope</code> argument is <code>bestRowTransaction</code>.
322      * @since HSQLDB 1.7.2
323      */

324     private static final String JavaDoc BRI_TRANSACTION_SCOPE_IN_LIST = "("
325         + bestRowTransaction + "," + bestRowSession + ")";
326
327     /**
328      * "SELECT * FROM ". <p>
329      *
330      * This attribute is in support of methods that use SQL SELECT statements to
331      * generate returned <code>ResultSet</code> objects. <p>
332      *
333      * @since HSQLDB 1.7.2
334      */

335     private static final String JavaDoc selstar = "SELECT * FROM INFORMATION_SCHEMA.";
336
337     /**
338      * " WHERE 1=1 ". <p>
339      *
340      * This attribute is in support of methods that use SQL SELECT statements to
341      * generate returned <code>ResultSet</code> objects. <p>
342      *
343      * A good optimizer will simply drop this when parsing a condition
344      * expression. And it makes our code much easier to write, since we don't
345      * have to check our "WHERE" clause productions as strictly for proper
346      * conjunction: we just stick additional conjunctive predicates on the
347      * end of this and Presto! Everything works :-) <p>
348      * @since HSQLDB 1.7.2
349      */

350     private static final String JavaDoc whereTrue = " WHERE 1=1";
351
352     //----------------------------------------------------------------------
353
// First, a variety of minor information about the target database.
354

355     /**
356      * Retrieves whether the current user can call all the procedures
357      * returned by the method <code>getProcedures</code>. <p>
358      *
359      * <!-- start release-specific documentation -->
360      * <div class="ReleaseSpecificDocumentation">
361      * <h3>HSQLDB-Specific Information:</h3> <p>
362      *
363      * This method still <em>always</em> returns
364      * <code>true</code>. <p>
365      *
366      * In a future release, the plugin interface may be modified to allow
367      * implementors to report different values here, based on their
368      * implementations.
369      * </div>
370      * <!-- end release-specific documentation -->
371      *
372      * @return <code>true</code> if so; <code>false</code> otherwise
373      * @exception SQLException if a database access error occurs
374      */

375     public boolean allProceduresAreCallable() throws SQLException JavaDoc {
376         return true;
377     }
378
379     /**
380      * Retrieves whether the current user can use all the tables returned
381      * by the method <code>getTables</code> in a <code>SELECT</code>
382      * statement. <p>
383      *
384      * <!-- start release-specific documentation -->
385      * <div class="ReleaseSpecificDocumentation">
386      * <h3>HSQLDB-Specific Information:</h3> <p>
387      *
388      * HSQLDB always reports <code>true</code>.<p>
389      *
390      * Please note that the default 1.7.2 <code>getTables</code> behaviour is
391      * omit from the list of <em>requested</em> tables only those to which the
392      * invoking user has <em>no</em> access of any kind. <p>
393      *
394      * </div>
395      * <!-- end release-specific documentation -->
396      *
397      * @return <code>true</code> if so; <code>false</code> otherwise
398      * @exception SQLException if a database access error occurs
399      */

400     public boolean allTablesAreSelectable() throws SQLException JavaDoc {
401         return true;
402     }
403
404     /**
405      * Retrieves the URL for this DBMS.
406      *
407      *
408      * @return the URL for this DBMS or <code>null</code> if it cannot be
409      * generated
410      * @exception SQLException if a database access error occurs
411      */

412     public String JavaDoc getURL() throws SQLException JavaDoc {
413         return connection.getURL();
414     }
415
416     /**
417      * Retrieves the user name as known to this database.
418      *
419      *
420      * @return the database user name
421      * @exception SQLException if a database access error occurs
422      */

423     public String JavaDoc getUserName() throws SQLException JavaDoc {
424
425         ResultSet JavaDoc rs = execute("CALL USER()");
426
427         rs.next();
428
429         String JavaDoc result = rs.getString(1);
430
431         rs.close();
432
433         return result;
434     }
435
436     /**
437      * Retrieves whether this database is in read-only mode. <p>
438      *
439      * <!-- start release-specific documentation -->
440      * <div class="ReleaseSpecificDocumentation">
441      * <h3>HSQLDB-Specific Information:</h3> <p>
442      *
443      * Starting with 1.7.2, this makes
444      * an SQL call to the new {@link Library#isReadOnlyDatabase} method
445      * which provides correct determination of the read-only status for
446      * both local and remote database instances.
447      * </div>
448      * <!-- end release-specific documentation -->
449      * @return <code>true</code> if so; <code>false</code> otherwise
450      * @exception SQLException if a database access error occurs
451      */

452     public boolean isReadOnly() throws SQLException JavaDoc {
453
454         ResultSet JavaDoc rs =
455             execute("CALL \"org.hsqldb.Library.isReadOnlyDatabase\"()");
456
457         rs.next();
458
459         boolean result = rs.getBoolean(1);
460
461         rs.close();
462
463         return result;
464     }
465
466     /**
467      * Retrieves whether <code>NULL</code> values are sorted high.
468      * Sorted high means that <code>NULL</code> values
469      * sort higher than any other value in a domain. In an ascending order,
470      * if this method returns <code>true</code>, <code>NULL</code> values
471      * will appear at the end. By contrast, the method
472      * <code>nullsAreSortedAtEnd</code> indicates whether <code>NULL</code> values
473      * are sorted at the end regardless of sort order. <p>
474      *
475      * <!-- start release-specific documentation -->
476      * <div class="ReleaseSpecificDocumentation">
477      * <h3>HSQLDB-Specific Information:</h3> <p>
478      *
479      * HSQLDB sorts null low; this method always returns <code>false</code>.
480      * </div>
481      * <!-- end release-specific documentation -->
482      *
483      *
484      * @return <code>true</code> if so; <code>false</code> otherwise
485      * @exception SQLException if a database access error occurs
486      */

487     public boolean nullsAreSortedHigh() throws SQLException JavaDoc {
488         return false;
489     }
490
491     /**
492      * Retrieves whether <code>NULL</code> values are sorted low.
493      * Sorted low means that <code>NULL</code> values
494      * sort lower than any other value in a domain. In an ascending order,
495      * if this method returns <code>true</code>, <code>NULL</code> values
496      * will appear at the beginning. By contrast, the method
497      * <code>nullsAreSortedAtStart</code> indicates whether <code>NULL</code> values
498      * are sorted at the beginning regardless of sort order. <p>
499      *
500      * <!-- start release-specific documentation -->
501      * <div class="ReleaseSpecificDocumentation">
502      * <h3>HSQLDB-Specific Information:</h3> <p>
503      *
504      * HSQLDB sorts null low; this method always returns <code>true</code>.
505      * </div>
506      * <!-- end release-specific documentation -->
507      *
508      *
509      * @return <code>true</code> if so; <code>false</code> otherwise
510      * @exception SQLException if a database access error occurs
511      */

512     public boolean nullsAreSortedLow() throws SQLException JavaDoc {
513         return true;
514     }
515
516     /**
517      * Retrieves whether <code>NULL</code> values are sorted at the start regardless
518      * of sort order. <p>
519      *
520      * <!-- start release-specific documentation -->
521      * <div class="ReleaseSpecificDocumentation">
522      * <h3>HSQLDB-Specific Information:</h3> <p>
523      *
524      * HSQLDB sorts null low; this method always returns <code>false</code>.
525      * </div>
526      * <!-- end release-specific documentation -->
527      *
528      *
529      * @return <code>true</code> if so; <code>false</code> otherwise
530      * @exception SQLException if a database access error occurs
531      */

532     public boolean nullsAreSortedAtStart() throws SQLException JavaDoc {
533         return false;
534     }
535
536     /**
537      * Retrieves whether <code>NULL</code> values are sorted at the end regardless of
538      * sort order. <p>
539      *
540      * <!-- start release-specific documentation -->
541      * <div class="ReleaseSpecificDocumentation">
542      * <h3>HSQLDB-Specific Information:</h3> <p>
543      *
544      * HSQLDB sorts null low; this method always returns <code>false</code>.
545      * </div>
546      * <!-- end release-specific documentation -->
547      *
548      *
549      * @return <code>true</code> if so; <code>false</code> otherwise
550      * @exception SQLException if a database access error occurs
551      */

552     public boolean nullsAreSortedAtEnd() throws SQLException JavaDoc {
553         return false;
554     }
555
556     /**
557      * Retrieves the name of this database product. <p>
558      *
559      * <div class="ReleaseSpecificDocumentation">
560      * <h3>HSQLDB-Specific Information:</h3> <p>
561      *
562      * Starting with HSQLDB 1.7.2, this value is retrieved through an
563      * SQL call to the new {@link Library#getDatabaseProductName} method
564      * which allows correct determination of the database product name
565      * for both local and remote database instances.
566      * </div> <p>
567      *
568      * @return database product name
569      * @exception SQLException if a database access error occurs
570      */

571     public String JavaDoc getDatabaseProductName() throws SQLException JavaDoc {
572
573         ResultSet JavaDoc rs =
574             execute("call \"org.hsqldb.Library.getDatabaseProductName\"()");
575
576         rs.next();
577
578         String JavaDoc result = rs.getString(1);
579
580         rs.close();
581
582         return result;
583     }
584
585     /**
586      * Retrieves the version number of this database product. <p>
587      *
588      * <div class="ReleaseSpecificDocumentation">
589      * <h3>HSQLDB-Specific Information:</h3> <p>
590      *
591      * Starting with HSQLDB 1.7.2, this value is retrieved through an
592      * SQL call to the new {@link Library#getDatabaseProductVersion} method
593      * which allows correct determination of the database product name
594      * for both local and remote database instances.
595      * </div> <p>
596      *
597      * @return database version number
598      * @exception SQLException if a database access error occurs
599      */

600     public String JavaDoc getDatabaseProductVersion() throws SQLException JavaDoc {
601
602         ResultSet JavaDoc rs = execute(
603             "call \"org.hsqldb.Library.getDatabaseProductVersion\"()");
604
605         rs.next();
606
607         String JavaDoc result = rs.getString(1);
608
609         rs.close();
610
611         return result;
612     }
613
614     /**
615      * Retrieves the name of this JDBC driver.
616      *
617      * @return JDBC driver name
618      * @exception SQLException if a database access error occurs
619      */

620     public String JavaDoc getDriverName() throws SQLException JavaDoc {
621         return HsqlDatabaseProperties.PRODUCT_NAME + " Driver";
622     }
623
624     /**
625      * Retrieves the version number of this JDBC driver as a <code>String</code>.
626      *
627      * @return JDBC driver version
628      * @exception SQLException if a database access error occurs
629      */

630     public String JavaDoc getDriverVersion() throws SQLException JavaDoc {
631         return HsqlDatabaseProperties.THIS_VERSION;
632     }
633
634     /**
635      * Retrieves this JDBC driver's major version number.
636      *
637      * @return JDBC driver major version
638      */

639     public int getDriverMajorVersion() {
640         return HsqlDatabaseProperties.MAJOR;
641     }
642
643     /**
644      * Retrieves this JDBC driver's minor version number.
645      *
646      * @return JDBC driver minor version number
647      */

648     public int getDriverMinorVersion() {
649         return HsqlDatabaseProperties.MINOR;
650     }
651
652     /**
653      * Retrieves whether this database stores tables in a local file. <p>
654      *
655      * <!-- start release-specific documentation -->
656      * <div class="ReleaseSpecificDocumentation">
657      * <h3>HSQLDB-Specific Information:</h3> <p>
658      *
659      * From HSQLDB 1.7.2 it is assumed that this refers to data being stored
660      * by the JDBC client. This method always returns false.
661      * </div>
662      * <!-- end release-specific documentation -->
663      * @return <code>true</code> if so; <code>false</code> otherwise
664      * @exception SQLException if a database access error occurs
665      */

666     public boolean usesLocalFiles() throws SQLException JavaDoc {
667         return false;
668     }
669
670     /**
671      * Retrieves whether this database uses a file for each table. <p>
672      *
673      * <!-- start release-specific documentation -->
674      * <div class="ReleaseSpecificDocumentation">
675      * <h3>HSQLDB-Specific Information:</h3> <p>
676      *
677      * Up to and including 1.7.2, HSQLDB does not use a file for each table.
678      * This method always returns <code>false</code>.
679      * </div>
680      * <!-- end release-specific documentation -->
681      * @return <code>true</code> if this database uses a local file for each table;
682      * <code>false</code> otherwise
683      * @exception SQLException if a database access error occurs
684      */

685     public boolean usesLocalFilePerTable() throws SQLException JavaDoc {
686         return false;
687     }
688
689     /**
690      * Retrieves whether this database treats mixed case unquoted SQL identifiers as
691      * case sensitive and as a result stores them in mixed case. <p>
692      *
693      * <!-- start release-specific documentation -->
694      * <div class="ReleaseSpecificDocumentation">
695      * <h3>HSQLDB-Specific Information:</h3> <p>
696      *
697      * HSQLDB treats unquoted identifiers as case insensitive and stores
698      * them in upper case. It treats quoted identifiers as case sensitive and
699      * stores them verbatim; this method always returns <code>false</code>.
700      * </div>
701      * <!-- end release-specific documentation -->
702      *
703      *
704      * @return <code>true</code> if so; <code>false</code> otherwise
705      * @exception SQLException if a database access error occurs
706      */

707     public boolean supportsMixedCaseIdentifiers() throws SQLException JavaDoc {
708         return false;
709     }
710
711     /**
712      * Retrieves whether this database treats mixed case unquoted SQL identifiers as
713      * case insensitive and stores them in upper case. <p>
714      *
715      * <!-- start release-specific documentation -->
716      * <div class="ReleaseSpecificDocumentation">
717      * <h3>HSQLDB-Specific Information:</h3> <p>
718      *
719      * HSQLDB treats unquoted identifiers as case insensitive and stores
720      * them in upper case. It treats quoted identifiers as case sensitive and
721      * stores them verbatim; this method always returns <code>true</code>.
722      * </div>
723      * <!-- end release-specific documentation -->
724      *
725      *
726      * @return <code>true</code> if so; <code>false</code> otherwise
727      * @exception SQLException if a database access error occurs
728      */

729     public boolean storesUpperCaseIdentifiers() throws SQLException JavaDoc {
730         return true;
731     }
732
733     /**
734      * Retrieves whether this database treats mixed case unquoted SQL identifiers as
735      * case insensitive and stores them in lower case. <p>
736      *
737      * <!-- start release-specific documentation -->
738      * <div class="ReleaseSpecificDocumentation">
739      * <h3>HSQLDB-Specific Information:</h3> <p>
740      *
741      * HSQLDB treats unquoted identifiers as case insensitive and stores
742      * them in upper case. It treats quoted identifiers as case sensitive and
743      * stores them verbatim; this method always returns <code>false</code>.
744      * </div>
745      * <!-- end release-specific documentation -->
746      *
747      *
748      * @return <code>true</code> if so; <code>false</code> otherwise
749      * @exception SQLException if a database access error occurs
750      */

751     public boolean storesLowerCaseIdentifiers() throws SQLException JavaDoc {
752         return false;
753     }
754
755     /**
756      * Retrieves whether this database treats mixed case unquoted SQL identifiers as
757      * case insensitive and stores them in mixed case. <p>
758      *
759      * <!-- start release-specific documentation -->
760      * <div class="ReleaseSpecificDocumentation">
761      * <h3>HSQLDB-Specific Information:</h3> <p>
762      *
763      * HSQLDB treats unquoted identifiers as case insensitive and stores
764      * them in upper case. It treats quoted identifiers as case sensitive and
765      * stores them verbatim; this method always returns <code>false</code>.
766      * </div>
767      * <!-- end release-specific documentation -->
768      *
769      *
770      * @return <code>true</code> if so; <code>false</code> otherwise
771      * @exception SQLException if a database access error occurs
772      */

773     public boolean storesMixedCaseIdentifiers() throws SQLException JavaDoc {
774         return false;
775     }
776
777     /**
778      * Retrieves whether this database treats mixed case quoted SQL identifiers as
779      * case sensitive and as a result stores them in mixed case. <p>
780      *
781      * <!-- start release-specific documentation -->
782      * <div class="ReleaseSpecificDocumentation">
783      * <h3>HSQLDB-Specific Information:</h3> <p>
784      *
785      * HSQLDB treats unquoted identifiers as case insensitive and stores
786      * them in upper case. It treats quoted identifiers as case sensitive and
787      * stores them verbatim; this method always returns <code>true</code>.
788      * </div>
789      * <!-- end release-specific documentation -->
790      *
791      *
792      * @return <code>true</code> if so; <code>false</code> otherwise
793      * @exception SQLException if a database access error occurs
794      */

795     public boolean supportsMixedCaseQuotedIdentifiers() throws SQLException JavaDoc {
796         return true;
797     }
798
799     /**
800      * Retrieves whether this database treats mixed case quoted SQL identifiers as
801      * case insensitive and stores them in upper case. <p>
802      *
803      * <!-- start release-specific documentation -->
804      * <div class="ReleaseSpecificDocumentation">
805      * <h3>HSQLDB-Specific Information:</h3> <p>
806      *
807      * HSQLDB treats unquoted identifiers as case insensitive and stores
808      * them in upper case. It treats quoted identifiers as case sensitive and
809      * stores them verbatim; this method always returns <code>false</code>.
810      * </div>
811      * <!-- end release-specific documentation -->
812      *
813      *
814      * @return <code>true</code> if so; <code>false</code> otherwise
815      * @exception SQLException if a database access error occurs
816      */

817     public boolean storesUpperCaseQuotedIdentifiers() throws SQLException JavaDoc {
818         return false;
819     }
820
821     /**
822      * Retrieves whether this database treats mixed case quoted SQL identifiers as
823      * case insensitive and stores them in lower case. <p>
824      *
825      * <!-- start release-specific documentation -->
826      * <div class="ReleaseSpecificDocumentation">
827      * <h3>HSQLDB-Specific Information:</h3> <p>
828      *
829      * HSQLDB treats unquoted identifiers as case insensitive and stores
830      * them in upper case. It treats quoted identifiers as case sensitive and
831      * stores them verbatim; this method always returns <code>false</code>.
832      * </div>
833      * <!-- end release-specific documentation -->
834      * @return <code>true</code> if so; <code>false</code> otherwise
835      * @exception SQLException if a database access error occurs
836      */

837     public boolean storesLowerCaseQuotedIdentifiers() throws SQLException JavaDoc {
838         return false;
839     }
840
841     /**
842      * Retrieves whether this database treats mixed case quoted SQL identifiers as
843      * case insensitive and stores them in mixed case. <p>
844      *
845      * <!-- start release-specific documentation -->
846      * <div class="ReleaseSpecificDocumentation">
847      * <h3>HSQLDB-Specific Information:</h3> <p>
848      *
849      * HSQLDB treats unquoted identifiers as case insensitive and stores
850      * them in upper case. It treats quoted identifiers as case sensitive and
851      * stores them verbatim; this method always returns <code>false</code>.
852      * </div>
853      * <!-- end release-specific documentation -->
854      *
855      *
856      * @return <code>true</code> if so; <code>false</code> otherwise
857      * @exception SQLException if a database access error occurs
858      */

859     public boolean storesMixedCaseQuotedIdentifiers() throws SQLException JavaDoc {
860         return false;
861     }
862
863     /**
864      * Retrieves the string used to quote SQL identifiers.
865      * This method returns a space " " if identifier quoting is not supported. <p>
866      *
867      * <!-- start release-specific documentation -->
868      * <div class="ReleaseSpecificDocumentation">
869      * <h3>HSQLDB-Specific Information:</h3> <p>
870      *
871      * HSQLDB uses the standard SQL identifier quote character
872      * (the double quote character); this method always returns <b>"</b>.
873      * </div>
874      * <!-- end release-specific documentation -->
875      * @return the quoting string or a space if quoting is not supported
876      * @exception SQLException if a database access error occurs
877      */

878     public String JavaDoc getIdentifierQuoteString() throws SQLException JavaDoc {
879         return "\"";
880     }
881
882 //fredt@users 20020429 - JavaDoc comment - in 1.7.1 there are keywords such
883
// as TEMP, TEXT, CACHED that are not SQL 92 keywords
884

885     /**
886      * Retrieves a comma-separated list of all of this database's SQL keywords
887      * that are NOT also SQL92 keywords. <p>
888      *
889      * <!-- start release-specific documentation -->
890      * <div class="ReleaseSpecificDocumentation">
891      * <h3>HSQLDB-Specific Information:</h3> <p>
892      *
893      * The list returned contains HSQLDB keywords that are not in the list
894      * of reserved words. Some of these are in the list reserved
895      * words for SQL 2003 but are not SQL92 keywords.
896      * </div>
897      * <!-- end release-specific documentation -->
898      *
899      *
900      * @return the list of this database's keywords that are not also
901      * SQL92 keywords
902      * @exception SQLException if a database access error occurs
903      */

904     public String JavaDoc getSQLKeywords() throws SQLException JavaDoc {
905
906         return "BEFORE,BIGINT,BINARY,CACHED,DATETIME,"
907                + "LIMIT,LONGVARBINARY,LONGVARCHAR,OBJECT,OTHER,SAVEPOINT,"
908                + "TEMP,TEXT,TOP,TRIGGER,TINYINT,VARBINARY,VARCHAR_IGNORECASE";
909     }
910
911     /**
912      * Retrieves a comma-separated list of math functions available with
913      * this database. These are the Open Group CLI math function names used in
914      * the JDBC function escape clause.
915      * @return the list of math functions supported by this database
916      * @exception SQLException if a database access error occurs
917      */

918     public String JavaDoc getNumericFunctions() throws SQLException JavaDoc {
919         return StringUtil.getList(Library.sNumeric, ",", "");
920     }
921
922     /**
923      * Retrieves a comma-separated list of string functions available with
924      * this database. These are the Open Group CLI string function names used
925      * in the JDBC function escape clause.
926      * @return the list of string functions supported by this database
927      * @exception SQLException if a database access error occurs
928      */

929     public String JavaDoc getStringFunctions() throws SQLException JavaDoc {
930         return StringUtil.getList(Library.sString, ",", "");
931     }
932
933     /**
934      * Retrieves a comma-separated list of system functions available with
935      * this database. These are the Open Group CLI system function names used
936      * in the JDBC function escape clause.
937      * @return a list of system functions supported by this database
938      * @exception SQLException if a database access error occurs
939      */

940     public String JavaDoc getSystemFunctions() throws SQLException JavaDoc {
941         return StringUtil.getList(Library.sSystem, ",", "");
942     }
943
944     /**
945      * Retrieves a comma-separated list of the time and date functions available
946      * with this database.
947      * @return the list of time and date functions supported by this database
948      * @exception SQLException if a database access error occurs
949      */

950     public String JavaDoc getTimeDateFunctions() throws SQLException JavaDoc {
951         return StringUtil.getList(Library.sTimeDate, ",", "");
952     }
953
954     /**
955      * Retrieves the string that can be used to escape wildcard characters.
956      * This is the string that can be used to escape '_' or '%' in
957      * the catalog search parameters that are a pattern (and therefore use one
958      * of the wildcard characters).
959      *
960      * <P>The '_' character represents any single character;
961      * the '%' character represents any sequence of zero or
962      * more characters. <p>
963      *
964      * <!-- start release-specific documentation -->
965      * <div class="ReleaseSpecificDocumentation">
966      * <h3>HSQLDB-Specific Information:</h3> <p>
967      *
968      * HSQLDB uses the "\" character to escape wildcard characters.
969      * </div>
970      * <!-- end release-specific documentation -->
971      *
972      *
973      * @return the string used to escape wildcard characters
974      * @exception SQLException if a database access error occurs
975      */

976     public String JavaDoc getSearchStringEscape() throws SQLException JavaDoc {
977         return "\\";
978     }
979
980     /**
981      * Retrieves all the "extra" characters that can be used in unquoted
982      * identifier names (those beyond a-z, A-Z, 0-9 and _). <p>
983      *
984      * <!-- start release-specific documentation -->
985      * <div class="ReleaseSpecificDocumentation">
986      * <h3>HSQLDB-Specific Information:</h3> <p>
987      *
988      * HSQLDB does not support using any "extra" characters in unquoted
989      * identifier names; this method always returns the empty String.
990      * </div>
991      * <!-- end release-specific documentation -->
992      *
993      *
994      * @return the string containing the extra characters
995      * @exception SQLException if a database access error occurs
996      */

997     public String JavaDoc getExtraNameCharacters() throws SQLException JavaDoc {
998         return "";
999     }
1000
1001    //--------------------------------------------------------------------
1002
// Functions describing which features are supported.
1003

1004    /**
1005     * Retrieves whether this database supports <code>ALTER TABLE</code>
1006     * with add column. <p>
1007     *
1008     * <!-- start release-specific documentation -->
1009     * <div class="ReleaseSpecificDocumentation">
1010     * <h3>HSQLDB-Specific Information:</h3> <p>
1011     *
1012     * From 1.7.0, HSQLDB supports this type of
1013     * <code>ALTER TABLE</code> statement; this method always
1014     * returns <code>true</code>.
1015     * </div>
1016     * <!-- end release-specific documentation -->
1017     * @return <code>true</code> if so; <code>false</code> otherwise
1018     * @exception SQLException if a database access error occurs
1019     */

1020    public boolean supportsAlterTableWithAddColumn() throws SQLException JavaDoc {
1021        return true;
1022    }
1023
1024    /**
1025     * Retrieves whether this database supports <code>ALTER TABLE</code>
1026     * with drop column. <p>
1027     *
1028     * <!-- start release-specific documentation -->
1029     * <div class="ReleaseSpecificDocumentation">
1030     * <h3>HSQLDB-Specific Information:</h3> <p>
1031     *
1032     * From 1.7.0, HSQLDB supports this type of
1033     * <code>ALTER TABLE</code> statement; this method always
1034     * returns <code>true</code>.
1035     * </div>
1036     * <!-- end release-specific documentation -->
1037     * @return <code>true</code> if so; <code>false</code> otherwise
1038     * @exception SQLException if a database access error occurs
1039     */

1040    public boolean supportsAlterTableWithDropColumn() throws SQLException JavaDoc {
1041        return true;
1042    }
1043
1044    /**
1045     * Retrieves whether this database supports column aliasing.
1046     *
1047     * <P>If so, the SQL AS clause can be used to provide names for
1048     * computed columns or to provide alias names for columns as
1049     * required. <p>
1050     *
1051     * <!-- start release-specific documentation -->
1052     * <div class="ReleaseSpecificDocumentation">
1053     * <h3>HSQLDB-Specific Information:</h3> <p>
1054     *
1055     * HSQLDB supports column aliasing; this method always
1056     * returns <code>true</code>.
1057     * </div>
1058     * <!-- end release-specific documentation -->
1059     *
1060     *
1061     * @return <code>true</code> if so; <code>false</code> otherwise
1062     * @exception SQLException if a database access error occurs
1063     */

1064    public boolean supportsColumnAliasing() throws SQLException JavaDoc {
1065        return true;
1066    }
1067
1068    /**
1069     * Retrieves whether this database supports concatenations between
1070     * <code>NULL</code> and non-<code>NULL</code> values being
1071     * <code>NULL</code>. <p>
1072     *
1073     * <!-- start release-specific documentation -->
1074     * <div class="ReleaseSpecificDocumentation">
1075     * <h3>HSQLDB-Specific Information:</h3> <p>
1076     *
1077     * HSQLDB supports this; this method always
1078     * returns <code>true</code>.
1079     * </div>
1080     * <!-- end release-specific documentation -->
1081     *
1082     *
1083     * @return <code>true</code> if so; <code>false</code> otherwise
1084     * @exception SQLException if a database access error occurs
1085     */

1086    public boolean nullPlusNonNullIsNull() throws SQLException JavaDoc {
1087        return true;
1088    }
1089
1090    /**
1091     * Retrieves whether this database supports the <code>CONVERT</code>
1092     * function between SQL types. <p>
1093     *
1094     * <!-- start release-specific documentation -->
1095     * <div class="ReleaseSpecificDocumentation">
1096     * <h3>HSQLDB-Specific Information:</h3> <p>
1097     *
1098     * HSQLDB supports conversions; this method always
1099     * returns <code>true</code>.
1100     * </div>
1101     * <!-- end release-specific documentation -->
1102     *
1103     *
1104     * @return <code>true</code> if so; <code>false</code> otherwise
1105     * @exception SQLException if a database access error occurs
1106     */

1107    public boolean supportsConvert() throws SQLException JavaDoc {
1108        return true;
1109    }
1110
1111// fredt@users - JD comment - I think this is unsupported at the moment
1112
// because SQL92 says conversion is implementation dependent, so if
1113
// conversion from DOUBLE to INTEGER were possbible we would return the
1114
// whole number part, but we currently throw. I'm not so sure about
1115
// conversions between string and numeric where it is logically possible
1116
// only if the string represents a numeric value
1117

1118    /**
1119     * Retrieves whether this database supports the <code>CONVERT</code>
1120     * for two given SQL types. <p>
1121     *
1122     * <!-- start release-specific documentation -->
1123     * <div class="ReleaseSpecificDocumentation">
1124     * <h3>HSQLDB-Specific Information:</h3> <p>
1125     *
1126     * HSQLDB supports conversion though String intermediates, so everything
1127     * should be possible, short of number format errors (all Java objects
1128     * have a toString method); this method always returns <code>true</code>.
1129     * </div>
1130     * <!-- end release-specific documentation -->
1131     *
1132     *
1133     * @param fromType the type to convert from; one of the type codes from
1134     * the class <code>java.sql.Types</code>
1135     * @param toType the type to convert to; one of the type codes from
1136     * the class <code>java.sql.Types</code>
1137     * @return <code>true</code> if so; <code>false</code> otherwise
1138     * @exception SQLException if a database access error occurs
1139     * @see java.sql.Types
1140     */

1141    public boolean supportsConvert(int fromType,
1142                                   int toType) throws SQLException JavaDoc {
1143        return true;
1144    }
1145
1146    /**
1147     * Retrieves whether this database supports table correlation names. <p>
1148     *
1149     * <!-- start release-specific documentation -->
1150     * <div class="ReleaseSpecificDocumentation">
1151     * <h3>HSQLDB-Specific Information:</h3> <p>
1152     *
1153     * HSQLDB supports table correlation names; this method always
1154     * returns <code>true</code>.
1155     * </div>
1156     * <!-- end release-specific documentation -->
1157     *
1158     *
1159     * @return <code>true</code> if so; <code>false</code> otherwise
1160     * @exception SQLException if a database access error occurs
1161     */

1162    public boolean supportsTableCorrelationNames() throws SQLException JavaDoc {
1163        return true;
1164    }
1165
1166    /**
1167     * Retrieves whether, when table correlation names are supported, they
1168     * are restricted to being different from the names of the tables. <p>
1169     *
1170     * <!-- start release-specific documentation -->
1171     * <div class="ReleaseSpecificDocumentation">
1172     * <h3>HSQLDB-Specific Information:</h3> <p>
1173     *
1174     * HSQLDB requires that table correlation names are different from the
1175     * names of the tables; this method always returns <code>true</code>.
1176     * </div>
1177     * <!-- end release-specific documentation -->
1178     *
1179     *
1180     * @return <code>true</code> if so; <code>false</code> otherwise
1181     * @exception SQLException if a database access error occurs
1182     */

1183    public boolean supportsDifferentTableCorrelationNames()
1184    throws SQLException JavaDoc {
1185        return true;
1186    }
1187
1188    /**
1189     * Retrieves whether this database supports expressions in
1190     * <code>ORDER BY</code> lists. <p>
1191     *
1192     * <!-- start release-specific documentation -->
1193     * <div class="ReleaseSpecificDocumentation">
1194     * <h3>HSQLDB-Specific Information:</h3> <p>
1195     *
1196     * HSQLDB supports expressions in <code>ORDER BY</code> lists; this
1197     * method always returns <code>true</code>.
1198     * </div>
1199     * <!-- end release-specific documentation -->
1200     *
1201     *
1202     * @return <code>true</code> if so; <code>false</code> otherwise
1203     * @exception SQLException if a database access error occurs
1204     */

1205    public boolean supportsExpressionsInOrderBy() throws SQLException JavaDoc {
1206        return true;
1207    }
1208
1209    /**
1210     * Retrieves whether this database supports using a column that is
1211     * not in the <code>SELECT</code> statement in an
1212     * <code>ORDER BY</code> clause. <p>
1213     *
1214     * <!-- start release-specific documentation -->
1215     * <div class="ReleaseSpecificDocumentation">
1216     * <h3>HSQLDB-Specific Information:</h3> <p>
1217     *
1218     * HSQLDB supports using a column that is not in the <code>SELECT</code>
1219     * statement in an <code>ORDER BY</code> clause; this method always
1220     * returns <code>true</code>.
1221     * </div>
1222     * <!-- end release-specific documentation -->
1223     *
1224     *
1225     * @return <code>true</code> if so; <code>false</code> otherwise
1226     * @exception SQLException if a database access error occurs
1227     */

1228    public boolean supportsOrderByUnrelated() throws SQLException JavaDoc {
1229        return true;
1230    }
1231
1232    /**
1233     * Retrieves whether this database supports some form of
1234     * <code>GROUP BY</code> clause. <p>
1235     *
1236     * <!-- start release-specific documentation -->
1237     * <div class="ReleaseSpecificDocumentation">
1238     * <h3>HSQLDB-Specific Information:</h3> <p>
1239     *
1240     * HSQLDB supports using the <code>GROUP BY</code> clause; this method
1241     * always returns <code>true</code>.
1242     * </div>
1243     * <!-- end release-specific documentation -->
1244     *
1245     *
1246     * @return <code>true</code> if so; <code>false</code> otherwise
1247     * @exception SQLException if a database access error occurs
1248     */

1249    public boolean supportsGroupBy() throws SQLException JavaDoc {
1250        return true;
1251    }
1252
1253    /**
1254     * Retrieves whether this database supports using a column that is
1255     * not in the <code>SELECT</code> statement in a
1256     * <code>GROUP BY</code> clause. <p>
1257     *
1258     * <!-- start release-specific documentation -->
1259     * <div class="ReleaseSpecificDocumentation">
1260     * <h3>HSQLDB-Specific Information:</h3> <p>
1261     *
1262     * HSQLDB supports using a column that is
1263     * not in the <code>SELECT</code> statement in a
1264     * <code>GROUP BY</code> clause; this method
1265     * always returns <code>true</code>.
1266     * </div>
1267     * <!-- end release-specific documentation -->
1268     *
1269     *
1270     * @return <code>true</code> if so; <code>false</code> otherwise
1271     * @exception SQLException if a database access error occurs
1272     */

1273    public boolean supportsGroupByUnrelated() throws SQLException JavaDoc {
1274        return true;
1275    }
1276
1277    /**
1278     * Retrieves whether this database supports using columns not included in
1279     * the <code>SELECT</code> statement in a <code>GROUP BY</code> clause
1280     * provided that all of the columns in the <code>SELECT</code> statement
1281     * are included in the <code>GROUP BY</code> clause. <p>
1282     *
1283     * <!-- start release-specific documentation -->
1284     * <div class="ReleaseSpecificDocumentation">
1285     * <h3>HSQLDB-Specific Information:</h3> <p>
1286     *
1287     * HSQLDB supports using columns not included in
1288     * the <code>SELECT</code> statement in a <code>GROUP BY</code> clause
1289     * provided that all of the columns in the <code>SELECT</code> statement
1290     * are included in the <code>GROUP BY</code> clause; this method
1291     * always returns <code>true</code>.
1292     * </div>
1293     * <!-- end release-specific documentation -->
1294     *
1295     *
1296     * @return <code>true</code> if so; <code>false</code> otherwise
1297     * @exception SQLException if a database access error occurs
1298     */

1299    public boolean supportsGroupByBeyondSelect() throws SQLException JavaDoc {
1300        return true;
1301    }
1302
1303    /**
1304     * Retrieves whether this database supports specifying a
1305     * <code>LIKE</code> escape clause. <p>
1306     *
1307     * <!-- start release-specific documentation -->
1308     * <div class="ReleaseSpecificDocumentation">
1309     * <h3>HSQLDB-Specific Information:</h3> <p>
1310     *
1311     * HSQLDB supports specifying a
1312     * <code>LIKE</code> escape clause; this method
1313     * always returns <code>true</code>.
1314     * </div>
1315     * <!-- end release-specific documentation -->
1316     *
1317     *
1318     * @return <code>true</code> if so; <code>false</code> otherwise
1319     * @exception SQLException if a database access error occurs
1320     */

1321    public boolean supportsLikeEscapeClause() throws SQLException JavaDoc {
1322        return true;
1323    }
1324
1325    /**
1326     * Retrieves whether this database supports getting multiple
1327     * <code>ResultSet</code> objects from a single call to the
1328     * method <code>execute</code>. <p>
1329     *
1330     * <!-- start release-specific documentation -->
1331     * <div class="ReleaseSpecificDocumentation">
1332     * <h3>HSQLDB-Specific Information:</h3> <p>
1333     *
1334     * Up to and including 1.7.2, HSQLDB does not support getting multiple
1335     * <code>ResultSet</code> objects from a single call to the
1336     * method <code>execute</code>; this method
1337     * always returns <code>false</code>. <p>
1338     *
1339     * This behaviour <i>may</i> change in a future release.
1340     * </div>
1341     * <!-- end release-specific documentation -->
1342     * @return <code>true</code> if so; <code>false</code> otherwise
1343     * @exception SQLException if a database access error occurs
1344     */

1345    public boolean supportsMultipleResultSets() throws SQLException JavaDoc {
1346        return false;
1347    }
1348
1349    /**
1350     * Retrieves whether this database allows having multiple
1351     * transactions open at once (on different connections). <p>
1352     *
1353     * <!-- start release-specific documentation -->
1354     * <div class="ReleaseSpecificDocumentation">
1355     * <h3>HSQLDB-Specific Information:</h3> <p>
1356     *
1357     * HSQLDB allows having multiple
1358     * transactions open at once (on different connections); this method
1359     * always returns <code>true</code>.
1360     * </div>
1361     * <!-- end release-specific documentation -->
1362     *
1363     *
1364     * @return <code>true</code> if so; <code>false</code> otherwise
1365     * @exception SQLException if a database access error occurs
1366     */

1367    public boolean supportsMultipleTransactions() throws SQLException JavaDoc {
1368        return true;
1369    }
1370
1371    /**
1372     * Retrieves whether columns in this database may be defined as
1373     * non-nullable. <p>
1374     *
1375     * <!-- start release-specific documentation -->
1376     * <div class="ReleaseSpecificDocumentation">
1377     * <h3>HSQLDB-Specific Information:</h3> <p>
1378     *
1379     * HSQLDB supports the specification of non-nullable columns; this method
1380     * always returns <code>true</code>.
1381     * </div>
1382     * <!-- end release-specific documentation -->
1383     *
1384     *
1385     * @return <code>true</code> if so; <code>false</code> otherwise
1386     * @exception SQLException if a database access error occurs
1387     */

1388    public boolean supportsNonNullableColumns() throws SQLException JavaDoc {
1389        return true;
1390    }
1391
1392    /**
1393     * Retrieves whether this database supports the ODBC Minimum SQL grammar. <p>
1394     *
1395     * <!-- start release-specific documentation -->
1396     * <div class="ReleaseSpecificDocumentation">
1397     * <h3>HSQLDB-Specific Information:</h3> <p>
1398     *
1399     * Up to and including 1.7.2, HSQLDB does not support the ODBC
1400     * Minimum SQL grammar; this method
1401     * always returns <code>false</code>.
1402     * </div>
1403     * <!-- end release-specific documentation -->
1404     * @return <code>true</code> if so; <code>false</code> otherwise
1405     * @exception SQLException if a database access error occurs
1406     */

1407    public boolean supportsMinimumSQLGrammar() throws SQLException JavaDoc {
1408        return false;
1409    }
1410
1411    /**
1412     * Retrieves whether this database supports the ODBC Core SQL grammar. <p>
1413     *
1414     * <!-- start release-specific documentation -->
1415     * <div class="ReleaseSpecificDocumentation">
1416     * <h3>HSQLDB-Specific Information:</h3> <p>
1417     *
1418     * From 1.7.2 this method always returns <code>true</code>.
1419     * </div>
1420     * <!-- end release-specific documentation -->
1421     * @return <code>true</code> if so; <code>false</code> otherwise
1422     * @exception SQLException if a database access error occurs
1423     */

1424    public boolean supportsCoreSQLGrammar() throws SQLException JavaDoc {
1425        return true;
1426    }
1427
1428    /**
1429     * Retrieves whether this database supports the ODBC Extended SQL grammar. <p>
1430     *
1431     * <!-- start release-specific documentation -->
1432     * <div class="ReleaseSpecificDocumentation">
1433     * <h3>HSQLDB-Specific Information:</h3> <p>
1434     *
1435     * Up to and including 1.7.2, HSQLDB does not support the ODBC
1436     * Extended SQL grammar; this method
1437     * always returns <code>false</code>.
1438     * </div>
1439     * <!-- end release-specific documentation -->
1440     * @return <code>true</code> if so; <code>false</code> otherwise
1441     * @exception SQLException if a database access error occurs
1442     */

1443    public boolean supportsExtendedSQLGrammar() throws SQLException JavaDoc {
1444        return false;
1445    }
1446
1447    /**
1448     * Retrieves whether this database supports the ANSI92 entry level SQL
1449     * grammar. <p>
1450     *
1451     * <!-- start release-specific documentation -->
1452     * <div class="ReleaseSpecificDocumentation">
1453     * <h3>HSQLDB-Specific Information:</h3> <p>
1454     *
1455     * Up to and including 1.7.2, HSQLDB does not support the ANSI92 entry
1456     * level SQL grammar; this method
1457     * always returns <code>false</code>.
1458     * </div>
1459     * <!-- end release-specific documentation -->
1460     * @return <code>true</code> if so; <code>false</code> otherwise
1461     * @exception SQLException if a database access error occurs
1462     */

1463    public boolean supportsANSI92EntryLevelSQL() throws SQLException JavaDoc {
1464        return false;
1465    }
1466
1467    /**
1468     * Retrieves whether this database supports the ANSI92 intermediate SQL
1469     * grammar supported. <p>
1470     *
1471     * <!-- start release-specific documentation -->
1472     * <div class="ReleaseSpecificDocumentation">
1473     * <h3>HSQLDB-Specific Information:</h3> <p>
1474     *
1475     * Up to and including 1.7.2, HSQLDB does not support the ANSI92
1476     * intermediate SQL grammar; this method always returns
1477     * <code>false</code>.
1478     * </div>
1479     * <!-- end release-specific documentation -->
1480     * @return <code>true</code> if so; <code>false</code> otherwise
1481     * @exception SQLException if a database access error occurs
1482     */

1483    public boolean supportsANSI92IntermediateSQL() throws SQLException JavaDoc {
1484        return false;
1485    }
1486
1487    /**
1488     * Retrieves whether this database supports the ANSI92 full SQL
1489     * grammar supported. <p>
1490     *
1491     * <!-- start release-specific documentation -->
1492     * <div class="ReleaseSpecificDocumentation">
1493     * <h3>HSQLDB-Specific Information:</h3> <p>
1494     *
1495     * Up to and including 1.7.2, HSQLDB does not support the ANSI92
1496     * full SQL grammar; this method always returns
1497     * <code>false</code>.
1498     * </div>
1499     * <!-- end release-specific documentation -->
1500     * @return <code>true</code> if so; <code>false</code> otherwise
1501     * @exception SQLException if a database access error occurs
1502     */

1503    public boolean supportsANSI92FullSQL() throws SQLException JavaDoc {
1504        return false;
1505    }
1506
1507// fredt@users 20030413 - return value change to support OpenOffice.org
1508

1509    /**
1510     * Retrieves whether this database supports the SQL Integrity
1511     * Enhancement Facility. <p>
1512     *
1513     * <!-- start release-specific documentation -->
1514     * <div class="ReleaseSpecificDocumentation">
1515     * <h3>HSQLDB-Specific Information:</h3> <p>
1516     *
1517     * From 1.7.2, this method always returns
1518     * <code>true</code>.
1519     * </div>
1520     * <!-- end release-specific documentation -->
1521     * @return <code>true</code> if so; <code>false</code> otherwise
1522     * @exception SQLException if a database access error occurs
1523     */

1524    public boolean supportsIntegrityEnhancementFacility()
1525    throws SQLException JavaDoc {
1526        return true;
1527    }
1528
1529    /**
1530     * Retrieves whether this database supports some form of outer join. <p>
1531     *
1532     * <!-- start release-specific documentation -->
1533     * <div class="ReleaseSpecificDocumentation">
1534     * <h3>HSQLDB-Specific Information:</h3> <p>
1535     *
1536     * HSQLDB supports outer joins; this method always returns
1537     * <code>true</code>.
1538     * </div>
1539     * <!-- end release-specific documentation -->
1540     *
1541     *
1542     * @return <code>true</code> if so; <code>false</code> otherwise
1543     * @exception SQLException if a database access error occurs
1544     */

1545    public boolean supportsOuterJoins() throws SQLException JavaDoc {
1546        return true;
1547    }
1548
1549    /**
1550     * Retrieves whether this database supports full nested outer joins. <p>
1551     *
1552     * <!-- start release-specific documentation -->
1553     * <div class="ReleaseSpecificDocumentation">
1554     * <h3>HSQLDB-Specific Information:</h3> <p>
1555     *
1556     * Up to and including 1.7.2, HSQLDB does not support full nested outer
1557     * joins; this method always returns <code>false</code>. <p>
1558     *
1559     * This behaviour may change in a future release.
1560     * </div>
1561     * <!-- end release-specific documentation -->
1562     * @return <code>true</code> if so; <code>false</code> otherwise
1563     * @exception SQLException if a database access error occurs
1564     */

1565    public boolean supportsFullOuterJoins() throws SQLException JavaDoc {
1566        return false;
1567    }
1568
1569    /**
1570     * Retrieves whether this database provides limited support for outer
1571     * joins. (This will be <code>true</code> if the method
1572     * <code>supportsFullOuterJoins</code> returns <code>true</code>). <p>
1573     *
1574     * <!-- start release-specific documentation -->
1575     * <div class="ReleaseSpecificDocumentation">
1576     * <h3>HSQLDB-Specific Information:</h3> <p>
1577     *
1578     * Up to and including 1.7.2, HSQLDB support the LEFT OUTER join syntax;
1579     * this method always returns <code>true</code>.
1580     * </div>
1581     * <!-- end release-specific documentation -->
1582     * @return <code>true</code> if so; <code>false</code> otherwise
1583     * @exception SQLException if a database access error occurs
1584     */

1585    public boolean supportsLimitedOuterJoins() throws SQLException JavaDoc {
1586        return true;
1587    }
1588
1589    /**
1590     * Retrieves the database vendor's preferred term for "schema". <p>
1591     *
1592     * <!-- start release-specific documentation -->
1593     * <div class="ReleaseSpecificDocumentation">
1594     * <h3>HSQLDB-Specific Information:</h3> <p>
1595     *
1596     * Starting with 1.8.0, HSQLDB provides support for schemas.
1597     * </div>
1598     * <!-- end release-specific documentation -->
1599     * @return the vendor term for "schema"
1600     * @exception SQLException if a database access error occurs
1601     */

1602    public String JavaDoc getSchemaTerm() throws SQLException JavaDoc {
1603        return "SCHEMA";
1604    }
1605
1606    /**
1607     * Retrieves the database vendor's preferred term for "procedure". <p>
1608     *
1609     * <!-- start release-specific documentation -->
1610     * <div class="ReleaseSpecificDocumentation">
1611     * <h3>HSQLDB-Specific Information:</h3> <p>
1612     *
1613     * Up to and including 1.7.2, HSQLDB does not support declaration of
1614     * functions or procedures directly in SQL but instead relies on the
1615     * HSQLDB-specific CLASS grant mechanism to make public static
1616     * Java methods available as SQL routines; this method always returns
1617     * an empty <code>String</code>.
1618     * </div>
1619     * <!-- end release-specific documentation -->
1620     * @return the vendor term for "procedure"
1621     * @exception SQLException if a database access error occurs
1622     */

1623    public String JavaDoc getProcedureTerm() throws SQLException JavaDoc {
1624        return "";
1625    }
1626
1627    /**
1628     * Retrieves the database vendor's preferred term for "catalog". <p>
1629     *
1630     * <!-- start release-specific documentation -->
1631     * <div class="ReleaseSpecificDocumentation">
1632     * <h3>HSQLDB-Specific Information:</h3> <p>
1633     *
1634     * Including 1.7.2, HSQLDB does not support catalogs in DDL or DML;
1635     * this method <ewm>always</em> returns the empty String.
1636     * </div>
1637     * <!-- end release-specific documentation -->
1638     *
1639     * @return the vendor term for "catalog"
1640     * @exception SQLException if a database access error occurs
1641     */

1642    public String JavaDoc getCatalogTerm() throws SQLException JavaDoc {
1643        return "";
1644    }
1645
1646    /**
1647     * Retrieves whether a catalog appears at the start of a fully qualified
1648     * table name. If not, the catalog appears at the end. <p>
1649     *
1650     * <!-- start release-specific documentation -->
1651     * <div class="ReleaseSpecificDocumentation">
1652     * <h3>HSQLDB-Specific Information:</h3> <p>
1653     *
1654     * Up to and including 1.7.2, HSQLDB does not support catalogs in DDL or DML;
1655     * this method always returns <code>false</code>.
1656     * </div>
1657     * <!-- end release-specific documentation -->
1658     * @return <code>true</code> if the catalog name appears at the beginning
1659     * of a fully qualified table name; <code>false</code> otherwise
1660     * @exception SQLException if a database access error occurs
1661     */

1662    public boolean isCatalogAtStart() throws SQLException JavaDoc {
1663        return false;
1664    }
1665
1666    /**
1667     * Retrieves the <code>String</code> that this database uses as the
1668     * separator between a catalog and table name. <p>
1669     *
1670     * <!-- start release-specific documentation -->
1671     * <div class="ReleaseSpecificDocumentation">
1672     * <h3>HSQLDB-Specific Information:</h3> <p>
1673     *
1674     * Including 1.7.2, HSQLDB does not support catalogs in DDL or DML;
1675     * this method <em>always</em> returns an empty <code>String</code>.
1676     * </div>
1677     * <!-- end release-specific documentation -->
1678     *
1679     * @return the separator string
1680     * @exception SQLException if a database access error occurs
1681     */

1682    public String JavaDoc getCatalogSeparator() throws SQLException JavaDoc {
1683        return "";
1684    }
1685
1686    /**
1687     * Retrieves whether a schema name can be used in a data
1688     * manipulation statement. <p>
1689     *
1690     * <!-- start release-specific documentation -->
1691     * <div class="ReleaseSpecificDocumentation">
1692     * <h3>HSQLDB-Specific Information:</h3> <p>
1693     *
1694     * In 1.8.0, HSQLDB supports schemas in table names but not in column names;
1695     * this method always returns <code>false</code>.
1696     *
1697     * </div>
1698     * <!-- end release-specific documentation -->
1699     * @return <code>true</code> if so; <code>false</code> otherwise
1700     * @exception SQLException if a database access error occurs
1701     */

1702    public boolean supportsSchemasInDataManipulation() throws SQLException JavaDoc {
1703
1704        // false for OOo client server compatibility
1705
// otherwise schema name is used by OOo in column references
1706
return false;
1707    }
1708
1709    /**
1710     * Retrieves whether a schema name can be used in a procedure call
1711     * statement. <p>
1712     *
1713     * <!-- start release-specific documentation -->
1714     * <div class="ReleaseSpecificDocumentation">
1715     * <h3>HSQLDB-Specific Information:</h3> <p>
1716     *
1717     * Up to and including 1.7.2, HSQLDB does not support schema-qualified
1718     * procedure identifiers; this method always returns <code>false</code>.
1719     * </div>
1720     * <!-- end release-specific documentation -->
1721     * @return <code>true</code> if so; <code>false</code> otherwise
1722     * @exception SQLException if a database access error occurs
1723     */

1724    public boolean supportsSchemasInProcedureCalls() throws SQLException JavaDoc {
1725        return false;
1726    }
1727
1728    /**
1729     * Retrieves whether a schema name can be used in a table
1730     * definition statement. <p>
1731     *
1732     * <!-- start release-specific documentation -->
1733     * <div class="ReleaseSpecificDocumentation">
1734     * <h3>HSQLDB-Specific Information:</h3> <p>
1735     *
1736     * In 1.8.0, HSQLDB supports schemas;
1737     * this method always returns <code>true</code>.
1738     *
1739     * </div>
1740     * <!-- end release-specific documentation -->
1741     * @return <code>true</code> if so; <code>false</code> otherwise
1742     * @exception SQLException if a database access error occurs
1743     */

1744    public boolean supportsSchemasInTableDefinitions() throws SQLException JavaDoc {
1745        return !useSchemaDefault;
1746    }
1747
1748    /**
1749     * Retrieves whether a schema name can be used in an index
1750     * definition statement. <p>
1751     *
1752     * <!-- start release-specific documentation -->
1753     * <div class="ReleaseSpecificDocumentation">
1754     * <h3>HSQLDB-Specific Information:</h3> <p>
1755     *
1756     * In 1.8.0, HSQLDB supports schemas;
1757     * this method always returns <code>true</code>.
1758     *
1759     * </div>
1760     * <!-- end release-specific documentation -->
1761     * @return <code>true</code> if so; <code>false</code> otherwise
1762     * @exception SQLException if a database access error occurs
1763     */

1764    public boolean supportsSchemasInIndexDefinitions() throws SQLException JavaDoc {
1765        return !useSchemaDefault;
1766    }
1767
1768    /**
1769     * Retrieves whether a schema name can be used in a privilege
1770     * definition statement. <p>
1771     *
1772     * <!-- start release-specific documentation -->
1773     * <div class="ReleaseSpecificDocumentation">
1774     * <h3>HSQLDB-Specific Information:</h3> <p>
1775     *
1776     * In 1.8.0, HSQLDB supports schemas;
1777     * this method always returns <code>true</code>.
1778     *
1779     * </div>
1780     * <!-- end release-specific documentation -->
1781     * @return <code>true</code> if so; <code>false</code> otherwise
1782     * @exception SQLException if a database access error occurs
1783     */

1784    public boolean supportsSchemasInPrivilegeDefinitions()
1785    throws SQLException JavaDoc {
1786        return !useSchemaDefault;
1787    }
1788
1789    /**
1790     * Retrieves whether a catalog name can be used in a data
1791     * manipulation statement. <p>
1792     *
1793     * <!-- start release-specific documentation -->
1794     * <div class="ReleaseSpecificDocumentation">
1795     * <h3>HSQLDB-Specific Information:</h3> <p>
1796     *
1797     * Up to and including 1.7.2, HSQLDB does not support catalog-qualified;
1798     * data manipulation; this method always returns <code>false</code>.
1799     * </div>
1800     * <!-- end release-specific documentation -->
1801     * @return <code>true</code> if so; <code>false</code> otherwise
1802     * @exception SQLException if a database access error occurs
1803     */

1804    public boolean supportsCatalogsInDataManipulation() throws SQLException JavaDoc {
1805        return false;
1806    }
1807
1808    /**
1809     * Retrieves whether a catalog name can be used in a
1810     * procedure call statement. <p>
1811     *
1812     * <!-- start release-specific documentation -->
1813     * <div class="ReleaseSpecificDocumentation">
1814     * <h3>HSQLDB-Specific Information:</h3> <p>
1815     *
1816     * Up to and including 1.7.2, HSQLDB does not support catalog-qualified
1817     * procedure calls; this method always returns <code>false</code>.
1818     * </div>
1819     * <!-- end release-specific documentation -->
1820     * @return <code>true</code> if so; <code>false</code> otherwise
1821     * @exception SQLException if a database access error occurs
1822     */

1823    public boolean supportsCatalogsInProcedureCalls() throws SQLException JavaDoc {
1824        return false;
1825    }
1826
1827    /**
1828     * Retrieves whether a catalog name can be used in a
1829     * table definition statement. <p>
1830     *
1831     * <!-- start release-specific documentation -->
1832     * <div class="ReleaseSpecificDocumentation">
1833     * <h3>HSQLDB-Specific Information:</h3> <p>
1834     *
1835     * Up to and including 1.7.2, HSQLDB does not support catalog-qualified
1836     * table definitions; this method always returns <code>false</code>.
1837     * </div>
1838     * <!-- end release-specific documentation -->
1839     * @return <code>true</code> if so; <code>false</code> otherwise
1840     * @exception SQLException if a database access error occurs
1841     */

1842    public boolean supportsCatalogsInTableDefinitions() throws SQLException JavaDoc {
1843        return false;
1844    }
1845
1846    /**
1847     * Retrieves whether a catalog name can be used in an
1848     * index definition statement. <p>
1849     *
1850     * <!-- start release-specific documentation -->
1851     * <div class="ReleaseSpecificDocumentation">
1852     * <h3>HSQLDB-Specific Information:</h3> <p>
1853     *
1854     * Up to and including 1.7.2, HSQLDB does not support catalog-qualified
1855     * index definitions; this method always returns <code>false</code>.
1856     * </div>
1857     * <!-- end release-specific documentation -->
1858     * @return <code>true</code> if so; <code>false</code> otherwise
1859     * @exception SQLException if a database access error occurs
1860     */

1861    public boolean supportsCatalogsInIndexDefinitions() throws SQLException JavaDoc {
1862        return false;
1863    }
1864
1865    /**
1866     * Retrieves whether a catalog name can be used in a
1867     * privilege definition statement. <p>
1868     *
1869     * <!-- start release-specific documentation -->
1870     * <div class="ReleaseSpecificDocumentation">
1871     * <h3>HSQLDB-Specific Information:</h3> <p>
1872     *
1873     * Up to and including 1.7.2, HSQLDB does not support catalog-qualified
1874     * privilege definitions; this method always returns <code>false</code>.
1875     * </div>
1876     * <!-- end release-specific documentation -->
1877     * @return <code>true</code> if so; <code>false</code> otherwise
1878     * @exception SQLException if a database access error occurs
1879     */

1880    public boolean supportsCatalogsInPrivilegeDefinitions()
1881    throws SQLException JavaDoc {
1882        return false;
1883    }
1884
1885    /**
1886     * Retrieves whether this database supports positioned <code>DELETE</code>
1887     * statements. <p>
1888     *
1889     * <!-- start release-specific documentation -->
1890     * <div class="ReleaseSpecificDocumentation">
1891     * <h3>HSQLDB-Specific Information:</h3> <p>
1892     *
1893     * Up to and including 1.7.2, HSQLDB does not support updateable
1894     * result sets; this method always returns <code>false</code>.
1895     * </div>
1896     * <!-- end release-specific documentation -->
1897     * @return <code>true</code> if so; <code>false</code> otherwise
1898     * @exception SQLException if a database access error occurs
1899     */

1900    public boolean supportsPositionedDelete() throws SQLException JavaDoc {
1901        return false;
1902    }
1903
1904    /**
1905     * Retrieves whether this database supports positioned <code>UPDATE</code>
1906     * statements. <p>
1907     *
1908     * <!-- start release-specific documentation -->
1909     * <div class="ReleaseSpecificDocumentation">
1910     * <h3>HSQLDB-Specific Information:</h3> <p>
1911     *
1912     * Up to and including 1.7.2, HSQLDB does not support updateable
1913     * result sets; this method always returns <code>false</code>.
1914     * </div>
1915     * <!-- end release-specific documentation -->
1916     * @return <code>true</code> if so; <code>false</code> otherwise
1917     * @exception SQLException if a database access error occurs
1918     */

1919    public boolean supportsPositionedUpdate() throws SQLException JavaDoc {
1920        return false;
1921    }
1922
1923    /**
1924     * Retrieves whether this database supports <code>SELECT FOR UPDATE</code>
1925     * statements. <p>
1926     *
1927     * <!-- start release-specific documentation -->
1928     * <div class="ReleaseSpecificDocumentation">
1929     * <h3>HSQLDB-Specific Information:</h3> <p>
1930     *
1931     * Up to and including 1.7.2, HSQLDB does not support explicit locking;
1932     * this method always returns <code>false</code>.
1933     * </div>
1934     * <!-- end release-specific documentation -->
1935     * @return <code>true</code> if so; <code>false</code> otherwise
1936     * @exception SQLException if a database access error occurs
1937     */

1938    public boolean supportsSelectForUpdate() throws SQLException JavaDoc {
1939        return false;
1940    }
1941
1942    /**
1943     * Retrieves whether this database supports stored procedure calls
1944     * that use the stored procedure escape syntax. <p>
1945     *
1946     * <!-- start release-specific documentation -->
1947     * <div class="ReleaseSpecificDocumentation">
1948     * <h3>HSQLDB-Specific Information:</h3> <p>
1949     *
1950     * Up to and including 1.7.2, HSQLDB supports calling public static
1951     * Java methods in the context of SQL Stored Procedures; this method
1952     * always returns <code>true</code>.
1953     * </div>
1954     * <!-- end release-specific documentation -->
1955     * @return <code>true</code> if so; <code>false</code> otherwise
1956     * @exception SQLException if a database access error occurs
1957     * @see jdbcPreparedStatement
1958     * @see jdbcConnection#prepareCall
1959     */

1960    public boolean supportsStoredProcedures() throws SQLException JavaDoc {
1961        return true;
1962    }
1963
1964    /**
1965     * Retrieves whether this database supports subqueries in comparison
1966     * expressions. <p>
1967     *
1968     * <!-- start release-specific documentation -->
1969     * <div class="ReleaseSpecificDocumentation">
1970     * <h3>HSQLDB-Specific Information:</h3> <p>
1971     *
1972     * HSQLDB has always supported subqueries in comparison expressions;
1973     * this method always returns <code>true</code>.
1974     * </div>
1975     * <!-- end release-specific documentation -->
1976     *
1977     *
1978     * @return <code>true</code> if so; <code>false</code> otherwise
1979     * @exception SQLException if a database access error occurs
1980     */

1981    public boolean supportsSubqueriesInComparisons() throws SQLException JavaDoc {
1982        return true;
1983    }
1984
1985    /**
1986     * Retrieves whether this database supports subqueries in
1987     * <code>EXISTS</code> expressions. <p>
1988     *
1989     * <!-- start release-specific documentation -->
1990     * <div class="ReleaseSpecificDocumentation">
1991     * <h3>HSQLDB-Specific Information:</h3> <p>
1992     *
1993     * HSQLDB has always supported subqueries in <code>EXISTS</code>
1994     * expressions; this method always returns <code>true</code>.
1995     * </div>
1996     * <!-- end release-specific documentation -->
1997     *
1998     *
1999     * @return <code>true</code> if so; <code>false</code> otherwise
2000     * @exception SQLException if a database access error occurs
2001     */

2002    public boolean supportsSubqueriesInExists() throws SQLException JavaDoc {
2003        return true;
2004    }
2005
2006    /**
2007     * JDBC4 correction: Retrieves whether this database supports subqueries in
2008     * <code>IN</code> expressions. <p>
2009     *
2010     * <!-- start release-specific documentation -->
2011     * <div class="ReleaseSpecificDocumentation">
2012     * <h3>HSQLDB-Specific Information:</h3> <p>
2013     *
2014     * HSQLDB has always supported subqueries in <code>IN</code>
2015     * statements; this method always returns <code>true</code>.
2016     * </div>
2017     * <!-- end release-specific documentation -->
2018     *
2019     *
2020     * @return <code>true</code> if so; <code>false</code> otherwise
2021     * @exception SQLException if a database access error occurs
2022     */

2023    public boolean supportsSubqueriesInIns() throws SQLException JavaDoc {
2024        return true;
2025    }
2026
2027    /**
2028     * Retrieves whether this database supports subqueries in quantified
2029     * expressions. <p>
2030     *
2031     * <!-- start release-specific documentation -->
2032     * <div class="ReleaseSpecificDocumentation">
2033     * <h3>HSQLDB-Specific Information:</h3> <p>
2034     *
2035     * HSQLDB has always supported subqueries in quantified
2036     * expressions; this method always returns <code>true</code>.
2037     * </div>
2038     * <!-- end release-specific documentation -->
2039     *
2040     *
2041     * @return <code>true</code> if so; <code>false</code> otherwise
2042     * @exception SQLException if a database access error occurs
2043     */

2044    public boolean supportsSubqueriesInQuantifieds() throws SQLException JavaDoc {
2045        return true;
2046    }
2047
2048    /**
2049     * Retrieves whether this database supports correlated subqueries. <p>
2050     *
2051     * <!-- start release-specific documentation -->
2052     * <div class="ReleaseSpecificDocumentation">
2053     * <h3>HSQLDB-Specific Information:</h3> <p>
2054     *
2055     * HSQLDB has always supported correlated subqueries;
2056     * this method always returns <code>true</code>.
2057     * </div>
2058     * <!-- end release-specific documentation -->
2059     *
2060     *
2061     * @return <code>true</code> if so; <code>false</code> otherwise
2062     * @exception SQLException if a database access error occurs
2063     */

2064    public boolean supportsCorrelatedSubqueries() throws SQLException JavaDoc {
2065        return true;
2066    }
2067
2068    /**
2069     * Retrieves whether this database supports SQL <code>UNION</code>. <p>
2070     *
2071     * <!-- start release-specific documentation -->
2072     * <div class="ReleaseSpecificDocumentation">
2073     * <h3>HSQLDB-Specific Information:</h3> <p>
2074     *
2075     * HSQLDB supports SQL <code>UNION</code>;
2076     * this method always returns <code>true</code>.
2077     * </div>
2078     * <!-- end release-specific documentation -->
2079     *
2080     *
2081     * @return <code>true</code> if so; <code>false</code> otherwise
2082     * @exception SQLException if a database access error occurs
2083     */

2084    public boolean supportsUnion() throws SQLException JavaDoc {
2085        return true;
2086    }
2087
2088    /**
2089     * Retrieves whether this database supports SQL <code>UNION ALL</code>. <p>
2090     *
2091     * <!-- start release-specific documentation -->
2092     * <div class="ReleaseSpecificDocumentation">
2093     * <h3>HSQLDB-Specific Information:</h3> <p>
2094     *
2095     * HSQLDB supports SQL <code>UNION ALL</code>;
2096     * this method always returns <code>true</code>.
2097     * </div>
2098     * <!-- end release-specific documentation -->
2099     *
2100     *
2101     * @return <code>true</code> if so; <code>false</code> otherwise
2102     * @exception SQLException if a database access error occurs
2103     */

2104    public boolean supportsUnionAll() throws SQLException JavaDoc {
2105        return true;
2106    }
2107
2108    /**
2109     * Retrieves whether this database supports keeping cursors open
2110     * across commits. <p>
2111     *
2112     * <!-- start release-specific documentation -->
2113     * <div class="ReleaseSpecificDocumentation">
2114     * <h3>HSQLDB-Specific Information:</h3> <p>
2115     *
2116     * Up to and including 1.7.2, HSQLDB does not support keeping
2117     * cursors open across commits; this method always returns
2118     * <code>false</code>.
2119     * </div>
2120     * <!-- end release-specific documentation -->
2121     * @return <code>true</code> if cursors always remain open;
2122     * <code>false</code> if they might not remain open
2123     * @exception SQLException if a database access error occurs
2124     */

2125    public boolean supportsOpenCursorsAcrossCommit() throws SQLException JavaDoc {
2126        return false;
2127    }
2128
2129    /**
2130     * Retrieves whether this database supports keeping cursors open
2131     * across rollbacks. <p>
2132     *
2133     * <!-- start release-specific documentation -->
2134     * <div class="ReleaseSpecificDocumentation">
2135     * <h3>HSQLDB-Specific Information:</h3> <p>
2136     *
2137     * Up to and including 1.7.2, HSQLDB does not support keeping
2138     * cursors open across rollbacks;
2139     * this method always returns <code>false</code>.
2140     * </div>
2141     * <!-- end release-specific documentation -->
2142     * @return <code>true</code> if cursors always remain open;
2143     * <code>false</code> if they might not remain open
2144     * @exception SQLException if a database access error occurs
2145     */

2146    public boolean supportsOpenCursorsAcrossRollback() throws SQLException JavaDoc {
2147        return false;
2148    }
2149
2150    /**
2151     * Retrieves whether this database supports keeping statements open
2152     * across commits. <p>
2153     *
2154     * <!-- start release-specific documentation -->
2155     * <div class="ReleaseSpecificDocumentation">
2156     * <h3>HSQLDB-Specific Information:</h3> <p>
2157     *
2158     * HSQLDB supports keeping statements open
2159     * across commits;
2160     * this method always returns <code>true</code>.
2161     * </div>
2162     * <!-- end release-specific documentation -->
2163     *
2164     *
2165     * @return <code>true</code> if statements always remain open;
2166     * <code>false</code> if they might not remain open
2167     * @exception SQLException if a database access error occurs
2168     */

2169    public boolean supportsOpenStatementsAcrossCommit() throws SQLException JavaDoc {
2170        return true;
2171    }
2172
2173    /**
2174     * Retrieves whether this database supports keeping statements open
2175     * across rollbacks. <p>
2176     *
2177     * <!-- start release-specific documentation -->
2178     * <div class="ReleaseSpecificDocumentation">
2179     * <h3>HSQLDB-Specific Information:</h3> <p>
2180     *
2181     * HSQLDB supports keeping statements open
2182     * across commits;
2183     * this method always returns <code>true</code>.
2184     * </div>
2185     * <!-- end release-specific documentation -->
2186     *
2187     *
2188     * @return <code>true</code> if statements always remain open;
2189     * <code>false</code> if they might not remain open
2190     * @exception SQLException if a database access error occurs
2191     */

2192    public boolean supportsOpenStatementsAcrossRollback()
2193    throws SQLException JavaDoc {
2194        return true;
2195    }
2196
2197    //----------------------------------------------------------------------
2198
// The following group of methods exposes various limitations
2199
// based on the target database with the current driver.
2200
// Unless otherwise specified, a result of zero means there is no
2201
// limit, or the limit is not known.
2202

2203    /**
2204     * Retrieves the maximum number of hex characters this database allows in an
2205     * inline binary literal. <p>
2206     *
2207     * <!-- start release-specific documentation -->
2208     * <div class="ReleaseSpecificDocumentation">
2209     * <h3>HSQLDB-Specific Information:</h3> <p>
2210     *
2211     * HSQLDB does not impose a "known" limit. The hard limit is the maximum
2212     * length of a java.lang.String (java.lang.Integer.MAX_VALUE);
2213     * this method always returns <code>0</code>.
2214     * </div>
2215     * <!-- end release-specific documentation -->
2216     *
2217     *
2218     * @return max the maximum length (in hex characters) for a binary literal;
2219     * a result of zero means that there is no limit or the limit
2220     * is not known
2221     * @exception SQLException if a database access error occurs
2222     */

2223    public int getMaxBinaryLiteralLength() throws SQLException JavaDoc {
2224
2225        // hard limit is Integer.MAX_VALUE
2226
return 0;
2227    }
2228
2229    /**
2230     * Retrieves the maximum number of characters this database allows
2231     * for a character literal. <p>
2232     *
2233     * <!-- start release-specific documentation -->
2234     * <div class="ReleaseSpecificDocumentation">
2235     * <h3>HSQLDB-Specific Information:</h3> <p>
2236     *
2237     * HSQLDB does not impose a "known" limit. The hard limit is the maximum
2238     * length of a java.lang.String (java.lang.Integer.MAX_VALUE);
2239     * this method always returns <code>0</code>.
2240     * </div>
2241     * <!-- end release-specific documentation -->
2242     *
2243     * @return the maximum number of characters allowed for a character literal;
2244     * a result of zero means that there is no limit or the limit is
2245     * not known
2246     * @exception SQLException if a database access error occurs
2247     */

2248    public int getMaxCharLiteralLength() throws SQLException JavaDoc {
2249
2250        // hard limit is Integer.MAX_VALUE
2251
return 0;
2252    }
2253
2254    /**
2255     * Retrieves the maximum number of characters this database allows
2256     * for a column name. <p>
2257     *
2258     * <!-- start release-specific documentation -->
2259     * <div class="ReleaseSpecificDocumentation">
2260     * <h3>HSQLDB-Specific Information:</h3> <p>
2261     *
2262     * HSQLDB does not impose a "known" limit. The hard limit is the maximum
2263     * length of a java.lang.String (java.lang.Integer.MAX_VALUE);
2264     * this method always returns <code>0</code>.
2265     * </div>
2266     * <!-- end release-specific documentation -->
2267     *
2268     * @return the maximum number of characters allowed for a column name;
2269     * a result of zero means that there is no limit or the limit
2270     * is not known
2271     * @exception SQLException if a database access error occurs
2272     */

2273    public int getMaxColumnNameLength() throws SQLException JavaDoc {
2274
2275        // hard limit is Integer.MAX_VALUE
2276
return 0;
2277    }
2278
2279    /**
2280     * Retrieves the maximum number of columns this database allows in a
2281     * <code>GROUP BY</code> clause. <p>
2282     *
2283     * <!-- start release-specific documentation -->
2284     * <div class="ReleaseSpecificDocumentation">
2285     * <h3>HSQLDB-Specific Information:</h3> <p>
2286     *
2287     * HSQLDB does not impose a "known" limit. The hard limit is the maximum
2288     * length of a Java array (java.lang.Integer.MAX_VALUE);
2289     * this method always returns <code>0</code>.
2290     * </div>
2291     * <!-- end release-specific documentation -->
2292     *
2293     * @return the maximum number of columns allowed;
2294     * a result of zero means that there is no limit or the limit
2295     * is not known
2296     * @exception SQLException if a database access error occurs
2297     */

2298    public int getMaxColumnsInGroupBy() throws SQLException JavaDoc {
2299
2300        // hard limit is Integer.MAX_VALUE
2301
return 0;
2302    }
2303
2304    /**
2305     * Retrieves the maximum number of columns this database allows in
2306     * an index. <p>
2307     *
2308     * <!-- start release-specific documentation -->
2309     * <div class="ReleaseSpecificDocumentation">
2310     * <h3>HSQLDB-Specific Information:</h3> <p>
2311     *
2312     * HSQLDB does not impose a "known" limit. The hard limit is the maximum
2313     * length of a Java array (java.lang.Integer.MAX_VALUE);
2314     * this method always returns <code>0</code>.
2315     * </div>
2316     * <!-- end release-specific documentation -->
2317     *
2318     * @return the maximum number of columns allowed;
2319     * a result of zero means that there is no limit or the limit
2320     * is not known
2321     * @exception SQLException if a database access error occurs
2322     */

2323    public int getMaxColumnsInIndex() throws SQLException JavaDoc {
2324
2325        // hard limit is Integer.MAX_VALUE
2326
return 0;
2327    }
2328
2329    /**
2330     * Retrieves the maximum number of columns this database allows in an
2331     * <code>ORDER BY</code> clause. <p>
2332     *
2333     * <!-- start release-specific documentation -->
2334     * <div class="ReleaseSpecificDocumentation">
2335     * <h3>HSQLDB-Specific Information:</h3> <p>
2336     *
2337     * HSQLDB does not impose a "known" limit. The hard limit is the maximum
2338     * length of a Java array (java.lang.Integer.MAX_VALUE);
2339     * this method always returns <code>0</code>.
2340     * </div>
2341     * <!-- end release-specific documentation -->
2342     *
2343     * @return the maximum number of columns allowed;
2344     * a result of zero means that there is no limit or the limit
2345     * is not known
2346     * @exception SQLException if a database access error occurs
2347     */

2348    public int getMaxColumnsInOrderBy() throws SQLException JavaDoc {
2349
2350        // hard limit is Integer.MAX_VALUE
2351
return 0;
2352    }
2353
2354    /**
2355     * Retrieves the maximum number of columns this database allows in a
2356     * <code>SELECT</code> list. <p>
2357     *
2358     * <!-- start release-specific documentation -->
2359     * <div class="ReleaseSpecificDocumentation">
2360     * <h3>HSQLDB-Specific Information:</h3> <p>
2361     *
2362     * HSQLDB does not impose a "known" limit. The hard limit is the maximum
2363     * length of a Java array (java.lang.Integer.MAX_VALUE);
2364     * this method always returns <code>0</code>.
2365     * </div>
2366     * <!-- end release-specific documentation -->
2367     *
2368     * @return the maximum number of columns allowed;
2369     * a result of zero means that there is no limit or the limit
2370     * is not known
2371     * @exception SQLException if a database access error occurs
2372     */

2373    public int getMaxColumnsInSelect() throws SQLException JavaDoc {
2374
2375        // hard limit is Integer.MAX_VALUE
2376
return 0;
2377    }
2378
2379    /**
2380     * Retrieves the maximum number of columns this database allows in
2381     * a table. <p>
2382     *
2383     * <!-- start release-specific documentation -->
2384     * <div class="ReleaseSpecificDocumentation">
2385     * <h3>HSQLDB-Specific Information:</h3> <p>
2386     *
2387     * HSQLDB does not impose a "known" limit. The hard limit is the maximum
2388     * length of a Java array (java.lang.Integer.MAX_VALUE);
2389     * this method always returns <code>0</code>.
2390     * </div>
2391     * <!-- end release-specific documentation -->
2392     *
2393     * @return the maximum number of columns allowed;
2394     * a result of zero means that there is no limit or the limit
2395     * is not known
2396     * @exception SQLException if a database access error occurs
2397     */

2398    public int getMaxColumnsInTable() throws SQLException JavaDoc {
2399
2400        // hard limit is Integer.MAX_VALUE
2401
return 0;
2402    }
2403
2404    /**
2405     * Retrieves the maximum number of concurrent connections to this
2406     * database that are possible. <p>
2407     *
2408     * <!-- start release-specific documentation -->
2409     * <div class="ReleaseSpecificDocumentation">
2410     * <h3>HSQLDB-Specific Information:</h3> <p>
2411     *
2412     * HSQLDB does not impose a "known" limit. The hard limit is the maximum
2413     * length of a Java array (java.lang.Integer.MAX_VALUE);
2414     * this method always returns <code>0</code>.
2415     * </div>
2416     * <!-- end release-specific documentation -->
2417     *
2418     * @return the maximum number of active connections possible at one time;
2419     * a result of zero means that there is no limit or the limit
2420     * is not known
2421     * @exception SQLException if a database access error occurs
2422     */

2423    public int getMaxConnections() throws SQLException JavaDoc {
2424
2425        // hard limit is (probably) Integer.MAX_VALUE
2426
return 0;
2427    }
2428
2429    /**
2430     * Retrieves the maximum number of characters that this database allows in a
2431     * cursor name. <p>
2432     *
2433     * <!-- start release-specific documentation -->
2434     * <div class="ReleaseSpecificDocumentation">
2435     * <h3>HSQLDB-Specific Information:</h3> <p>
2436     *
2437     * HSQLDB does not impose a "known" limit. The hard limit is the maximum
2438     * length of a java.lang.String (java.lang.Integer.MAX_VALUE);
2439     * this method always returns <code>0</code>.
2440     * </div>
2441     * <!-- end release-specific documentation -->
2442     *
2443     * @return the maximum number of characters allowed in a cursor name;
2444     * a result of zero means that there is no limit or the limit
2445     * is not known
2446     * @exception SQLException if a database access error occurs
2447     */

2448    public int getMaxCursorNameLength() throws SQLException JavaDoc {
2449        return 0;
2450    }
2451
2452    /**
2453     * Retrieves the maximum number of bytes this database allows for an
2454     * index, including all of the parts of the index. <p>
2455     *
2456     * <!-- start release-specific documentation -->
2457     * <div class="ReleaseSpecificDocumentation">
2458     * <h3>HSQLDB-Specific Information:</h3> <p>
2459     *
2460     * HSQLDB does not impose a "known" limit;
2461     * this method always returns <code>0</code>.
2462     * </div>
2463     * <!-- end release-specific documentation -->
2464     *
2465     * @return the maximum number of bytes allowed; this limit includes the
2466     * composite of all the constituent parts of the index;
2467     * a result of zero means that there is no limit or the limit
2468     * is not known
2469     * @exception SQLException if a database access error occurs
2470     */

2471    public int getMaxIndexLength() throws SQLException JavaDoc {
2472        return 0;
2473    }
2474
2475    /**
2476     * Retrieves the maximum number of characters that this database allows in a
2477     * schema name. <p>
2478     *
2479     * <!-- start release-specific documentation -->
2480     * <div class="ReleaseSpecificDocumentation">
2481     * <h3>HSQLDB-Specific Information:</h3> <p>
2482     *
2483     * 1.8.0 supports schema names with no known limit imposed,
2484     * so this method always returns <code>0</code>.
2485     * </div>
2486     * <!-- end release-specific documentation -->
2487     * @return the maximum number of characters allowed in a schema name;
2488     * a result of zero means that there is no limit or the limit
2489     * is not known
2490     * @exception SQLException if a database access error occurs
2491     */

2492    public int getMaxSchemaNameLength() throws SQLException JavaDoc {
2493        return 0;
2494    }
2495
2496    /**
2497     * Retrieves the maximum number of characters that this database allows in a
2498     * procedure name. <p>
2499     *
2500     * <!-- start release-specific documentation -->
2501     * <div class="ReleaseSpecificDocumentation">
2502     * <h3>HSQLDB-Specific Information:</h3> <p>
2503     *
2504     * HSQLDB does not impose a "known" limit. The hard limit is the maximum
2505     * length of a java.lang.String (java.lang.Integer.MAX_VALUE);
2506     * this method always returns <code>0</code>.
2507     * </div>
2508     * <!-- end release-specific documentation -->
2509     *
2510     * @return the maximum number of characters allowed in a procedure name;
2511     * a result of zero means that there is no limit or the limit
2512     * is not known
2513     * @exception SQLException if a database access error occurs
2514     */

2515    public int getMaxProcedureNameLength() throws SQLException JavaDoc {
2516        return 0;
2517    }
2518
2519    /**
2520     * Retrieves the maximum number of characters that this database allows in a
2521     * catalog name. <p>
2522     *
2523     * <!-- start release-specific documentation -->
2524     * <div class="ReleaseSpecificDocumentation">
2525     * <h3>HSQLDB-Specific Information:</h3> <p>
2526     *
2527     * Up to and including 1.7.2, HSQLDB does not support catalogs in
2528     * DDL or DML; this method always returns <code>0</code>.
2529     * </div>
2530     * <!-- end release-specific documentation -->
2531     *
2532     * @return the maximum number of characters allowed in a catalog name;
2533     * a result of zero means that there is no limit or the limit
2534     * is not known
2535     * @exception SQLException if a database access error occurs
2536     */

2537    public int getMaxCatalogNameLength() throws SQLException JavaDoc {
2538        return 0;
2539    }
2540
2541    /**
2542     * Retrieves the maximum number of bytes this database allows in
2543     * a single row. <p>
2544     *
2545     * <!-- start release-specific documentation -->
2546     * <div class="ReleaseSpecificDocumentation">
2547     * <h3>HSQLDB-Specific Information:</h3> <p>
2548     *
2549     * HSQLDB does not impose a "known" limit;
2550     * this method always returns <code>0</code>.
2551     * </div>
2552     * <!-- end release-specific documentation -->
2553     *
2554     * @return the maximum number of bytes allowed for a row; a result of
2555     * zero means that there is no limit or the limit is not known
2556     * @exception SQLException if a database access error occurs
2557     */

2558    public int getMaxRowSize() throws SQLException JavaDoc {
2559        return 0;
2560    }
2561
2562    /**
2563     * Retrieves whether the return value for the method
2564     * <code>getMaxRowSize</code> includes the SQL data types
2565     * <code>LONGVARCHAR</code> and <code>LONGVARBINARY</code>. <p>
2566     *
2567     * <!-- start release-specific documentation -->
2568     * <div class="ReleaseSpecificDocumentation">
2569     * <h3>HSQLDB-Specific Indormation:</h3><p>
2570     *
2571     * Including 1.7.2, {@link #getMaxRowSize} <em>always</em> returns
2572     * 0, indicating that the maximum row size is unknown or has no limit.
2573     * This applies to the above types as well; this method <em>always</em>
2574     * returns <code>true</code>.
2575     * </div>
2576     * <!-- end release-specific documentation -->
2577     *
2578     *
2579     * @return <code>true</code> if so; <code>false</code> otherwise
2580     * @exception SQLException if a database access error occurs
2581     */

2582    public boolean doesMaxRowSizeIncludeBlobs() throws SQLException JavaDoc {
2583        return true;
2584    }
2585
2586    /**
2587     * Retrieves the maximum number of characters this database allows in
2588     * an SQL statement. <p>
2589     *
2590     * <!-- start release-specific documentation -->
2591     * <div class="ReleaseSpecificDocumentation">
2592     * <h3>HSQLDB-Specific Information:</h3> <p>
2593     *
2594     * HSQLDB does not impose a "known" limit. The hard limit is the maximum
2595     * length of a java.lang.String (java.lang.Integer.MAX_VALUE);
2596     * this method always returns <code>0</code>.
2597     * </div>
2598     * <!-- end release-specific documentation -->
2599     *
2600     * @return the maximum number of characters allowed for an SQL statement;
2601     * a result of zero means that there is no limit or the limit
2602     * is not known
2603     * @exception SQLException if a database access error occurs
2604     */

2605    public int getMaxStatementLength() throws SQLException JavaDoc {
2606        return 0;
2607    }
2608
2609    /**
2610     * Retrieves the maximum number of active statements to this database
2611     * that can be open at the same time. <p>
2612     *
2613     * <!-- start release-specific documentation -->
2614     * <div class="ReleaseSpecificDocumentation">
2615     * <h3>HSQLDB-Specific Information:</h3> <p>
2616     *
2617     * HSQLDB does not impose a "known" limit;
2618     * this method always returns <code>0</code>.
2619     * </div>
2620     * <!-- end release-specific documentation -->
2621     *
2622     * @return the maximum number of statements that can be open at one time;
2623     * a result of zero means that there is no limit or the limit
2624     * is not known
2625     * @exception SQLException if a database access error occurs
2626     */

2627    public int getMaxStatements() throws SQLException JavaDoc {
2628        return 0;
2629    }
2630
2631    /**
2632     * Retrieves the maximum number of characters this database allows in
2633     * a table name. <p>
2634     *
2635     * <!-- start release-specific documentation -->
2636     * <div class="ReleaseSpecificDocumentation">
2637     * <h3>HSQLDB-Specific Information:</h3> <p>
2638     *
2639     * HSQLDB does not impose a "known" limit. The hard limit is the maximum
2640     * length of a java.lang.String (java.lang.Integer.MAX_VALUE);
2641     * this method always returns <code>0</code>.
2642     * </div>
2643     * <!-- end release-specific documentation -->
2644     *
2645     * @return the maximum number of characters allowed for a table name;
2646     * a result of zero means that there is no limit or the limit
2647     * is not known
2648     * @exception SQLException if a database access error occurs
2649     */

2650    public int getMaxTableNameLength() throws SQLException JavaDoc {
2651        return 0;
2652    }
2653
2654    /**
2655     * Retrieves the maximum number of tables this database allows in a
2656     * <code>SELECT</code> statement. <p>
2657     *
2658     * <!-- start release-specific documentation -->
2659     * <div class="ReleaseSpecificDocumentation">
2660     * <h3>HSQLDB-Specific Information:</h3> <p>
2661     *
2662     * HSQLDB does not impose a "known" limit. The hard limit is the maximum
2663     * length of a Java array (java.lang.Integer.MAX_VALUE);
2664     * this method always returns <code>0</code>.
2665     * </div>
2666     * <!-- end release-specific documentation -->
2667     *
2668     * @return the maximum number of tables allowed in a <code>SELECT</code>
2669     * statement; a result of zero means that there is no limit or
2670     * the limit is not known
2671     * @exception SQLException if a database access error occurs
2672     */

2673    public int getMaxTablesInSelect() throws SQLException JavaDoc {
2674
2675        // - soft limit is >>> than will ever be seen in any real stmnt
2676
// - exists a fixed (non statement dependent) hard limit? No.
2677
// - depends totally on number of table idents that can fit in
2678
// Integer.MAX_VALUE characters, minus the rest of the stmnt
2679
return 0;
2680    }
2681
2682    /**
2683     * Retrieves the maximum number of characters this database allows in
2684     * a user name. <p>
2685     *
2686     * <!-- start release-specific documentation -->
2687     * <div class="ReleaseSpecificDocumentation">
2688     * <h3>HSQLDB-Specific Information:</h3> <p>
2689     *
2690     * HSQLDB does not impose a "known" limit. The hard limit is the maximum
2691     * length of a java.lang.String (java.lang.Integer.MAX_VALUE);
2692     * this method always returns <code>0</code>.
2693     * </div>
2694     * <!-- end release-specific documentation -->
2695     *
2696     * @return the maximum number of characters allowed for a user name;
2697     * a result of zero means that there is no limit or the limit
2698     * is not known
2699     * @exception SQLException if a database access error occurs
2700     */

2701    public int getMaxUserNameLength() throws SQLException JavaDoc {
2702
2703        // hard limit is Integer.MAX_VALUE
2704
return 0;
2705    }
2706
2707    //----------------------------------------------------------------------
2708

2709    /**
2710     * Retrieves this database's default transaction isolation level. The
2711     * possible values are defined in <code>java.sql.Connection</code>. <p>
2712     *
2713     * <!-- start release-specific documentation -->
2714     * <div class="ReleaseSpecificDocumentation">
2715     * <h3>HSQLDB-Specific Information</h3>
2716     *
2717     * Including 1.7.2, HSQLDB supports only TRANSACTION_READ_UNCOMMITED
2718     * and <em>always</em> returns this value here.
2719     * </div>
2720     * <!-- end release-specific documentation -->
2721     *
2722     * @return the default isolation level
2723     * @exception SQLException if a database access error occurs
2724     * @see jdbcConnection
2725     */

2726    public int getDefaultTransactionIsolation() throws SQLException JavaDoc {
2727        return Connection.TRANSACTION_READ_UNCOMMITTED;
2728    }
2729
2730    /**
2731     * Retrieves whether this database supports transactions. If not, invoking the
2732     * method <code>commit</code> is a noop, and the isolation level is
2733     * <code>TRANSACTION_NONE</code>. <p>
2734     *
2735     * <!-- start release-specific documentation -->
2736     * <div class="ReleaseSpecificDocumentation">
2737     * <h3>HSQLDB-Specific Information:</h3> <p>
2738     *
2739     * HSQLDB supports transactions;
2740     * this method always returns <code>true</code>.
2741     * </div>
2742     * <!-- end release-specific documentation -->
2743     * @return <code>true</code> if transactions are supported;
2744     * <code>false</code> otherwise
2745     * @exception SQLException if a database access error occurs
2746     */

2747    public boolean supportsTransactions() throws SQLException JavaDoc {
2748        return true;
2749    }
2750
2751    /**
2752     * Retrieves whether this database supports the given transaction
2753     * isolation level. <p>
2754     *
2755     * <!-- start release-specific documentation -->
2756     * <div class="ReleaseSpecificDocumentation">
2757     * <h3>HSQLDB-Specific Information</h3>
2758     * HSQLDB supports <code>TRANSACTION_READ_UNCOMMITED</code> in all cases
2759     * and the rest of the isolation levels where there is only one connection
2760     * to the database.
2761     * </div>
2762     * <!-- end release-specific documentation -->
2763     *
2764     *
2765     * @param level one of the transaction isolation levels defined in
2766     * <code>java.sql.Connection</code>
2767     * @return <code>true</code> if so; <code>false</code> otherwise
2768     * @exception SQLException if a database access error occurs
2769     * @see jdbcConnection
2770     */

2771    public boolean supportsTransactionIsolationLevel(int level)
2772    throws SQLException JavaDoc {
2773
2774        return level == Connection.TRANSACTION_READ_UNCOMMITTED
2775               || level == Connection.TRANSACTION_READ_COMMITTED
2776               || level == Connection.TRANSACTION_REPEATABLE_READ
2777               || level == Connection.TRANSACTION_SERIALIZABLE;
2778    }
2779
2780    /**
2781     * Retrieves whether this database supports both data definition and
2782     * data manipulation statements within a transaction. <p>
2783     *
2784     * <!-- start release-specific documentation -->
2785     * <div class="ReleaseSpecificDocumentation">
2786     * <h3>HSQLDB-Specific Information:</h3> <p>
2787     *
2788     * HSQLDB does not support a mix of both data definition and
2789     * data manipulation statements within a transaction. DDL commits the
2790     * current transaction before proceding;
2791     * this method always returns <code>false</code>.
2792     * </div>
2793     * <!-- end release-specific documentation -->
2794     *
2795     *
2796     * @return <code>true</code> if so; <code>false</code> otherwise
2797     * @exception SQLException if a database access error occurs
2798     */

2799    public boolean supportsDataDefinitionAndDataManipulationTransactions()
2800    throws SQLException JavaDoc {
2801        return false;
2802    }
2803
2804    /**
2805     * Retrieves whether this database supports only data manipulation
2806     * statements within a transaction. <p>
2807     *
2808     * <!-- start release-specific documentation -->
2809     * <div class="ReleaseSpecificDocumentation">
2810     * <h3>HSQLDB-Specific Information:</h3> <p>
2811     *
2812     * HSQLDB supports only data manipulation
2813     * statements within a transaction. DDL commits the
2814     * current transaction before proceeding, while DML does not;
2815     * this method always returns <code>true</code>.
2816     * </div>
2817     * <!-- end release-specific documentation -->
2818     *
2819     *
2820     * @return <code>true</code> if so; <code>false</code> otherwise
2821     * @exception SQLException if a database access error occurs
2822     */

2823    public boolean supportsDataManipulationTransactionsOnly()
2824    throws SQLException JavaDoc {
2825        return true;
2826    }
2827
2828    /**
2829     * Retrieves whether a data definition statement within a transaction forces
2830     * the transaction to commit. <p>
2831     *
2832     * <!-- start release-specific documentation -->
2833     * <div class="ReleaseSpecificDocumentation">
2834     * <h3>HSQLDB-Specific Information:</h3> <p>
2835     *
2836     * Including 1.7.2, a data definition statement within a transaction forces
2837     * the transaction to commit; this method always returns <code>true</code>.
2838     * </div>
2839     * <!-- end release-specific documentation -->
2840     *
2841     *
2842     * @return <code>true</code> if so; <code>false</code> otherwise
2843     * @exception SQLException if a database access error occurs
2844     */

2845    public boolean dataDefinitionCausesTransactionCommit()
2846    throws SQLException JavaDoc {
2847        return true;
2848    }
2849
2850    /**
2851     * Retrieves whether this database ignores a data definition statement
2852     * within a transaction. <p>
2853     *
2854     * <!-- start release-specific documentation -->
2855     * <div class="ReleaseSpecificDocumentation">
2856     * <h3>HSQLDB-Specific Information:</h3> <p>
2857     *
2858     * Including 1.7.2, a data definition statement is not ignored within a
2859     * transaction. Rather, a data definition statement within a
2860     * transaction forces the transaction to commit; this method
2861     * <em>always</em> returns <code>false</code>.
2862     * </div>
2863     * <!-- end release-specific documentation -->
2864     *
2865     *
2866     * @return <code>true</code> if so; <code>false</code> otherwise
2867     * @exception SQLException if a database access error occurs
2868     */

2869    public boolean dataDefinitionIgnoredInTransactions() throws SQLException JavaDoc {
2870        return false;
2871    }
2872
2873    /**
2874     * Retrieves a description of the stored procedures available in the given
2875     * catalog.
2876     * <P>
2877     * Only procedure descriptions matching the schema and
2878     * procedure name criteria are returned. They are ordered by
2879     * <code>PROCEDURE_SCHEM</code> and <code>PROCEDURE_NAME</code>.
2880     *
2881     * <P>Each procedure description has the the following columns:
2882     * <OL>
2883     * <LI><B>PROCEDURE_CAT</B> String => procedure catalog (may be <code>null</code>)
2884     * <LI><B>PROCEDURE_SCHEM</B> String => procedure schema (may be <code>null</code>)
2885     * <LI><B>PROCEDURE_NAME</B> String => procedure name
2886     * <LI> reserved for future use
2887     * <LI> reserved for future use
2888     * <LI> reserved for future use
2889     * <LI><B>REMARKS</B> String => explanatory comment on the procedure
2890     * <LI><B>PROCEDURE_TYPE</B> short => kind of procedure:
2891     * <UL>
2892     * <LI> procedureResultUnknown - May return a result
2893     * <LI> procedureNoResult - Does not return a result
2894     * <LI> procedureReturnsResult - Returns a result
2895     * </UL>
2896     * </OL> <p>
2897     *
2898     * <!-- start release-specific documentation -->
2899     * <div class="ReleaseSpecificDocumentation">
2900     * <h3>HSQLDB-Specific Information:</h3> <p>
2901     *
2902     * HSQLDB treats unquoted identifiers as case insensitive in SQL but stores
2903     * them in upper case; it treats quoted identifiers as case sensitive and
2904     * stores them verbatim. All jdbcDatabaseMetaData methods perform
2905     * case-sensitive comparison between name (pattern) arguments and the
2906     * corresponding identifier values as they are stored in the database.
2907     * Therefore, care must be taken to specify name arguments precisely
2908     * (including case) as they are stored in the database. <p>
2909     *
2910     * Since 1.7.2, this feature is supported by default. If the jar is
2911     * compiled without org.hsqldb.DatabaseInformationFull or
2912     * org.hsqldb.DatabaseInformationMain, the feature is
2913     * not supported. The default implementation is
2914     * {@link org.hsqldb.DatabaseInformationFull}.
2915     * </div>
2916     * <!-- end release-specific documentation -->
2917     *
2918     * @param catalog a catalog name; must match the catalog name as it
2919     * is stored in the database; "" retrieves those without a catalog;
2920     * <code>null</code> means that the catalog name should not be used
2921     * to narrow the search
2922     * @param schemaPattern a schema name pattern; must match the schema name
2923     * as it is stored in the database; "" retrieves those without a
2924     * schema; <code>null</code> means that the schema name should not be
2925     * used to narrow the search
2926     * @param procedureNamePattern a procedure name pattern; must match the
2927     * procedure name as it is stored in the database
2928     * @return <code>ResultSet</code> - each row is a procedure description
2929     * @exception SQLException if a database access error occurs
2930     * @see #getSearchStringEscape
2931     */

2932    public ResultSet JavaDoc getProcedures(String JavaDoc catalog, String JavaDoc schemaPattern,
2933                                   String JavaDoc procedureNamePattern)
2934                                   throws SQLException JavaDoc {
2935
2936        if (wantsIsNull(procedureNamePattern)) {
2937            return executeSelect("SYSTEM_PROCEDURES", "0=1");
2938        }
2939
2940        schemaPattern = translateSchema(schemaPattern);
2941
2942        StringBuffer JavaDoc select = toQueryPrefix("SYSTEM_PROCEDURES").append(
2943            and("PROCEDURE_CAT", "=", catalog)).append(
2944            and("PROCEDURE_SCHEM", "LIKE", schemaPattern)).append(
2945            and("PROCEDURE_NAME", "LIKE", procedureNamePattern));
2946
2947        // By default, query already returns the result ordered by
2948
// PROCEDURE_SCHEM, PROCEDURE_NAME...
2949
return execute(select.toString());
2950    }
2951
2952    /**
2953     * Retrieves a description of the given catalog's stored procedure parameter
2954     * and result columns.
2955     *
2956     * <P>Only descriptions matching the schema, procedure and
2957     * parameter name criteria are returned. They are ordered by
2958     * PROCEDURE_SCHEM and PROCEDURE_NAME. Within this, the return value,
2959     * if any, is first. Next are the parameter descriptions in call
2960     * order. The column descriptions follow in column number order.
2961     *
2962     * <P>Each row in the <code>ResultSet</code> is a parameter description or
2963     * column description with the following fields:
2964     * <OL>
2965     * <LI><B>PROCEDURE_CAT</B> String => procedure catalog (may be <code>null</code>)
2966     * <LI><B>PROCEDURE_SCHEM</B> String => procedure schema (may be <code>null</code>)
2967     * <LI><B>PROCEDURE_NAME</B> String => procedure name
2968     * <LI><B>COLUMN_NAME</B> String => column/parameter name
2969     * <LI><B>COLUMN_TYPE</B> Short => kind of column/parameter:
2970     * <UL>
2971     * <LI> procedureColumnUnknown - nobody knows
2972     * <LI> procedureColumnIn - IN parameter
2973     * <LI> procedureColumnInOut - INOUT parameter
2974     * <LI> procedureColumnOut - OUT parameter
2975     * <LI> procedureColumnReturn - procedure return value
2976     * <LI> procedureColumnResult - result column in <code>ResultSet</code>
2977     * </UL>
2978     * <LI><B>DATA_TYPE</B> short => SQL type from java.sql.Types
2979     * <LI><B>TYPE_NAME</B> String => SQL type name, for a UDT type the
2980     * type name is fully qualified
2981     * <LI><B>PRECISION</B> int => precision
2982     * <LI><B>LENGTH</B> int => length in bytes of data
2983     * <LI><B>SCALE</B> short => scale
2984     * <LI><B>RADIX</B> short => radix
2985     * <LI><B>NULLABLE</B> short => can it contain NULL.
2986     * <UL>
2987     * <LI> procedureNoNulls - does not allow NULL values
2988     * <LI> procedureNullable - allows NULL values
2989     * <LI> procedureNullableUnknown - nullability unknown
2990     * </UL>
2991     * <LI><B>REMARKS</B> String => comment describing parameter/column
2992     * </OL>
2993     *
2994     * <P><B>Note:</B> Some databases may not return the column
2995     * descriptions for a procedure. Additional columns beyond
2996     * REMARKS can be defined by the database. <p>
2997     *
2998     * <!-- start release-specific documentation -->
2999     * <div class="ReleaseSpecificDocumentation">
3000     * <h3>HSQLDB-Specific Information:</h3> <p>
3001     *
3002     * HSQLDB treats unquoted identifiers as case insensitive in SQL but stores
3003     * them in upper case; it treats quoted identifiers as case sensitive and
3004     * stores them verbatim. All jdbcDatabaseMetaData methods perform
3005     * case-sensitive comparison between name (pattern) arguments and the
3006     * corresponding identifier values as they are stored in the database.
3007     * Therefore, care must be taken to specify name arguments precisely
3008     * (including case) as they are stored in the database. <p>
3009     *
3010     * Since 1.7.2, this feature is supported by default. If the jar is
3011     * compiled without org.hsqldb.DatabaseInformationFull or
3012     * org.hsqldb.DatabaseInformationMain, the feature is
3013     * not supported. The default implementation is
3014     * {@link org.hsqldb.DatabaseInformationFull}.
3015     * </div>
3016     * <!-- end release-specific documentation -->
3017     *
3018     * @param catalog a catalog name; must match the catalog name as it
3019     * is stored in the database; "" retrieves those without a catalog;
3020     * <code>null</code> means that the catalog name should not be used
3021     * to narrow the search
3022     * @param schemaPattern a schema name pattern; must match the schema name
3023     * as it is stored in the database; "" retrieves those without a
3024     * schema; <code>null</code> means that the schema name should not be
3025     * used to narrow the search
3026     * @param procedureNamePattern a procedure name pattern; must match the
3027     * procedure name as it is stored in the database
3028     * @param columnNamePattern a column name pattern; must match the column
3029     * name as it is stored in the database
3030     * @return <code>ResultSet</code> - each row describes a stored procedure
3031     * parameter or column
3032     * @exception SQLException if a database access error occurs
3033     * @see #getSearchStringEscape
3034     */

3035    public ResultSet JavaDoc getProcedureColumns(String JavaDoc catalog,
3036                                         String JavaDoc schemaPattern,
3037                                         String JavaDoc procedureNamePattern,
3038                                         String JavaDoc columnNamePattern)
3039                                         throws SQLException JavaDoc {
3040
3041        if (wantsIsNull(procedureNamePattern)
3042                || wantsIsNull(columnNamePattern)) {
3043            return executeSelect("SYSTEM_PROCEDURECOLUMNS", "0=1");
3044        }
3045
3046        schemaPattern = translateSchema(schemaPattern);
3047
3048        StringBuffer JavaDoc select = toQueryPrefix("SYSTEM_PROCEDURECOLUMNS").append(
3049            and("PROCEDURE_CAT", "=", catalog)).append(
3050            and("PROCEDURE_SCHEM", "LIKE", schemaPattern)).append(
3051            and("PROCEDURE_NAME", "LIKE", procedureNamePattern)).append(
3052            and("COLUMN_NAME", "LIKE", columnNamePattern));
3053
3054        // By default, query already returns result ordered by
3055
// PROCEDURE_SCHEM and PROCEDURE_NAME...
3056
return execute(select.toString());
3057    }
3058
3059    /**
3060     * Retrieves a description of the tables available in the given catalog.
3061     * Only table descriptions matching the catalog, schema, table
3062     * name and type criteria are returned. They are ordered by
3063     * TABLE_TYPE, TABLE_SCHEM and TABLE_NAME.
3064     * <P>
3065     * Each table description has the following columns:
3066     * <OL>
3067     * <LI><B>TABLE_CAT</B> String => table catalog (may be <code>null</code>)
3068     * <LI><B>TABLE_SCHEM</B> String => table schema (may be <code>null</code>)
3069     * <LI><B>TABLE_NAME</B> String => table name
3070     * <LI><B>TABLE_TYPE</B> String => table type. Typical types are "TABLE",
3071     * "VIEW", "SYSTEM TABLE", "GLOBAL TEMPORARY",
3072     * "LOCAL TEMPORARY", "ALIAS", "SYNONYM".
3073     * <LI><B>REMARKS</B> String => explanatory comment on the table
3074     * <LI><B>TYPE_CAT</B> String => the types catalog (may be <code>null</code>)
3075     * <LI><B>TYPE_SCHEM</B> String => the types schema (may be <code>null</code>)
3076     * <LI><B>TYPE_NAME</B> String => type name (may be <code>null</code>)
3077     * <LI><B>SELF_REFERENCING_COL_NAME</B> String => name of the designated
3078     * "identifier" column of a typed table (may be <code>null</code>)
3079     * <LI><B>REF_GENERATION</B> String => specifies how values in
3080     * SELF_REFERENCING_COL_NAME are created. Values are
3081     * "SYSTEM", "USER", "DERIVED". (may be <code>null</code>)
3082     * </OL>
3083     *
3084     * <P><B>Note:</B> Some databases may not return information for
3085     * all tables. <p>
3086     *
3087     * <!-- start release-specific documentation -->
3088     * <div class="ReleaseSpecificDocumentation">
3089     * <h3>HSQLDB-Specific Information:</h3> <p>
3090     *
3091     * HSQLDB treats unquoted identifiers as case insensitive in SQL but stores
3092     * them in upper case; it treats quoted identifiers as case sensitive and
3093     * stores them verbatim. All jdbcDatabaseMetaData methods perform
3094     * case-sensitive comparison between name (pattern) arguments and the
3095     * corresponding identifier values as they are stored in the database.
3096     * Therefore, care must be taken to specify name arguments precisely
3097     * (including case) as they are stored in the database. <p>
3098     *
3099     * Since 1.7.0, HSQLDB returns extra information on TEXT tables
3100     * in the REMARKS column. <p>
3101     *
3102     * Since 1.7.0, HSQLDB includes the new JDBC3 columns TYPE_CAT,
3103     * TYPE_SCHEM, TYPE_NAME and SELF_REFERENCING_COL_NAME in anticipation
3104     * of JDBC3 compliant tools. <p>
3105     *
3106     * Since 1.7.2, this feature is supported by default. If the jar is
3107     * compiled without org.hsqldb.DatabaseInformationFull or
3108     * org.hsqldb.DatabaseInformationMain, the feature is
3109     * not supported. The default implementation is
3110     * {@link org.hsqldb.DatabaseInformationFull}.
3111     * </div>
3112     * <!-- end release-specific documentation -->
3113     *
3114     * @param catalog a catalog name; must match the catalog name as it
3115     * is stored in the database; "" retrieves those without a catalog;
3116     * <code>null</code> means that the catalog name should not be used
3117     * to narrow the search
3118     * @param schemaPattern a schema name pattern; must match the schema name
3119     * as it is stored in the database; "" retrieves those without a
3120     * schema; <code>null</code> means that the schema name should not be
3121     * used to narrow the search
3122     * @param tableNamePattern a table name pattern; must match the
3123     * table name as it is stored in the database
3124     * @param types a list of table types to include; <code>null</code> returns
3125     * all types
3126     * @return <code>ResultSet</code> - each row is a table description
3127     * @exception SQLException if a database access error occurs
3128     * @see #getSearchStringEscape
3129     */

3130    public ResultSet JavaDoc getTables(String JavaDoc catalog, String JavaDoc schemaPattern,
3131                               String JavaDoc tableNamePattern,
3132                               String JavaDoc[] types) throws SQLException JavaDoc {
3133
3134        if (wantsIsNull(tableNamePattern)
3135                || (types != null && types.length == 0)) {
3136            return executeSelect("SYSTEM_TABLES", "0=1");
3137        }
3138
3139        schemaPattern = translateSchema(schemaPattern);
3140
3141        StringBuffer JavaDoc select =
3142            toQueryPrefix("SYSTEM_TABLES").append(and("TABLE_CAT", "=",
3143                catalog)).append(and("TABLE_SCHEM", "LIKE",
3144                                     schemaPattern)).append(and("TABLE_NAME",
3145                                         "LIKE", tableNamePattern));
3146
3147        if (types == null) {
3148
3149            // do not use to narrow search
3150
} else {
3151            select.append(" AND TABLE_TYPE IN (").append(
3152                StringUtil.getList(types, ",", "'")).append(')');
3153        }
3154
3155        // By default, query already returns result ordered by
3156
// TABLE_TYPE, TABLE_SCHEM and TABLE_NAME...
3157
return execute(select.toString());
3158    }
3159
3160    /**
3161     * Retrieves the schema names available in this database. The results
3162     * are ordered by schema name.
3163     *
3164     * <P>The schema column is:
3165     * <OL>
3166     * <LI><B>TABLE_SCHEM</B> String => schema name
3167     * <LI><B>TABLE_CATALOG</B> String => catalog name (may be <code>null</code>)
3168     * </OL> <p>
3169     *
3170     * <!-- start release-specific documentation -->
3171     * <div class="ReleaseSpecificDocumentation">
3172     * <h3>HSQLDB-Specific Information:</h3> <p>
3173     *
3174     * In 1.8.0, the list of schemas is returned.
3175     * </div>
3176     * <!-- end release-specific documentation -->
3177     *
3178     * @return a <code>ResultSet</code> object in which each row is a
3179     * schema decription
3180     * @exception SQLException if a database access error occurs
3181     */

3182    public ResultSet JavaDoc getSchemas() throws SQLException JavaDoc {
3183
3184        // By default, query already returns the result in contract order
3185
return executeSelect("SYSTEM_SCHEMAS", null);
3186    }
3187
3188    /**
3189     * Retrieves the catalog names available in this database. The results
3190     * are ordered by catalog name.
3191     *
3192     * <P>The catalog column is:
3193     * <OL>
3194     * <LI><B>TABLE_CAT</B> String => catalog name
3195     * </OL> <p>
3196     *
3197     * <!-- start release-specific documentation -->
3198     * <div class="ReleaseSpecificDocumentation">
3199     * <h3>HSQLDB-Specific Information:</h3> <p>
3200     *
3201     * Since 1.7.2, this feature is supported by default. If the jar is
3202     * compiled without org.hsqldb.DatabaseInformationFull or
3203     * org.hsqldb.DatabaseInformationMain, the feature is
3204     * not supported. The default implementation is
3205     * {@link org.hsqldb.DatabaseInformationFull}.
3206     * </div>
3207     * <!-- end release-specific documentation -->
3208     *
3209     * @return a <code>ResultSet</code> object in which each row has a
3210     * single <code>String</code> column that is a catalog name
3211     * @exception SQLException if a database access error occurs
3212     */

3213    public ResultSet JavaDoc getCatalogs() throws SQLException JavaDoc {
3214        return executeSelect("SYSTEM_CATALOGS", null);
3215    }
3216
3217    /**
3218     * Retrieves the table types available in this database. The results
3219     * are ordered by table type.
3220     *
3221     * <P>The table type is:
3222     * <OL>
3223     * <LI><B>TABLE_TYPE</B> String => table type. Typical types are "TABLE",
3224     * "VIEW", "SYSTEM TABLE", "GLOBAL TEMPORARY",
3225     * "LOCAL TEMPORARY", "ALIAS", "SYNONYM".
3226     * </OL> <p>
3227     *
3228     * <!-- start release-specific documentation -->
3229     * <div class="ReleaseSpecificDocumentation">
3230     * <h3>HSQLDB-Specific Information:</h3> <p>
3231     *
3232     * Since 1.7.1, HSQLDB reports: "TABLE", "VIEW" and "GLOBAL TEMPORARY"
3233     * types.
3234     *
3235     * Since 1.7.2, this feature is supported by default. If the jar is
3236     * compiled without org.hsqldb.DatabaseInformationFull or
3237     * org.hsqldb.DatabaseInformationMain, the feature is
3238     * not supported. The default implementation is
3239     * {@link org.hsqldb.DatabaseInformationFull}.
3240     * </div>
3241     * <!-- end release-specific documentation -->
3242     * @return a <code>ResultSet</code> object in which each row has a
3243     * single <code>String</code> column that is a table type
3244     * @exception SQLException if a database access error occurs
3245     */

3246    public ResultSet JavaDoc getTableTypes() throws SQLException JavaDoc {
3247
3248        // system table producer returns rows in contract order
3249
return executeSelect("SYSTEM_TABLETYPES", null);
3250    }
3251
3252    /**
3253     * Retrieves a description of table columns available in
3254     * the specified catalog.
3255     *
3256     * <P>Only column descriptions matching the catalog, schema, table
3257     * and column name criteria are returned. They are ordered by
3258     * <code>TABLE_SCHEM</code>, <code>TABLE_NAME</code>, and
3259     * <code>ORDINAL_POSITION</code>.
3260     *
3261     * <P>Each column description has the following columns:
3262     * <OL>
3263     * <LI><B>TABLE_CAT</B> String => table catalog (may be <code>null</code>)
3264     * <LI><B>TABLE_SCHEM</B> String => table schema (may be <code>null</code>)
3265     * <LI><B>TABLE_NAME</B> String => table name
3266     * <LI><B>COLUMN_NAME</B> String => column name
3267     * <LI><B>DATA_TYPE</B> short => SQL type from java.sql.Types
3268     * <LI><B>TYPE_NAME</B> String => Data source dependent type name,
3269     * for a UDT the type name is fully qualified
3270     * <LI><B>COLUMN_SIZE</B> int => column size. For char or date
3271     * types this is the maximum number of characters, for numeric or
3272     * decimal types this is precision.
3273     * <LI><B>BUFFER_LENGTH</B> is not used.
3274     * <LI><B>DECIMAL_DIGITS</B> int => the number of fractional digits
3275     * <LI><B>NUM_PREC_RADIX</B> int => Radix (typically either 10 or 2)
3276     * <LI><B>NULLABLE</B> int => is NULL allowed.
3277     * <UL>
3278     * <LI> columnNoNulls - might not allow <code>NULL</code> values
3279     * <LI> columnNullable - definitely allows <code>NULL</code> values
3280     * <LI> columnNullableUnknown - nullability unknown
3281     * </UL>
3282     * <LI><B>REMARKS</B> String => comment describing column (may be <code>null</code>)
3283     * <LI><B>COLUMN_DEF</B> String => default value (may be <code>null</code>)
3284     * <LI><B>SQL_DATA_TYPE</B> int => unused
3285     * <LI><B>SQL_DATETIME_SUB</B> int => unused
3286     * <LI><B>CHAR_OCTET_LENGTH</B> int => for char types the
3287     * maximum number of bytes in the column
3288     * <LI><B>ORDINAL_POSITION</B> int => index of column in table
3289     * (starting at 1)
3290     * <LI><B>IS_NULLABLE</B> String => "NO" means column definitely
3291     * does not allow NULL values; "YES" means the column might
3292     * allow NULL values. An empty string means nobody knows.
3293     * <LI><B>SCOPE_CATLOG</B> String => catalog of table that is the scope
3294     * of a reference attribute (<code>null</code> if DATA_TYPE isn't REF)
3295     * <LI><B>SCOPE_SCHEMA</B> String => schema of table that is the scope
3296     * of a reference attribute (<code>null</code> if the DATA_TYPE isn't REF)
3297     * <LI><B>SCOPE_TABLE</B> String => table name that this the scope
3298     * of a reference attribure (<code>null</code> if the DATA_TYPE isn't REF)
3299     * <LI><B>SOURCE_DATA_TYPE</B> short => source type of a distinct type or user-generated
3300     * Ref type, SQL type from java.sql.Types (<code>null</code> if DATA_TYPE
3301     * isn't DISTINCT or user-generated REF)
3302     * </OL> <p>
3303     *
3304     * <!-- start release-specific documentation -->
3305     * <div class="ReleaseSpecificDocumentation">
3306     * <h3>HSQLDB-Specific Information:</h3> <p>
3307     *
3308     * HSQLDB treats unquoted identifiers as case insensitive in SQL but stores
3309     * them in upper case; it treats quoted identifiers as case sensitive and
3310     * stores them verbatim. All jdbcDatabaseMetaData methods perform
3311     * case-sensitive comparison between name (pattern) arguments and the
3312     * corresponding identifier values as they are stored in the database.
3313     * Therefore, care must be taken to specify name arguments precisely
3314     * (including case) as they are stored in the database. <p>
3315     *
3316     * Since 1.7.0, HSQLDB includes the new JDBC 3 columns SCOPE_CATLOG,
3317     * SCOPE_SCHEMA, SCOPE_TABLE and SOURCE_DATA_TYPE in anticipation
3318     * of JDBC 3 compliant tools. However, these columns are never filled in;
3319     * the engine does not support the related features. <p>
3320     *
3321     * Since 1.7.2, this feature is supported by default. If the jar is
3322     * compiled without org.hsqldb.DatabaseInformationFull or
3323     * org.hsqldb.DatabaseInformationMain, the feature is
3324     * not supported. The default implementation is
3325     * {@link org.hsqldb.DatabaseInformationFull}.
3326     * </div>
3327     * <!-- end release-specific documentation -->
3328     *
3329     * @param catalog a catalog name; must match the catalog name as it
3330     * is stored in the database; "" retrieves those without a catalog;
3331     * <code>null</code> means that the catalog name should not be used
3332     * to narrow the search
3333     * @param schemaPattern a schema name pattern; must match the schema name
3334     * as it is stored in the database; "" retrieves those without a
3335     * schema; <code>null</code> means that the schema name should not be
3336     * used to narrow the search
3337     * @param tableNamePattern a table name pattern; must match the
3338     * table name as it is stored in the database
3339     * @param columnNamePattern a column name pattern; must match the column
3340     * name as it is stored in the database
3341     * @return <code>ResultSet</code> - each row is a column description
3342     * @exception SQLException if a database access error occurs
3343     * @see #getSearchStringEscape
3344     */

3345    public ResultSet JavaDoc getColumns(String JavaDoc catalog, String JavaDoc schemaPattern,
3346                                String JavaDoc tableNamePattern,
3347                                String JavaDoc columnNamePattern)
3348                                throws SQLException JavaDoc {
3349
3350        if (wantsIsNull(tableNamePattern) || wantsIsNull(columnNamePattern)) {
3351            return executeSelect("SYSTEM_COLUMNS", "0=1");
3352        }
3353
3354        schemaPattern = translateSchema(schemaPattern);
3355
3356        StringBuffer JavaDoc select = toQueryPrefix("SYSTEM_COLUMNS").append(
3357            and("TABLE_CAT", "=", catalog)).append(
3358            and("TABLE_SCHEM", "LIKE", schemaPattern)).append(
3359            and("TABLE_NAME", "LIKE", tableNamePattern)).append(
3360            and("COLUMN_NAME", "LIKE", columnNamePattern));
3361
3362        // by default, query already returns the result ordered
3363
// by TABLE_SCHEM, TABLE_NAME and ORDINAL_POSITION
3364
return execute(select.toString());
3365    }
3366
3367    /**
3368     * Retrieves a description of the access rights for a table's columns.
3369     *
3370     * <P>Only privileges matching the column name criteria are
3371     * returned. They are ordered by COLUMN_NAME and PRIVILEGE.
3372     *
3373     * <P>Each privilige description has the following columns:
3374     * <OL>
3375     * <LI><B>TABLE_CAT</B> String => table catalog (may be <code>null</code>)
3376     * <LI><B>TABLE_SCHEM</B> String => table schema (may be <code>null</code>)
3377     * <LI><B>TABLE_NAME</B> String => table name
3378     * <LI><B>COLUMN_NAME</B> String => column name
3379     * <LI><B>GRANTOR</B> => grantor of access (may be <code>null</code>)
3380     * <LI><B>GRANTEE</B> String => grantee of access
3381     * <LI><B>PRIVILEGE</B> String => name of access (SELECT,
3382     * INSERT, UPDATE, REFRENCES, ...)
3383     * <LI><B>IS_GRANTABLE</B> String => "YES" if grantee is permitted
3384     * to grant to others; "NO" if not; <code>null</code> if unknown
3385     * </OL> <p>
3386     *
3387     * <!-- start release-specific documentation -->
3388     * <div class="ReleaseSpecificDocumentation">
3389     * <h3>HSQLDB-Specific Information:</h3> <p>
3390     *
3391     * HSQLDB treats unquoted identifiers as case insensitive in SQL but stores
3392     * them in upper case; it treats quoted identifiers as case sensitive and
3393     * stores them verbatim. All jdbcDatabaseMetaData methods perform
3394     * case-sensitive comparison between name (pattern) arguments and the
3395     * corresponding identifier values as they are stored in the database.
3396     * Therefore, care must be taken to specify name arguments precisely
3397     * (including case) as they are stored in the database. <p>
3398     *
3399     * Since 1.7.2, this feature is supported by default. If the jar is
3400     * compiled without org.hsqldb.DatabaseInformationFull or
3401     * org.hsqldb.DatabaseInformationMain, the feature is
3402     * not supported. The default implementation is
3403     * {@link org.hsqldb.DatabaseInformationFull}.
3404     * </div>
3405     * <!-- end release-specific documentation -->
3406     *
3407     * @param catalog a catalog name; must match the catalog name as it
3408     * is stored in the database; "" retrieves those without a catalog;
3409     * <code>null</code> means that the catalog name should not be used
3410     * to narrow the search
3411     * @param schema a schema name; must match the schema name as it is
3412     * stored in the database; "" retrieves those without a schema;
3413     * <code>null</code> means that the schema name should not be used
3414     * to narrow the search
3415     * @param table a table name; must match the table name as it is
3416     * stored in the database
3417     * @param columnNamePattern a column name pattern; must match the column
3418     * name as it is stored in the database
3419     * @return <code>ResultSet</code> - each row is a column privilege
3420     * description
3421     * @exception SQLException if a database access error occurs
3422     * @see #getSearchStringEscape
3423     */

3424    public ResultSet JavaDoc getColumnPrivileges(String JavaDoc catalog, String JavaDoc schema,
3425                                         String JavaDoc table,
3426                                         String JavaDoc columnNamePattern)
3427                                         throws SQLException JavaDoc {
3428
3429        if (table == null) {
3430            Util.sqlException(Trace.INVALID_JDBC_ARGUMENT);
3431        }
3432
3433        if (wantsIsNull(columnNamePattern)) {
3434            return executeSelect("SYSTEM_COLUMNPRIVILEGES", "0=1");
3435        }
3436
3437        schema = translateSchema(schema);
3438
3439        StringBuffer JavaDoc select = toQueryPrefix("SYSTEM_COLUMNPRIVILEGES").append(
3440            and("TABLE_CAT", "=", catalog)).append(
3441            and("TABLE_SCHEM", "=", schema)).append(
3442            and("TABLE_NAME", "=", table)).append(
3443            and("COLUMN_NAME", "LIKE", columnNamePattern));
3444
3445        // By default, the query already returns the result
3446
// ordered by column name, privilege...
3447
return execute(select.toString());
3448    }
3449
3450    /**
3451     * Retrieves a description of the access rights for each table available
3452     * in a catalog. Note that a table privilege applies to one or
3453     * more columns in the table. It would be wrong to assume that
3454     * this privilege applies to all columns (this may be true for
3455     * some systems but is not true for all.)
3456     *
3457     * <P>Only privileges matching the schema and table name
3458     * criteria are returned. They are ordered by TABLE_SCHEM,
3459     * TABLE_NAME, and PRIVILEGE.
3460     *
3461     * <P>Each privilige description has the following columns:
3462     * <OL>
3463     * <LI><B>TABLE_CAT</B> String => table catalog (may be <code>null</code>)
3464     * <LI><B>TABLE_SCHEM</B> String => table schema (may be <code>null</code>)
3465     * <LI><B>TABLE_NAME</B> String => table name
3466     * <LI><B>GRANTOR</B> => grantor of access (may be <code>null</code>)
3467     * <LI><B>GRANTEE</B> String => grantee of access
3468     * <LI><B>PRIVILEGE</B> String => name of access (SELECT,
3469     * INSERT, UPDATE, REFRENCES, ...)
3470     * <LI><B>IS_GRANTABLE</B> String => "YES" if grantee is permitted
3471     * to grant to others; "NO" if not; <code>null</code> if unknown
3472     * </OL> <p>
3473     *
3474     * <!-- start release-specific documentation -->
3475     * <div class="ReleaseSpecificDocumentation">
3476     * <h3>HSQLDB-Specific Information:</h3> <p>
3477     *
3478     * HSQLDB treats unquoted identifiers as case insensitive in SQL but stores
3479     * them in upper case; it treats quoted identifiers as case sensitive and
3480     * stores them verbatim. All jdbcDatabaseMetaData methods perform
3481     * case-sensitive comparison between name (pattern) arguments and the
3482     * corresponding identifier values as they are stored in the database.
3483     * Therefore, care must be taken to specify name arguments precisely
3484     * (including case) as they are stored in the database. <p>
3485     *
3486     * Since 1.7.2, this feature is supported by default. If the jar is
3487     * compiled without org.hsqldb.DatabaseInformationFull or
3488     * org.hsqldb.DatabaseInformationMain, the feature is
3489     * not supported. The default implementation is
3490     * {@link org.hsqldb.DatabaseInformationFull}.
3491     * </div>
3492     * <!-- end release-specific documentation -->
3493     *
3494     * @param catalog a catalog name; must match the catalog name as it
3495     * is stored in the database; "" retrieves those without a catalog;
3496     * <code>null</code> means that the catalog name should not be used
3497     * to narrow the search
3498     * @param schemaPattern a schema name pattern; must match the schema name
3499     * as it is stored in the database; "" retrieves those without a
3500     * schema; <code>null</code> means that the schema name should not be
3501     * used to narrow the search
3502     * @param tableNamePattern a table name pattern; must match the
3503     * table name as it is stored in the database
3504     * @return <code>ResultSet</code> - each row is a table privilege
3505     * description
3506     * @exception SQLException if a database access error occurs
3507     * @see #getSearchStringEscape
3508     */

3509    public ResultSet JavaDoc getTablePrivileges(String JavaDoc catalog, String JavaDoc schemaPattern,
3510                                        String JavaDoc tableNamePattern)
3511                                        throws SQLException JavaDoc {
3512
3513        if (wantsIsNull(tableNamePattern)) {
3514            return executeSelect("SYSTEM_TABLEPRIVILEGES", "0=1");
3515        }
3516
3517        schemaPattern = translateSchema(schemaPattern);
3518
3519        StringBuffer JavaDoc select = toQueryPrefix("SYSTEM_TABLEPRIVILEGES").append(
3520            and("TABLE_CAT", "=", catalog)).append(
3521            and("TABLE_SCHEM", "LIKE", schemaPattern)).append(
3522            and("TABLE_NAME", "LIKE", tableNamePattern));
3523
3524        // By default, the query already returns a result ordered by
3525
// TABLE_SCHEM, TABLE_NAME, and PRIVILEGE...
3526
return execute(select.toString());
3527    }
3528
3529    /**
3530     * Retrieves a description of a table's optimal set of columns that
3531     * uniquely identifies a row. They are ordered by SCOPE.
3532     *
3533     * <P>Each column description has the following columns:
3534     * <OL>
3535     * <LI><B>SCOPE</B> short => actual scope of result
3536     * <UL>
3537     * <LI> bestRowTemporary - very temporary, while using row
3538     * <LI> bestRowTransaction - valid for remainder of current transaction
3539     * <LI> bestRowSession - valid for remainder of current session
3540     * </UL>
3541     * <LI><B>COLUMN_NAME</B> String => column name
3542     * <LI><B>DATA_TYPE</B> short => SQL data type from java.sql.Types
3543     * <LI><B>TYPE_NAME</B> String => Data source dependent type name,
3544     * for a UDT the type name is fully qualified
3545     * <LI><B>COLUMN_SIZE</B> int => precision
3546     * <LI><B>BUFFER_LENGTH</B> int => not used
3547     * <LI><B>DECIMAL_DIGITS</B> short => scale
3548     * <LI><B>PSEUDO_COLUMN</B> short => is this a pseudo column
3549     * like an Oracle ROWID
3550     * <UL>
3551     * <LI> bestRowUnknown - may or may not be pseudo column
3552     * <LI> bestRowNotPseudo - is NOT a pseudo column
3553     * <LI> bestRowPseudo - is a pseudo column
3554     * </UL>
3555     * </OL> <p>
3556     *
3557     * <!-- start release-specific documentation -->
3558     * <div class="ReleaseSpecificDocumentation">
3559     * <h3>HSQLDB-Specific Information:</h3> <p>
3560     *
3561     * HSQLDB treats unquoted identifiers as case insensitive in SQL but stores
3562     * them in upper case; it treats quoted identifiers as case sensitive and
3563     * stores them verbatim. All jdbcDatabaseMetaData methods perform
3564     * case-sensitive comparison between name (pattern) arguments and the
3565     * corresponding identifier values as they are stored in the database.
3566     * Therefore, care must be taken to specify name arguments precisely
3567     * (including case) as they are stored in the database. <p>
3568     *
3569     * If the name of a column is defined in the database without double
3570     * quotes, an all-uppercase name must be specified when calling this
3571     * method. Otherwise, the name must be specified in the exact case of
3572     * the column definition in the database. <p>
3573     *
3574     * Since 1.7.2, this feature is supported by default. If the jar is
3575     * compiled without org.hsqldb.DatabaseInformationFull or
3576     * org.hsqldb.DatabaseInformationMain, the feature is
3577     * not supported. The default implementation is
3578     * {@link org.hsqldb.DatabaseInformationFull}.
3579     * </div>
3580     * <!-- end release-specific documentation -->
3581     *
3582     * @param catalog a catalog name; must match the catalog name as it
3583     * is stored in the database; "" retrieves those without a catalog;
3584     * <code>null</code> means that the catalog name should not be used
3585     * to narrow the search
3586     * @param schema a schema name; must match the schema name
3587     * as it is stored in the database; "" retrieves those without a
3588     * schema; <code>null</code> means that the schema name should not
3589     * be used to narrow the search
3590     * @param table a table name; must match the table name as it is stored
3591     * in the database
3592     * @param scope the scope of interest; use same values as SCOPE
3593     * @param nullable include columns that are nullable.
3594     * @return <code>ResultSet</code> - each row is a column description
3595     * @exception SQLException if a database access error occurs
3596     */

3597    public ResultSet JavaDoc getBestRowIdentifier(String JavaDoc catalog, String JavaDoc schema,
3598                                          String JavaDoc table, int scope,
3599                                          boolean nullable)
3600                                          throws SQLException JavaDoc {
3601
3602        String JavaDoc scopeIn;
3603
3604        switch (scope) {
3605
3606            case bestRowTemporary :
3607                scopeIn = BRI_TEMPORARY_SCOPE_IN_LIST;
3608                break;
3609
3610            case bestRowTransaction :
3611                scopeIn = BRI_TRANSACTION_SCOPE_IN_LIST;
3612                break;
3613
3614            case bestRowSession :
3615                scopeIn = BRI_SESSION_SCOPE_IN_LIST;
3616                break;
3617
3618            default :
3619                throw Util.sqlException(Trace.ASSERT_FAILED,
3620                                        Trace.JDBC_INVALID_BRI_SCOPE, null);
3621        }
3622
3623        if (table == null) {
3624            Util.sqlException(Trace.INVALID_JDBC_ARGUMENT);
3625        }
3626
3627        schema = translateSchema(schema);
3628
3629        Integer JavaDoc Nullable = (nullable) ? null
3630                                      : INT_COLUMNS_NO_NULLS;
3631        StringBuffer JavaDoc select = toQueryPrefix(
3632            "SYSTEM_BESTROWIDENTIFIER").append(
3633            and("TABLE_CAT", "=", catalog)).append(
3634            and("TABLE_SCHEM", "=", schema)).append(
3635            and("TABLE_NAME", "=", table)).append(
3636            and("NULLABLE", "=", Nullable)).append(
3637            " AND SCOPE IN " + scopeIn);
3638
3639        // By default, query already returns rows in contract order.
3640
// However, the way things are set up, there should never be
3641
// a result where there is > 1 distinct scope value: most requests
3642
// will want only one table and the system table producer (for
3643
// now) guarantees that a maximum of one BRI scope column set is
3644
// produced for each table
3645
return execute(select.toString());
3646    }
3647
3648    /**
3649     * Retrieves a description of a table's columns that are automatically
3650     * updated when any value in a row is updated. They are
3651     * unordered.
3652     *
3653     * <P>Each column description has the following columns:
3654     * <OL>
3655     * <LI><B>SCOPE</B> short => is not used
3656     * <LI><B>COLUMN_NAME</B> String => column name
3657     * <LI><B>DATA_TYPE</B> short => SQL data type from <code>java.sql.Types</code>
3658     * <LI><B>TYPE_NAME</B> String => Data source-dependent type name
3659     * <LI><B>COLUMN_SIZE</B> int => precision
3660     * <LI><B>BUFFER_LENGTH</B> int => length of column value in bytes
3661     * <LI><B>DECIMAL_DIGITS</B> short => scale
3662     * <LI><B>PSEUDO_COLUMN</B> short => whether this is pseudo column
3663     * like an Oracle ROWID
3664     * <UL>
3665     * <LI> versionColumnUnknown - may or may not be pseudo column
3666     * <LI> versionColumnNotPseudo - is NOT a pseudo column
3667     * <LI> versionColumnPseudo - is a pseudo column
3668     * </UL>
3669     * </OL> <p>
3670     *
3671     * <!-- start release-specific documentation -->
3672     * <div class="ReleaseSpecificDocumentation">
3673     * <h3>HSQLDB-Specific Information:</h3> <p>
3674     *
3675     * HSQLDB treats unquoted identifiers as case insensitive in SQL but stores
3676     * them in upper case; it treats quoted identifiers as case sensitive and
3677     * stores them verbatim. All jdbcDatabaseMetaData methods perform
3678     * case-sensitive comparison between name (pattern) arguments and the
3679     * corresponding identifier values as they are stored in the database.
3680     * Therefore, care must be taken to specify name arguments precisely
3681     * (including case) as they are stored in the database. <p>
3682     *
3683     * Since 1.7.2, this feature is supported by default. If the jar is
3684     * compiled without org.hsqldb.DatabaseInformationFull or
3685     * org.hsqldb.DatabaseInformationMain, the feature is
3686     * not supported. The default implementation is
3687     * {@link org.hsqldb.DatabaseInformationFull}.
3688     * </div>
3689     * <!-- end release-specific documentation -->
3690     *
3691     * @param catalog a catalog name; must match the catalog name as it
3692     * is stored in the database; "" retrieves those without a catalog;
3693     * <code>null</code> means that the catalog name should not be used
3694     * to narrow the search
3695     * @param schema a schema name; must match the schema name
3696     * as it is stored in the database; "" retrieves those without a
3697     * schema; <code>null</code> means that the schema name should not be
3698     * used to narrow the search
3699     * @param table a table name; must match the table name as it is stored
3700     * in the database
3701     * @return a <code>ResultSet</code> object in which each row is a
3702     * column description
3703     * @exception SQLException if a database access error occurs
3704     */

3705    public ResultSet JavaDoc getVersionColumns(String JavaDoc catalog, String JavaDoc schema,
3706                                       String JavaDoc table) throws SQLException JavaDoc {
3707
3708        if (table == null) {
3709            Util.sqlException(Trace.INVALID_JDBC_ARGUMENT);
3710        }
3711
3712        schema = translateSchema(schema);
3713
3714        StringBuffer JavaDoc select =
3715            toQueryPrefix("SYSTEM_VERSIONCOLUMNS").append(and("TABLE_CAT",
3716                "=", catalog)).append(and("TABLE_SCHEM", "=",
3717                                          schema)).append(and("TABLE_NAME",
3718                                              "=", table));
3719
3720        // result does not need to be ordered
3721
return execute(select.toString());
3722    }
3723
3724    /**
3725     * Retrieves a description of the given table's primary key columns. They
3726     * are ordered by COLUMN_NAME.
3727     *
3728     * <P>Each primary key column description has the following columns:
3729     * <OL>
3730     * <LI><B>TABLE_CAT</B> String => table catalog (may be <code>null</code>)
3731     * <LI><B>TABLE_SCHEM</B> String => table schema (may be <code>null</code>)
3732     * <LI><B>TABLE_NAME</B> String => table name
3733     * <LI><B>COLUMN_NAME</B> String => column name
3734     * <LI><B>KEY_SEQ</B> short => sequence number within primary key
3735     * <LI><B>PK_NAME</B> String => primary key name (may be <code>null</code>)
3736     * </OL> <p>
3737     *
3738     * <!-- start release-specific documentation -->
3739     * <div class="ReleaseSpecificDocumentation">
3740     * <h3>HSQLDB-Specific Information:</h3> <p>
3741     *
3742     * HSQLDB treats unquoted identifiers as case insensitive in SQL but stores
3743     * them in upper case; it treats quoted identifiers as case sensitive and
3744     * stores them verbatim. All jdbcDatabaseMetaData methods perform
3745     * case-sensitive comparison between name (pattern) arguments and the
3746     * corresponding identifier values as they are stored in the database.
3747     * Therefore, care must be taken to specify name arguments precisely
3748     * (including case) as they are stored in the database. <p>
3749     *
3750     * Since 1.7.2, this feature is supported by default. If the jar is
3751     * compiled without org.hsqldb.DatabaseInformationFull or
3752     * org.hsqldb.DatabaseInformationMain, the feature is
3753     * not supported. The default implementation is
3754     * {@link org.hsqldb.DatabaseInformationFull}.
3755     * </div>
3756     * <!-- end release-specific documentation -->
3757     *
3758     * @param catalog a catalog name; must match the catalog name as it
3759     * is stored in the database; "" retrieves those without a catalog;
3760     * <code>null</code> means that the catalog name should not be used
3761     * to narrow the search
3762     * @param schema a schema name; must match the schema name
3763     * as it is stored in the database; "" retrieves those without a
3764     * schema; <code>null</code> means that the schema name should not
3765     * be used to narrow the search
3766     * @param table a table name; must match the table name as it is stored
3767     * in the database
3768     * @return <code>ResultSet</code> - each row is a primary key column
3769     * description
3770     * @exception SQLException if a database access error occurs
3771     * @see #supportsMixedCaseQuotedIdentifiers
3772     * @see #storesUpperCaseIdentifiers
3773     */

3774
3775// fredt@users 20020226 - comment - changed query to exact name
3776
public ResultSet JavaDoc getPrimaryKeys(String JavaDoc catalog, String JavaDoc schema,
3777                                    String JavaDoc table) throws SQLException JavaDoc {
3778
3779        if (table == null) {
3780            Util.sqlException(Trace.INVALID_JDBC_ARGUMENT);
3781        }
3782
3783        schema = translateSchema(schema);
3784
3785        StringBuffer JavaDoc select =
3786            toQueryPrefix("SYSTEM_PRIMARYKEYS").append(and("TABLE_CAT", "=",
3787                catalog)).append(and("TABLE_SCHEM", "=",
3788                                     schema)).append(and("TABLE_NAME", "=",
3789                                         table));
3790
3791        // By default, query already returns result in contract order
3792
return execute(select.toString());
3793    }
3794
3795    /**
3796     * Retrieves a description of the primary key columns that are
3797     * referenced by a table's foreign key columns (the primary keys
3798     * imported by a table). They are ordered by PKTABLE_CAT,
3799     * PKTABLE_SCHEM, PKTABLE_NAME, and KEY_SEQ.
3800     *
3801     * <P>Each primary key column description has the following columns:
3802     * <OL>
3803     * <LI><B>PKTABLE_CAT</B> String => primary key table catalog
3804     * being imported (may be <code>null</code>)
3805     * <LI><B>PKTABLE_SCHEM</B> String => primary key table schema
3806     * being imported (may be <code>null</code>)
3807     * <LI><B>PKTABLE_NAME</B> String => primary key table name
3808     * being imported
3809     * <LI><B>PKCOLUMN_NAME</B> String => primary key column name
3810     * being imported
3811     * <LI><B>FKTABLE_CAT</B> String => foreign key table catalog (may be <code>null</code>)
3812     * <LI><B>FKTABLE_SCHEM</B> String => foreign key table schema (may be <code>null</code>)
3813     * <LI><B>FKTABLE_NAME</B> String => foreign key table name
3814     * <LI><B>FKCOLUMN_NAME</B> String => foreign key column name
3815     * <LI><B>KEY_SEQ</B> short => sequence number within a foreign key
3816     * <LI><B>UPDATE_RULE</B> short => What happens to a
3817     * foreign key when the primary key is updated:
3818     * <UL>
3819     * <LI> importedNoAction - do not allow update of primary
3820     * key if it has been imported
3821     * <LI> importedKeyCascade - change imported key to agree
3822     * with primary key update
3823     * <LI> importedKeySetNull - change imported key to <code>NULL</code>
3824     * if its primary key has been updated
3825     * <LI> importedKeySetDefault - change imported key to default values
3826     * if its primary key has been updated
3827     * <LI> importedKeyRestrict - same as importedKeyNoAction
3828     * (for ODBC 2.x compatibility)
3829     * </UL>
3830     * <LI><B>DELETE_RULE</B> short => What happens to
3831     * the foreign key when primary is deleted.
3832     * <UL>
3833     * <LI> importedKeyNoAction - do not allow delete of primary
3834     * key if it has been imported
3835     * <LI> importedKeyCascade - delete rows that import a deleted key
3836     * <LI> importedKeySetNull - change imported key to NULL if
3837     * its primary key has been deleted
3838     * <LI> importedKeyRestrict - same as importedKeyNoAction
3839     * (for ODBC 2.x compatibility)
3840     * <LI> importedKeySetDefault - change imported key to default if
3841     * its primary key has been deleted
3842     * </UL>
3843     * <LI><B>FK_NAME</B> String => foreign key name (may be <code>null</code>)
3844     * <LI><B>PK_NAME</B> String => primary key name (may be <code>null</code>)
3845     * <LI><B>DEFERRABILITY</B> short => can the evaluation of foreign key
3846     * constraints be deferred until commit
3847     * <UL>
3848     * <LI> importedKeyInitiallyDeferred - see SQL92 for definition
3849     * <LI> importedKeyInitiallyImmediate - see SQL92 for definition
3850     * <LI> importedKeyNotDeferrable - see SQL92 for definition
3851     * </UL>
3852     * </OL> <p>
3853     *
3854     * <!-- start release-specific documentation -->
3855     * <div class="ReleaseSpecificDocumentation">
3856     * <h3>HSQLDB-Specific Information:</h3> <p>
3857     *
3858     * HSQLDB treats unquoted identifiers as case insensitive in SQL but stores
3859     * them in upper case; it treats quoted identifiers as case sensitive and
3860     * stores them verbatim. All jdbcDatabaseMetaData methods perform
3861     * case-sensitive comparison between name (pattern) arguments and the
3862     * corresponding identifier values as they are stored in the database.
3863     * Therefore, care must be taken to specify name arguments precisely
3864     * (including case) as they are stored in the database. <p>
3865     *
3866     * Since 1.7.2, this feature is supported by default. If the jar is
3867     * compiled without org.hsqldb.DatabaseInformationFull or
3868     * org.hsqldb.DatabaseInformationMain, the feature is
3869     * not supported. The default implementation is
3870     * {@link org.hsqldb.DatabaseInformationFull}.
3871     * </div>
3872     * <!-- end release-specific documentation -->
3873     *
3874     * @param catalog a catalog name; must match the catalog name as it
3875     * is stored in the database; "" retrieves those without a catalog;
3876     * <code>null</code> means that the catalog name should not be used
3877     * to narrow the search
3878     * @param schema a schema name; must match the schema name
3879     * as it is stored in the database; "" retrieves those without a
3880     * schema; <code>null</code> means that the schema name should not be
3881     * used to narrow the search
3882     * @param table a table name; must match the table name as it is stored
3883     * in the database
3884     * @return <code>ResultSet</code> - each row is a primary key column
3885     * description
3886     * @exception SQLException if a database access error occurs
3887     * @see #getExportedKeys
3888     * @see #supportsMixedCaseQuotedIdentifiers
3889     * @see #storesUpperCaseIdentifiers
3890     */

3891    public ResultSet JavaDoc getImportedKeys(String JavaDoc catalog, String JavaDoc schema,
3892                                     String JavaDoc table) throws SQLException JavaDoc {
3893
3894        if (table == null) {
3895            Util.sqlException(Trace.INVALID_JDBC_ARGUMENT);
3896        }
3897
3898        schema = translateSchema(schema);
3899
3900        StringBuffer JavaDoc select = toQueryPrefix("SYSTEM_CROSSREFERENCE").append(
3901            and("FKTABLE_CAT", "=", catalog)).append(
3902            and("FKTABLE_SCHEM", "=", schema)).append(
3903            and("FKTABLE_NAME", "=", table)).append(
3904            " ORDER BY PKTABLE_CAT, PKTABLE_SCHEM, PKTABLE_NAME, KEY_SEQ");
3905
3906        return execute(select.toString());
3907    }
3908
3909    /**
3910     * Retrieves a description of the foreign key columns that reference the
3911     * given table's primary key columns (the foreign keys exported by a
3912     * table). They are ordered by FKTABLE_CAT, FKTABLE_SCHEM,
3913     * FKTABLE_NAME, and KEY_SEQ.
3914     *
3915     * <P>Each foreign key column description has the following columns:
3916     * <OL>
3917     * <LI><B>PKTABLE_CAT</B> String => primary key table catalog (may be <code>null</code>)
3918     * <LI><B>PKTABLE_SCHEM</B> String => primary key table schema (may be <code>null</code>)
3919     * <LI><B>PKTABLE_NAME</B> String => primary key table name
3920     * <LI><B>PKCOLUMN_NAME</B> String => primary key column name
3921     * <LI><B>FKTABLE_CAT</B> String => foreign key table catalog (may be <code>null</code>)
3922     * being exported (may be <code>null</code>)
3923     * <LI><B>FKTABLE_SCHEM</B> String => foreign key table schema (may be <code>null</code>)
3924     * being exported (may be <code>null</code>)
3925     * <LI><B>FKTABLE_NAME</B> String => foreign key table name
3926     * being exported
3927     * <LI><B>FKCOLUMN_NAME</B> String => foreign key column name
3928     * being exported
3929     * <LI><B>KEY_SEQ</B> short => sequence number within foreign key
3930     * <LI><B>UPDATE_RULE</B> short => What happens to
3931     * foreign key when primary is updated:
3932     * <UL>
3933     * <LI> importedNoAction - do not allow update of primary
3934     * key if it has been imported
3935     * <LI> importedKeyCascade - change imported key to agree
3936     * with primary key update
3937     * <LI> importedKeySetNull - change imported key to <code>NULL</code> if
3938     * its primary key has been updated
3939     * <LI> importedKeySetDefault - change imported key to default values
3940     * if its primary key has been updated
3941     * <LI> importedKeyRestrict - same as importedKeyNoAction
3942     * (for ODBC 2.x compatibility)
3943     * </UL>
3944     * <LI><B>DELETE_RULE</B> short => What happens to
3945     * the foreign key when primary is deleted.
3946     * <UL>
3947     * <LI> importedKeyNoAction - do not allow delete of primary
3948     * key if it has been imported
3949     * <LI> importedKeyCascade - delete rows that import a deleted key
3950     * <LI> importedKeySetNull - change imported key to <code>NULL</code> if
3951     * its primary key has been deleted
3952     * <LI> importedKeyRestrict - same as importedKeyNoAction
3953     * (for ODBC 2.x compatibility)
3954     * <LI> importedKeySetDefault - change imported key to default if
3955     * its primary key has been deleted
3956     * </UL>
3957     * <LI><B>FK_NAME</B> String => foreign key name (may be <code>null</code>)
3958     * <LI><B>PK_NAME</B> String => primary key name (may be <code>null</code>)
3959     * <LI><B>DEFERRABILITY</B> short => can the evaluation of foreign key
3960     * constraints be deferred until commit
3961     * <UL>
3962     * <LI> importedKeyInitiallyDeferred - see SQL92 for definition
3963     * <LI> importedKeyInitiallyImmediate - see SQL92 for definition
3964     * <LI> importedKeyNotDeferrable - see SQL92 for definition
3965     * </UL>
3966     * </OL> <p>
3967     *
3968     * <!-- start release-specific documentation -->
3969     * <div class="ReleaseSpecificDocumentation">
3970     * <h3>HSQLDB-Specific Information:</h3> <p>
3971     *
3972     * HSQLDB treats unquoted identifiers as case insensitive in SQL but stores
3973     * them in upper case; it treats quoted identifiers as case sensitive and
3974     * stores them verbatim. All jdbcDatabaseMetaData methods perform
3975     * case-sensitive comparison between name (pattern) arguments and the
3976     * corresponding identifier values as they are stored in the database.
3977     * Therefore, care must be taken to specify name arguments precisely
3978     * (including case) as they are stored in the database. <p>
3979     *
3980     * Since 1.7.2, this feature is supported by default. If the jar is
3981     * compiled without org.hsqldb.DatabaseInformationFull or
3982     * org.hsqldb.DatabaseInformationMain, the feature is
3983     * not supported. The default implementation is
3984     * {@link org.hsqldb.DatabaseInformationFull}.
3985     * </div>
3986     * <!-- end release-specific documentation -->
3987     *
3988     * @param catalog a catalog name; must match the catalog name as it
3989     * is stored in this database; "" retrieves those without a catalog;
3990     * <code>null</code> means that the catalog name should not be used
3991     * to narrow the search
3992     * @param schema a schema name; must match the schema name
3993     * as it is stored in the database; "" retrieves those without a
3994     * schema; <code>null</code> means that the schema name should not be
3995     * used to narrow the search
3996     * @param table a table name; must match the table name as it is stored
3997     * in this database
3998     * @return a <code>ResultSet</code> object in which each row is a
3999     * foreign key column description
4000     * @exception SQLException if a database access error occurs
4001     * @see #getImportedKeys
4002     * @see #supportsMixedCaseQuotedIdentifiers
4003     * @see #storesUpperCaseIdentifiers
4004     */

4005    public ResultSet JavaDoc getExportedKeys(String JavaDoc catalog, String JavaDoc schema,
4006                                     String JavaDoc table) throws SQLException JavaDoc {
4007
4008        if (table == null) {
4009            Util.sqlException(Trace.INVALID_JDBC_ARGUMENT);
4010        }
4011
4012        schema = translateSchema(schema);
4013
4014        StringBuffer JavaDoc select =
4015            toQueryPrefix("SYSTEM_CROSSREFERENCE").append(and("PKTABLE_CAT",
4016                "=", catalog)).append(and("PKTABLE_SCHEM", "=",
4017                                          schema)).append(and("PKTABLE_NAME",
4018                                              "=", table));
4019
4020        // By default, query already returns the table ordered by
4021
// FKTABLE_CAT, FKTABLE_SCHEM, FKTABLE_NAME, and KEY_SEQ.
4022
return execute(select.toString());
4023    }
4024
4025    /**
4026     * Retrieves a description of the foreign key columns in the given foreign key
4027     * table that reference the primary key columns of the given primary key
4028     * table (describe how one table imports another's key). This
4029     * should normally return a single foreign key/primary key pair because
4030     * most tables import a foreign key from a table only once. They
4031     * are ordered by FKTABLE_CAT, FKTABLE_SCHEM, FKTABLE_NAME, and
4032     * KEY_SEQ.
4033     *
4034     * <P>Each foreign key column description has the following columns:
4035     * <OL>
4036     * <LI><B>PKTABLE_CAT</B> String => primary key table catalog (may be <code>null</code>)
4037     * <LI><B>PKTABLE_SCHEM</B> String => primary key table schema (may be <code>null</code>)
4038     * <LI><B>PKTABLE_NAME</B> String => primary key table name
4039     * <LI><B>PKCOLUMN_NAME</B> String => primary key column name
4040     * <LI><B>FKTABLE_CAT</B> String => foreign key table catalog (may be <code>null</code>)
4041     * being exported (may be <code>null</code>)
4042     * <LI><B>FKTABLE_SCHEM</B> String => foreign key table schema (may be <code>null</code>)
4043     * being exported (may be <code>null</code>)
4044     * <LI><B>FKTABLE_NAME</B> String => foreign key table name
4045     * being exported
4046     * <LI><B>FKCOLUMN_NAME</B> String => foreign key column name
4047     * being exported
4048     * <LI><B>KEY_SEQ</B> short => sequence number within foreign key
4049     * <LI><B>UPDATE_RULE</B> short => What happens to
4050     * foreign key when primary is updated:
4051     * <UL>
4052     * <LI> importedNoAction - do not allow update of primary
4053     * key if it has been imported
4054     * <LI> importedKeyCascade - change imported key to agree
4055     * with primary key update
4056     * <LI> importedKeySetNull - change imported key to <code>NULL</code> if
4057     * its primary key has been updated
4058     * <LI> importedKeySetDefault - change imported key to default values
4059     * if its primary key has been updated
4060     * <LI> importedKeyRestrict - same as importedKeyNoAction
4061     * (for ODBC 2.x compatibility)
4062     * </UL>
4063     * <LI><B>DELETE_RULE</B> short => What happens to
4064     * the foreign key when primary is deleted.
4065     * <UL>
4066     * <LI> importedKeyNoAction - do not allow delete of primary
4067     * key if it has been imported
4068     * <LI> importedKeyCascade - delete rows that import a deleted key
4069     * <LI> importedKeySetNull - change imported key to <code>NULL</code> if
4070     * its primary key has been deleted
4071     * <LI> importedKeyRestrict - same as importedKeyNoAction
4072     * (for ODBC 2.x compatibility)
4073     * <LI> importedKeySetDefault - change imported key to default if
4074     * its primary key has been deleted
4075     * </UL>
4076     * <LI><B>FK_NAME</B> String => foreign key name (may be <code>null</code>)
4077     * <LI><B>PK_NAME</B> String => primary key name (may be <code>null</code>)
4078     * <LI><B>DEFERRABILITY</B> short => can the evaluation of foreign key
4079     * constraints be deferred until commit
4080     * <UL>
4081     * <LI> importedKeyInitiallyDeferred - see SQL92 for definition
4082     * <LI> importedKeyInitiallyImmediate - see SQL92 for definition
4083     * <LI> importedKeyNotDeferrable - see SQL92 for definition
4084     * </UL>
4085     * </OL> <p>
4086     *
4087     * <!-- start release-specific documentation -->
4088     * <div class="ReleaseSpecificDocumentation">
4089     * <h3>HSQLDB-Specific Information:</h3> <p>
4090     *
4091     * HSQLDB treats unquoted identifiers as case insensitive in SQL but stores
4092     * them in upper case; it treats quoted identifiers as case sensitive and
4093     * stores them verbatim. All jdbcDatabaseMetaData methods perform
4094     * case-sensitive comparison between name (pattern) arguments and the
4095     * corresponding identifier values as they are stored in the database.
4096     * Therefore, care must be taken to specify name arguments precisely
4097     * (including case) as they are stored in the database. <p>
4098     *
4099     * Since 1.7.2, this feature is supported by default. If the jar is
4100     * compiled without org.hsqldb.DatabaseInformationFull or
4101     * org.hsqldb.DatabaseInformationMain, the feature is
4102     * not supported. The default implementation is
4103     * {@link org.hsqldb.DatabaseInformationFull}.
4104     * </div>
4105     * <!-- end release-specific documentation -->
4106     *
4107     * @param primaryCatalog a catalog name; must match the catalog name
4108     * as it is stored in the database; "" retrieves those without a
4109     * catalog; <code>null</code> means drop catalog name from the
4110     * selection criteria
4111     * @param primarySchema a schema name; must match the schema name as
4112     * it is stored in the database; "" retrieves those without a schema;
4113     * <code>null</code> means drop schema name from the selection criteria
4114     * @param primaryTable the name of the table that exports the key; must
4115     * match the table name as it is stored in the database
4116     * @param foreignCatalog a catalog name; must match the catalog name as
4117     * it is stored in the database; "" retrieves those without a
4118     * catalog; <code>null</code> means drop catalog name from the
4119     * selection criteria
4120     * @param foreignSchema a schema name; must match the schema name as it
4121     * is stored in the database; "" retrieves those without a schema;
4122     * <code>null</code> means drop schema name from the selection criteria
4123     * @param foreignTable the name of the table that imports the key; must
4124     * match the table name as it is stored in the database
4125     * @return <code>ResultSet</code> - each row is a foreign key column
4126     * description
4127     * @exception SQLException if a database access error occurs
4128     * @see #getImportedKeys
4129     * @see #supportsMixedCaseQuotedIdentifiers
4130     * @see #storesUpperCaseIdentifiers
4131     */

4132    public ResultSet JavaDoc getCrossReference(String JavaDoc primaryCatalog,
4133                                       String JavaDoc primarySchema,
4134                                       String JavaDoc primaryTable,
4135                                       String JavaDoc foreignCatalog,
4136                                       String JavaDoc foreignSchema,
4137                                       String JavaDoc foreignTable)
4138                                       throws SQLException JavaDoc {
4139
4140        if (primaryTable == null || foreignTable == null) {
4141            Util.sqlException(Trace.INVALID_JDBC_ARGUMENT);
4142        }
4143
4144        primarySchema = translateSchema(primarySchema);
4145        foreignSchema = translateSchema(foreignSchema);
4146
4147        StringBuffer JavaDoc select = toQueryPrefix("SYSTEM_CROSSREFERENCE").append(
4148            and("PKTABLE_CAT", "=", primaryCatalog)).append(
4149            and("PKTABLE_SCHEM", "=", primarySchema)).append(
4150            and("PKTABLE_NAME", "=", primaryTable)).append(
4151            and("FKTABLE_CAT", "=", foreignCatalog)).append(
4152            and("FKTABLE_SCHEM", "=", foreignSchema)).append(
4153            and("FKTABLE_NAME", "=", foreignTable));
4154
4155        // by default, query already returns the table ordered by
4156
// FKTABLE_CAT, FKTABLE_SCHEM, FKTABLE_NAME, and KEY_SEQ.
4157
return execute(select.toString());
4158    }
4159
4160    /**
4161     * Retrieves a description of all the standard SQL types supported by
4162     * this database. They are ordered by DATA_TYPE and then by how
4163     * closely the data type maps to the corresponding JDBC SQL type.
4164     *
4165     * <P>Each type description has the following columns:
4166     * <OL>
4167     * <LI><B>TYPE_NAME</B> String => Type name
4168     * <LI><B>DATA_TYPE</B> short => SQL data type from java.sql.Types
4169     * <LI><B>PRECISION</B> int => maximum precision
4170     * <LI><B>LITERAL_PREFIX</B> String => prefix used to quote a literal
4171     * (may be <code>null</code>)
4172     * <LI><B>LITERAL_SUFFIX</B> String => suffix used to quote a literal
4173     * (may be <code>null</code>)
4174     * <LI><B>CREATE_PARAMS</B> String => parameters used in creating
4175     * the type (may be <code>null</code>)
4176     * <LI><B>NULLABLE</B> short => can you use NULL for this type.
4177     * <UL>
4178     * <LI> typeNoNulls - does not allow NULL values
4179     * <LI> typeNullable - allows NULL values
4180     * <LI> typeNullableUnknown - nullability unknown
4181     * </UL>
4182     * <LI><B>CASE_SENSITIVE</B> boolean=> is it case sensitive.
4183     * <LI><B>SEARCHABLE</B> short => can you use "WHERE" based on this type:
4184     * <UL>
4185     * <LI> typePredNone - No support
4186     * <LI> typePredChar - Only supported with WHERE .. LIKE
4187     * <LI> typePredBasic - Supported except for WHERE .. LIKE
4188     * <LI> typeSearchable - Supported for all WHERE ..
4189     * </UL>
4190     * <LI><B>UNSIGNED_ATTRIBUTE</B> boolean => is it unsigned.
4191     * <LI><B>FIXED_PREC_SCALE</B> boolean => can it be a money value.
4192     * <LI><B>AUTO_INCREMENT</B> boolean => can it be used for an
4193     * auto-increment value.
4194     * <LI><B>LOCAL_TYPE_NAME</B> String => localized version of type name
4195     * (may be <code>null</code>)
4196     * <LI><B>MINIMUM_SCALE</B> short => minimum scale supported
4197     * <LI><B>MAXIMUM_SCALE</B> short => maximum scale supported
4198     * <LI><B>SQL_DATA_TYPE</B> int => unused
4199     * <LI><B>SQL_DATETIME_SUB</B> int => unused
4200     * <LI><B>NUM_PREC_RADIX</B> int => usually 2 or 10
4201     * </OL> <p>
4202     *
4203     * <!-- start release-specific documentation -->
4204     * <div class="ReleaseSpecificDocumentation">
4205     * <h3>HSQLDB-Specific Information:</h3> <p>
4206     *
4207     * Since 1.7.2, this feature is supported by default. If the jar is
4208     * compiled without org.hsqldb.DatabaseInformationFull or
4209     * org.hsqldb.DatabaseInformationMain, the feature is
4210     * not supported. The default implementation is
4211     * {@link org.hsqldb.DatabaseInformationFull}.
4212     * </div>
4213     * <!-- end release-specific documentation -->
4214     *
4215     * @return a <code>ResultSet</code> object in which each row is an SQL
4216     * type description
4217     * @exception SQLException if a database access error occurs
4218     */

4219    public ResultSet JavaDoc getTypeInfo() throws SQLException JavaDoc {
4220
4221        // system table producer returns rows in contract order
4222
return executeSelect("SYSTEM_TYPEINFO", null);
4223    }
4224
4225    /**
4226     * Retrieves a description of the given table's indices and statistics. They are
4227     * ordered by NON_UNIQUE, TYPE, INDEX_NAME, and ORDINAL_POSITION.
4228     *
4229     * <P>Each index column description has the following columns:
4230     * <OL>
4231     * <LI><B>TABLE_CAT</B> String => table catalog (may be <code>null</code>)
4232     * <LI><B>TABLE_SCHEM</B> String => table schema (may be <code>null</code>)
4233     * <LI><B>TABLE_NAME</B> String => table name
4234     * <LI><B>NON_UNIQUE</B> boolean => Can index values be non-unique.
4235     * false when TYPE is tableIndexStatistic
4236     * <LI><B>INDEX_QUALIFIER</B> String => index catalog (may be <code>null</code>);
4237     * <code>null</code> when TYPE is tableIndexStatistic
4238     * <LI><B>INDEX_NAME</B> String => index name; <code>null</code> when TYPE is
4239     * tableIndexStatistic
4240     * <LI><B>TYPE</B> short => index type:
4241     * <UL>
4242     * <LI> tableIndexStatistic - this identifies table statistics that are
4243     * returned in conjuction with a table's index descriptions
4244     * <LI> tableIndexClustered - this is a clustered index
4245     * <LI> tableIndexHashed - this is a hashed index
4246     * <LI> tableIndexOther - this is some other style of index
4247     * </UL>
4248     * <LI><B>ORDINAL_POSITION</B> short => column sequence number
4249     * within index; zero when TYPE is tableIndexStatistic
4250     * <LI><B>COLUMN_NAME</B> String => column name; <code>null</code> when TYPE is
4251     * tableIndexStatistic
4252     * <LI><B>ASC_OR_DESC</B> String => column sort sequence, "A" => ascending,
4253     * "D" => descending, may be <code>null</code> if sort sequence is not supported;
4254     * <code>null</code> when TYPE is tableIndexStatistic
4255     * <LI><B>CARDINALITY</B> int => When TYPE is tableIndexStatistic, then
4256     * this is the number of rows in the table; otherwise, it is the
4257     * number of unique values in the index.
4258     * <LI><B>PAGES</B> int => When TYPE is tableIndexStatisic then
4259     * this is the number of pages used for the table, otherwise it
4260     * is the number of pages used for the current index.
4261     * <LI><B>FILTER_CONDITION</B> String => Filter condition, if any.
4262     * (may be <code>null</code>)
4263     * </OL> <p>
4264     *
4265     * <!-- start release-specific documentation -->
4266     * <div class="ReleaseSpecificDocumentation">
4267     * <h3>HSQLDB-Specific Information:</h3> <p>
4268     *
4269     * HSQLDB treats unquoted identifiers as case insensitive in SQL but stores
4270     * them in upper case; it treats quoted identifiers as case sensitive and
4271     * stores them verbatim. All jdbcDatabaseMetaData methods perform
4272     * case-sensitive comparison between name (pattern) arguments and the
4273     * corresponding identifier values as they are stored in the database.
4274     * Therefore, care must be taken to specify name arguments precisely
4275     * (including case) as they are stored in the database. <p>
4276     *
4277     * Since 1.7.2, this feature is supported by default. If the jar is
4278     * compiled without org.hsqldb.DatabaseInformationFull or
4279     * org.hsqldb.DatabaseInformationMain, the feature is
4280     * not supported. The default implementation is
4281     * {@link org.hsqldb.DatabaseInformationFull}.
4282     * </div>
4283     * <!-- end release-specific documentation -->
4284     *
4285     * @param catalog a catalog name; must match the catalog name as it
4286     * is stored in this database; "" retrieves those without a catalog;
4287     * <code>null</code> means that the catalog name should not be used
4288     * to narrow the search
4289     * @param schema a schema name; must match the schema name
4290     * as it is stored in this database; "" retrieves those without a
4291     * schema; <code>null</code> means that the schema name should not be
4292     * used to narrow the search
4293     * @param table a table name; must match the table name as it is stored
4294     * in this database
4295     * @param unique when true, return only indices for unique values;
4296     * when false, return indices regardless of whether unique or not
4297     * @param approximate when true, result is allowed to reflect approximate
4298     * or out of date values; when false, results are requested to be
4299     * accurate
4300     * @return <code>ResultSet</code> - each row is an index column description
4301     * @exception SQLException if a database access error occurs
4302     * @see #supportsMixedCaseQuotedIdentifiers
4303     * @see #storesUpperCaseIdentifiers
4304     */

4305
4306// fredt@users 20020526 - comment - changed to exact table name
4307
public ResultSet JavaDoc getIndexInfo(String JavaDoc catalog, String JavaDoc schema,
4308                                  String JavaDoc table, boolean unique,
4309                                  boolean approximate) throws SQLException JavaDoc {
4310
4311        if (table == null) {
4312            Util.sqlException(Trace.INVALID_JDBC_ARGUMENT);
4313        }
4314
4315        schema = translateSchema(schema);
4316
4317        Boolean JavaDoc nu = (unique) ? Boolean.FALSE
4318                              : null;
4319        StringBuffer JavaDoc select =
4320            toQueryPrefix("SYSTEM_INDEXINFO").append(and("TABLE_CAT", "=",
4321                catalog)).append(and("TABLE_SCHEM", "=",
4322                                     schema)).append(and("TABLE_NAME", "=",
4323                                         table)).append(and("NON_UNIQUE",
4324                                             "=", nu));
4325
4326        // By default, this query already returns the table ordered by
4327
// NON_UNIQUE, TYPE, INDEX_NAME, and ORDINAL_POSITION...
4328
return execute(select.toString());
4329    }
4330
4331    //--------------------------JDBC 2.0-----------------------------
4332

4333    /**
4334     * Retrieves whether this database supports the given result set type. <p>
4335     *
4336     * @param type defined in <code>java.sql.ResultSet</code>
4337     * @return <code>true</code> if so; <code>false</code> otherwise
4338     * @exception SQLException if a database access error occurs
4339     * @see jdbcConnection
4340     * @since JDK 1.2 (JDK 1.1.x developers: read the new overview
4341     * for jdbcDatabaseMetaData)
4342     */

4343    public boolean supportsResultSetType(int type) throws SQLException JavaDoc {
4344        return (type == jdbcResultSet.TYPE_FORWARD_ONLY
4345                || type == jdbcResultSet.TYPE_SCROLL_INSENSITIVE);
4346    }
4347
4348    /**
4349     * Retrieves whether this database supports the given concurrency type
4350     * in combination with the given result set type. <p>
4351     *
4352     * @param type defined in <code>java.sql.ResultSet</code>
4353     * @param concurrency type defined in <code>java.sql.ResultSet</code>
4354     * @return <code>true</code> if so; <code>false</code> otherwise
4355     * @exception SQLException if a database access error occurs
4356     * @see jdbcConnection
4357     * @since JDK 1.2 (JDK 1.1.x developers: read the new overview
4358     * for jdbcDatabaseMetaData)
4359     */

4360    public boolean supportsResultSetConcurrency(int type,
4361            int concurrency) throws SQLException JavaDoc {
4362        return supportsResultSetType(type)
4363               && concurrency == jdbcResultSet.CONCUR_READ_ONLY;
4364    }
4365
4366    /**
4367     * Retrieves whether for the given type of <code>ResultSet</code> object,
4368     * the result set's own updates are visible. <p>
4369     *
4370     * <!-- start release-specific documentation -->
4371     * <div class="ReleaseSpecificDocumentation">
4372     * <h3>HSQLDB-Specific Information:</h3> <p>
4373     *
4374     * Up to and including 1.7.2, HSQLDB does not support updateable
4375     * result sets; this method always returns <code>false</code>.
4376     * </div>
4377     * <!-- end release-specific documentation -->
4378     * @param type the <code>ResultSet</code> type; one of
4379     * <code>ResultSet.TYPE_FORWARD_ONLY</code>,
4380     * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
4381     * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
4382     * @return <code>true</code> if updates are visible for the given result set type;
4383     * <code>false</code> otherwise
4384     * @exception SQLException if a database access error occurs
4385     * @since JDK 1.2 (JDK 1.1.x developers: read the new overview
4386     * for jdbcDatabaseMetaData)
4387     */

4388    public boolean ownUpdatesAreVisible(int type) throws SQLException JavaDoc {
4389        return false;
4390    }
4391
4392    /**
4393     * Retrieves whether a result set's own deletes are visible. <p>
4394     *
4395     * <!-- start release-specific documentation -->
4396     * <div class="ReleaseSpecificDocumentation">
4397     * <h3>HSQLDB-Specific Information:</h3> <p>
4398     *
4399     * Up to and including 1.7.2, HSQLDB does not support updateable
4400     * result sets; this method always returns <code>false</code>.
4401     * </div>
4402     * <!-- end release-specific documentation -->
4403     * @param type the <code>ResultSet</code> type; one of
4404     * <code>ResultSet.TYPE_FORWARD_ONLY</code>,
4405     * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
4406     * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
4407     * @return <code>true</code> if deletes are visible for the given result set type;
4408     * <code>false</code> otherwise
4409     * @exception SQLException if a database access error occurs
4410     * @since JDK 1.2 (JDK 1.1.x developers: read the new overview
4411     * for jdbcDatabaseMetaData)
4412     */

4413    public boolean ownDeletesAreVisible(int type) throws SQLException JavaDoc {
4414        return false;
4415    }
4416
4417    /**
4418     * Retrieves whether a result set's own inserts are visible. <p>
4419     *
4420     * <!-- start release-specific documentation -->
4421     * <div class="ReleaseSpecificDocumentation">
4422     * <h3>HSQLDB-Specific Information:</h3> <p>
4423     *
4424     * Up to and including 1.7.2, HSQLDB does not support updateable
4425     * result sets; this method always returns <code>false</code>.
4426     * </div>
4427     * <!-- end release-specific documentation -->
4428     * @param type the <code>ResultSet</code> type; one of
4429     * <code>ResultSet.TYPE_FORWARD_ONLY</code>,
4430     * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
4431     * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
4432     * @return <code>true</code> if inserts are visible for the given result set type;
4433     * <code>false</code> otherwise
4434     * @exception SQLException if a database access error occurs
4435     * @since JDK 1.2 (JDK 1.1.x developers: read the new overview
4436     * for jdbcDatabaseMetaData)
4437     */

4438    public boolean ownInsertsAreVisible(int type) throws SQLException JavaDoc {
4439        return false;
4440    }
4441
4442    /**
4443     * Retrieves whether updates made by others are visible. <p>
4444     *
4445     * <!-- start release-specific documentation -->
4446     * <div class="ReleaseSpecificDocumentation">
4447     * <h3>HSQLDB-Specific Information:</h3> <p>
4448     *
4449     * Up to and including 1.7.2, HSQLDB does not support updateable
4450     * result sets; this method always returns <code>false</code>.
4451     * </div>
4452     * <!-- end release-specific documentation -->
4453     * @param type the <code>ResultSet</code> type; one of
4454     * <code>ResultSet.TYPE_FORWARD_ONLY</code>,
4455     * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
4456     * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
4457     * @return <code>true</code> if updates made by others
4458     * are visible for the given result set type;
4459     * <code>false</code> otherwise
4460     * @exception SQLException if a database access error occurs
4461     * @since JDK 1.2 (JDK 1.1.x developers: read the new overview
4462     * for jdbcDatabaseMetaData)
4463     */

4464    public boolean othersUpdatesAreVisible(int type) throws SQLException JavaDoc {
4465        return false;
4466    }
4467
4468    /**
4469     * Retrieves whether deletes made by others are visible. <p>
4470     *
4471     * <!-- start release-specific documentation -->
4472     * <div class="ReleaseSpecificDocumentation">
4473     * <h3>HSQLDB-Specific Information:</h3> <p>
4474     *
4475     * Up to and including 1.7.2, HSQLDB does not support updateable
4476     * result sets; this method always returns <code>false</code>.
4477     * </div>
4478     * <!-- end release-specific documentation -->
4479     * @param type the <code>ResultSet</code> type; one of
4480     * <code>ResultSet.TYPE_FORWARD_ONLY</code>,
4481     * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
4482     * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
4483     * @return <code>true</code> if deletes made by others
4484     * are visible for the given result set type;
4485     * <code>false</code> otherwise
4486     * @exception SQLException if a database access error occurs
4487     * @since JDK 1.2 (JDK 1.1.x developers: read the new overview
4488     * for jdbcDatabaseMetaData)
4489     */

4490    public boolean othersDeletesAreVisible(int type) throws SQLException JavaDoc {
4491        return false;
4492    }
4493
4494    /**
4495     * Retrieves whether inserts made by others are visible. <p>
4496     *
4497     * <!-- start release-specific documentation -->
4498     * <div class="ReleaseSpecificDocumentation">
4499     * <h3>HSQLDB-Specific Information:</h3> <p>
4500     *
4501     * Up to and including 1.7.2, HSQLDB does not support updateable
4502     * result sets; this method always returns <code>false</code>.
4503     * </div>
4504     * <!-- end release-specific documentation -->
4505     * @param type the <code>ResultSet</code> type; one of
4506     * <code>ResultSet.TYPE_FORWARD_ONLY</code>,
4507     * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
4508     * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
4509     * @return <code>true</code> if inserts made by others
4510     * are visible for the given result set type;
4511     * <code>false</code> otherwise
4512     * @exception SQLException if a database access error occurs
4513     * @since JDK 1.2 (JDK 1.1.x developers: read the new overview
4514     * for jdbcDatabaseMetaData)
4515     */

4516    public boolean othersInsertsAreVisible(int type) throws SQLException JavaDoc {
4517        return false;
4518    }
4519
4520    /**
4521     * Retrieves whether or not a visible row update can be detected by
4522     * calling the method <code>ResultSet.rowUpdated</code>. <p>
4523     *
4524     * <!-- start release-specific documentation -->
4525     * <div class="ReleaseSpecificDocumentation">
4526     * <h3>HSQLDB-Specific Information:</h3> <p>
4527     *
4528     * Up to and including 1.7.2, HSQLDB does not support updateable
4529     * result sets; this method always returns <code>false</code>.
4530     * </div>
4531     * <!-- end release-specific documentation -->
4532     * @param type the <code>ResultSet</code> type; one of
4533     * <code>ResultSet.TYPE_FORWARD_ONLY</code>,
4534     * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
4535     * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
4536     * @return <code>true</code> if changes are detected by the result set type;
4537     * <code>false</code> otherwise
4538     * @exception SQLException if a database access error occurs
4539     * @since JDK 1.2 (JDK 1.1.x developers: read the new overview
4540     * for jdbcDatabaseMetaData)
4541     */

4542    public boolean updatesAreDetected(int type) throws SQLException JavaDoc {
4543        return false;
4544    }
4545
4546    /**
4547     * Retrieves whether or not a visible row delete can be detected by
4548     * calling the method <code>ResultSet.rowDeleted</code>. If the method
4549     * <code>deletesAreDetected</code> returns <code>false</code>, it means that
4550     * deleted rows are removed from the result set. <p>
4551     *
4552     * <!-- start release-specific documentation -->
4553     * <div class="ReleaseSpecificDocumentation">
4554     * <h3>HSQLDB-Specific Information:</h3> <p>
4555     *
4556     * Including 1.7.2, HSQLDB does not support updateable
4557     * result sets; this method <em>always</em> returns <code>false</code>.
4558     * </div>
4559     * <!-- end release-specific documentation -->
4560     *
4561     *
4562     * @param type the <code>ResultSet</code> type; one of
4563     * <code>ResultSet.TYPE_FORWARD_ONLY</code>,
4564     * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
4565     * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
4566     * @return <code>true</code> if deletes are detected by the given result set type;
4567     * <code>false</code> otherwise
4568     * @exception SQLException if a database access error occurs
4569     * @since JDK 1.2 (JDK 1.1.x developers: read the new overview
4570     * for jdbcDatabaseMetaData)
4571     */

4572    public boolean deletesAreDetected(int type) throws SQLException JavaDoc {
4573        return false;
4574    }
4575
4576    /**
4577     * Retrieves whether or not a visible row insert can be detected
4578     * by calling the method <code>ResultSet.rowInserted</code>. <p>
4579     *
4580     * <!-- start release-specific documentation -->
4581     * <div class="ReleaseSpecificDocumentation">
4582     * <h3>HSQLDB-Specific Information:</h3> <p>
4583     *
4584     * Up to and including 1.7.2, HSQLDB does not support updateable
4585     * result sets; this method always returns <code>false</code>.
4586     * </div>
4587     * <!-- end release-specific documentation -->
4588     * @param type the <code>ResultSet</code> type; one of
4589     * <code>ResultSet.TYPE_FORWARD_ONLY</code>,
4590     * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
4591     * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
4592     * @return <code>true</code> if changes are detected by the specified result
4593     * set type; <code>false</code> otherwise
4594     * @exception SQLException if a database access error occurs
4595     * @since JDK 1.2 (JDK 1.1.x developers: read the new overview
4596     * for jdbcDatabaseMetaData)
4597     */

4598    public boolean insertsAreDetected(int type) throws SQLException JavaDoc {
4599        return false;
4600    }
4601
4602    /**
4603     * Retrieves whether this database supports batch updates. <p>
4604     *
4605     * <!-- start release-specific documentation -->
4606     * <div class="ReleaseSpecificDocumentation">
4607     * <h3>HSQLDB-Specific Information:</h3> <p>
4608     *
4609     * Starting with 1.7.2, HSQLDB supports batch updates;
4610     * this method always returns <code>true</code>.
4611     * </div>
4612     * <!-- end release-specific documentation -->
4613     * @return <code>true</code> if this database supports batch upcates;
4614     * <code>false</code> otherwise
4615     * @exception SQLException if a database access error occurs
4616     * @since JDK 1.2 (JDK 1.1.x developers: read the new overview
4617     * for jdbcDatabaseMetaData)
4618     */

4619    public boolean supportsBatchUpdates() throws SQLException JavaDoc {
4620        return true;
4621    }
4622
4623    /**
4624     * Retrieves a description of the user-defined types (UDTs) defined
4625     * in a particular schema. Schema-specific UDTs may have type
4626     * <code>JAVA_OBJECT</code>, <code>STRUCT</code>,
4627     * or <code>DISTINCT</code>.
4628     *
4629     * <P>Only types matching the catalog, schema, type name and type
4630     * criteria are returned. They are ordered by DATA_TYPE, TYPE_SCHEM
4631     * and TYPE_NAME. The type name parameter may be a fully-qualified
4632     * name. In this case, the catalog and schemaPattern parameters are
4633     * ignored.
4634     *
4635     * <P>Each type description has the following columns:
4636     * <OL>
4637     * <LI><B>TYPE_CAT</B> String => the type's catalog (may be <code>null</code>)
4638     * <LI><B>TYPE_SCHEM</B> String => type's schema (may be <code>null</code>)
4639     * <LI><B>TYPE_NAME</B> String => type name
4640     * <LI><B>CLASS_NAME</B> String => Java class name
4641     * <LI><B>DATA_TYPE</B> String => type value defined in java.sql.Types.
4642     * One of JAVA_OBJECT, STRUCT, or DISTINCT
4643     * <LI><B>REMARKS</B> String => explanatory comment on the type
4644     * <LI><B>BASE_TYPE</B> short => type code of the source type of a
4645     * DISTINCT type or the type that implements the user-generated
4646     * reference type of the SELF_REFERENCING_COLUMN of a structured
4647     * type as defined in java.sql.Types (<code>null</code> if DATA_TYPE is not
4648     * DISTINCT or not STRUCT with REFERENCE_GENERATION = USER_DEFINED)
4649     * </OL>
4650     *
4651     * <P><B>Note:</B> If the driver does not support UDTs, an empty
4652     * result set is returned. <p>
4653     *
4654     * <!-- start release-specific documentation -->
4655     * <div class="ReleaseSpecificDocumentation">
4656     * <h3>HSQLDB-Specific Information:</h3> <p>
4657     *
4658     * HSQLDB treats unquoted identifiers as case insensitive in SQL but stores
4659     * them in upper case; it treats quoted identifiers as case sensitive and
4660     * stores them verbatim. All jdbcDatabaseMetaData methods perform
4661     * case-sensitive comparison between name (pattern) arguments and the
4662     * corresponding identifier values as they are stored in the database.
4663     * Therefore, care must be taken to specify name arguments precisely
4664     * (including case) as they are stored in the database. <p>
4665     *
4666     * Up to and including 1.7.1, HSQLDB does not support UDTs and
4667     * thus produces an empty result. <p>
4668     *
4669     * Starting with 1.7.2, there is an option to support this feature
4670     * to greater or lesser degrees. See the documentation specific to the
4671     * selected system table provider implementation. The default implementation
4672     * is org.hsqldb.DatabaseInformationFull.
4673     * </div>
4674     * <!-- end release-specific documentation -->
4675     * @param catalog a catalog name; must match the catalog name as it
4676     * is stored in the database; "" retrieves those without a catalog;
4677     * <code>null</code> means that the catalog name should not be used
4678     * to narrow the search
4679     * @param schemaPattern a schema pattern name; must match the schema name
4680     * as it is stored in the database; "" retrieves those without a
4681     * schema; <code>null</code> means that the schema name should not be
4682     * used to narrow the search
4683     * @param typeNamePattern a type name pattern; must match the type name
4684     * as it is stored in the database; may be a fully qualified name
4685     * @param types a list of user-defined types (JAVA_OBJECT,
4686     * STRUCT, or DISTINCT) to include; <code>null</code> returns
4687     * all types
4688     * @return <code>ResultSet</code> object in which each row describes a UDT
4689     * @exception SQLException if a database access error occurs
4690     * @since JDK 1.2 (JDK 1.1.x developers: read the new overview
4691     * for jdbcDatabaseMetaData)
4692     */

4693    public ResultSet JavaDoc getUDTs(String JavaDoc catalog, String JavaDoc schemaPattern,
4694                             String JavaDoc typeNamePattern,
4695                             int[] types) throws SQLException JavaDoc {
4696
4697        if (wantsIsNull(typeNamePattern)
4698                || (types != null && types.length == 0)) {
4699            executeSelect("SYSTEM_UDTS", "0=1");
4700        }
4701
4702        schemaPattern = translateSchema(schemaPattern);
4703
4704        StringBuffer JavaDoc select =
4705            toQueryPrefix("SYSTEM_UDTS").append(and("TYPE_CAT", "=",
4706                catalog)).append(and("TYPE_SCHEM", "LIKE",
4707                                     schemaPattern)).append(and("TYPE_NAME",
4708                                         "LIKE", typeNamePattern));
4709
4710        if (types == null) {
4711
4712            // do not use to narrow search
4713
} else {
4714            select.append(" AND DATA_TYPE IN (").append(
4715                StringUtil.getList(types, ",", "'")).append(')');
4716        }
4717
4718        // By default, the query already returns a result ordered by
4719
// DATA_TYPE, TYPE_SCHEM, and TYPE_NAME...
4720
return execute(select.toString());
4721    }
4722
4723    /**
4724     * Retrieves the connection that produced this metadata object. <p>
4725     *
4726     * @return the connection that produced this metadata object
4727     * @exception SQLException if a database access error occurs
4728     * @since JDK 1.2 (JDK 1.1.x developers: read the new overview
4729     * for jdbcDatabaseMetaData)
4730     */

4731    public Connection JavaDoc getConnection() throws SQLException JavaDoc {
4732        return connection;
4733    }
4734
4735// boucherb@users 20020426 - javadocs for all JDBC 3 methods
4736
// boucherb@users 20020426 - todos
4737
// ------------------- JDBC 3.0 -------------------------
4738

4739    /**
4740     * Retrieves whether this database supports savepoints. <p>
4741     *
4742     * <!-- start release-specific documentation -->
4743     * <div class="ReleaseSpecificDocumentation">
4744     * <h3>HSQLDB-Specific Information:</h3> <p>
4745     *
4746     * Beginning with 1.7.2, this SQL feature is supported
4747     * through JDBC as well as SQL. <p>
4748     *
4749     * </div>
4750     * <!-- end release-specific documentation -->
4751     * @return <code>true</code> if savepoints are supported;
4752     * <code>false</code> otherwise
4753     * @exception SQLException if a database access error occurs
4754     * @since JDK 1.4, HSQLDB 1.7
4755     */

4756//#ifdef JDBC3
4757
public boolean supportsSavepoints() throws SQLException JavaDoc {
4758        return true;
4759    }
4760
4761//#endif JDBC3
4762

4763    /**
4764     * Retrieves whether this database supports named parameters to callable
4765     * statements. <p>
4766     *
4767     * <!-- start release-specific documentation -->
4768     * <div class="ReleaseSpecificDocumentation">
4769     * <h3>HSQLDB-Specific Information:</h3> <p>
4770     *
4771     * Starting with 1.7.2, HSQLDB supports JDBC named parameters to
4772     * callable statements; this method returns true. <p>
4773     *
4774     * </div>
4775     * <!-- end release-specific documentation -->
4776     * @return <code>true</code> if named parameters are supported;
4777     * <code>false</code> otherwise
4778     * @exception SQLException if a database access error occurs
4779     * @since JDK 1.4, HSQLDB 1.7
4780     */

4781//#ifdef JDBC3
4782
public boolean supportsNamedParameters() throws SQLException JavaDoc {
4783        return true;
4784    }
4785
4786//#endif JDBC3
4787

4788    /**
4789     * Retrieves whether it is possible to have multiple <code>ResultSet</code>
4790     * objects returned from a <code>CallableStatement</code> object
4791     * simultaneously. <p>
4792     *
4793     * <!-- start release-specific documentation -->
4794     * <div class="ReleaseSpecificDocumentation">
4795     * <h3>HSQLDB-Specific Information:</h3> <p>
4796     *
4797     * Up to and including 1.7.2, HSQLDB does not support multiple ResultSet
4798     * objects returned from a <code>CallableStatement</code> object at all;
4799     * this method always returns <code>false</code>. <p>
4800     *
4801     * </div>
4802     * <!-- end release-specific documentation -->
4803     * @return <code>true</code> if a <code>CallableStatement</code> object
4804     * can return multiple <code>ResultSet</code> objects
4805     * simultaneously; <code>false</code> otherwise
4806     * @exception SQLException if a database access error occurs
4807     * @since JDK 1.4, HSQLDB 1.7
4808     */

4809//#ifdef JDBC3
4810
public boolean supportsMultipleOpenResults() throws SQLException JavaDoc {
4811        return false;
4812    }
4813
4814//#endif JDBC3
4815

4816    /**
4817     * Retrieves whether auto-generated keys can be retrieved after
4818     * a statement has been executed. <p>
4819     *
4820     * <!-- start release-specific documentation -->
4821     * <div class="ReleaseSpecificDocumentation">
4822     * <h3>HSQLDB-Specific Information:</h3> <p>
4823     *
4824     * Up to and including 1.7.2, HSQLDB does not support retrieving
4825     * autogenerated keys through the JDBC interface at all, although
4826     * it is possible to retrieve them in a proprietary fashion;
4827     * this method always returns <code>false</code>. <p>
4828     *
4829     * </div>
4830     * <!-- end release-specific documentation -->
4831     * @return <code>true</code> if auto-generated keys can be retrieved
4832     * after a statement has executed; <code>false</code> otherwise
4833     * @exception SQLException if a database access error occurs
4834     * @since JDK 1.4, HSQLDB 1.7
4835     */

4836//#ifdef JDBC3
4837
public boolean supportsGetGeneratedKeys() throws SQLException JavaDoc {
4838        return false;
4839    }
4840
4841//#endif JDBC3
4842

4843    /**
4844     * Retrieves a description of the user-defined type (UDT) hierarchies defined in a
4845     * particular schema in this database. Only the immediate super type
4846     * sub type relationship is modeled.
4847     * <P>
4848     * Only supertype information for UDTs matching the catalog,
4849     * schema, and type name is returned. The type name parameter
4850     * may be a fully-qualified name. When the UDT name supplied is a
4851     * fully-qualified name, the catalog and schemaPattern parameters are
4852     * ignored.
4853     * <P>
4854     * If a UDT does not have a direct super type, it is not listed here.
4855     * A row of the <code>ResultSet</code> object returned by this method
4856     * describes the designated UDT and a direct supertype. A row has the following
4857     * columns:
4858     * <OL>
4859     * <LI><B>TYPE_CAT</B> String => the UDT's catalog (may be <code>null</code>)
4860     * <LI><B>TYPE_SCHEM</B> String => UDT's schema (may be <code>null</code>)
4861     * <LI><B>TYPE_NAME</B> String => type name of the UDT
4862     * <LI><B>SUPERTYPE_CAT</B> String => the direct super type's catalog
4863     * (may be <code>null</code>)
4864     * <LI><B>SUPERTYPE_SCHEM</B> String => the direct super type's schema
4865     * (may be <code>null</code>)
4866     * <LI><B>SUPERTYPE_NAME</B> String => the direct super type's name
4867     * </OL>
4868     *
4869     * <P><B>Note:</B> If the driver does not support type hierarchies, an
4870     * empty result set is returned. <p>
4871     *
4872     * <!-- start release-specific documentation -->
4873     * <div class="ReleaseSpecificDocumentation">
4874     * <h3>HSQLDB-Specific Information:</h3> <p>
4875     *
4876     * HSQLDB treats unquoted identifiers as case insensitive in SQL but stores
4877     * them in upper case; it treats quoted identifiers as case sensitive and
4878     * stores them verbatim. All jdbcDatabaseMetaData methods perform
4879     * case-sensitive comparison between name (pattern) arguments and the
4880     * corresponding identifier values as they are stored in the database.
4881     * Therefore, care must be taken to specify name arguments precisely
4882     * (including case) as they are stored in the database. <p>
4883     *
4884     * Including 1.7.1, this JDBC feature is not supported; calling
4885     * this method throws a SQLException stating that the operation
4886     * is not supported. <p>
4887     *
4888     * Since 1.7.2, this feature is supported by default. If the jar is
4889     * compiled without org.hsqldb.DatabaseInformationFull or
4890     * org.hsqldb.DatabaseInformationMain, the feature is
4891     * not supported. The default implementation is
4892     * {@link org.hsqldb.DatabaseInformationFull}.
4893     * </div>
4894     * <!-- end release-specific documentation -->
4895     *
4896     * @param catalog a catalog name; "" retrieves those without a catalog;
4897     * <code>null</code> means drop catalog name from the selection
4898     * criteria
4899     * @param schemaPattern a schema name pattern; "" retrieves those
4900     * without a schema
4901     * @param typeNamePattern a UDT name pattern; may be a fully-qualified
4902     * name
4903     * @return a <code>ResultSet</code> object in which a row gives information
4904     * about the designated UDT
4905     * @throws SQLException if a database access error occurs
4906     * @since JDK 1.4, HSQLDB 1.7
4907     */

4908//#ifdef JDBC3
4909
public ResultSet JavaDoc getSuperTypes(String JavaDoc catalog, String JavaDoc schemaPattern,
4910                                   String JavaDoc typeNamePattern)
4911                                   throws SQLException JavaDoc {
4912
4913        if (wantsIsNull(typeNamePattern)) {
4914            return executeSelect("SYSTEM_SUPERTYPES", "0=1");
4915        }
4916
4917        schemaPattern = translateSchema(schemaPattern);
4918
4919        StringBuffer JavaDoc select =
4920            toQueryPrefix("SYSTEM_SUPERTYPES").append(and("TYPE_CAT", "=",
4921                catalog)).append(and("TYPE_SCHEM", "LIKE",
4922                                     schemaPattern)).append(and("TYPE_NAME",
4923                                         "LIKE", typeNamePattern));
4924
4925        return execute(select.toString());
4926    }
4927
4928//#endif JDBC3
4929

4930    /**
4931     * Retrieves a description of the table hierarchies defined in a particular
4932     * schema in this database.
4933     *
4934     * <P>Only supertable information for tables matching the catalog, schema
4935     * and table name are returned. The table name parameter may be a fully-
4936     * qualified name, in which case, the catalog and schemaPattern parameters
4937     * are ignored. If a table does not have a super table, it is not listed here.
4938     * Supertables have to be defined in the same catalog and schema as the
4939     * sub tables. Therefore, the type description does not need to include
4940     * this information for the supertable.
4941     *
4942     * <P>Each type description has the following columns:
4943     * <OL>
4944     * <LI><B>TABLE_CAT</B> String => the type's catalog (may be <code>null</code>)
4945     * <LI><B>TABLE_SCHEM</B> String => type's schema (may be <code>null</code>)
4946     * <LI><B>TABLE_NAME</B> String => type name
4947     * <LI><B>SUPERTABLE_NAME</B> String => the direct super type's name
4948     * </OL>
4949     *
4950     * <P><B>Note:</B> If the driver does not support type hierarchies, an
4951     * empty result set is returned. <p>
4952     *
4953     * <!-- start release-specific documentation -->
4954     * <div class="ReleaseSpecificDocumentation">
4955     * <h3>HSQLDB-Specific Information:</h3> <p>
4956     *
4957     * HSQLDB treats unquoted identifiers as case insensitive in SQL but stores
4958     * them in upper case; it treats quoted identifiers as case sensitive and
4959     * stores them verbatim. All jdbcDatabaseMetaData methods perform
4960     * case-sensitive comparison between name (pattern) arguments and the
4961     * corresponding identifier values as they are stored in the database.
4962     * Therefore, care must be taken to specify name arguments precisely
4963     * (including case) as they are stored in the database. <p>
4964     *
4965     * Since 1.7.2, this feature is supported by default. If the jar is
4966     * compiled without org.hsqldb.DatabaseInformationFull or
4967     * org.hsqldb.DatabaseInformationMain, the feature is
4968     * not supported. The default implementation is
4969     * {@link org.hsqldb.DatabaseInformationFull}.
4970     * </div>
4971     * <!-- end release-specific documentation -->
4972     *
4973     * @param catalog a catalog name; "" retrieves those without a catalog;
4974     * <code>null</code> means drop catalog name from the selection
4975     * criteria
4976     * @param schemaPattern a schema name pattern; "" retrieves those
4977     * without a schema
4978     * @param tableNamePattern a table name pattern; may be a fully-qualified
4979     * name
4980     * @return a <code>ResultSet</code> object in which each row is a type
4981     * description
4982     * @throws SQLException if a database access error occurs
4983     * @since JDK 1.4, HSQLDB 1.7
4984     */

4985//#ifdef JDBC3
4986
public ResultSet JavaDoc getSuperTables(String JavaDoc catalog, String JavaDoc schemaPattern,
4987                                    String JavaDoc tableNamePattern)
4988                                    throws SQLException JavaDoc {
4989
4990        if (wantsIsNull(tableNamePattern)) {
4991            return executeSelect("SYSTEM_SUPERTABLES", "0=1");
4992        }
4993
4994        schemaPattern = translateSchema(schemaPattern);
4995
4996        StringBuffer JavaDoc select =
4997            toQueryPrefix("SYSTEM_SUPERTABLES").append(and("TABLE_CAT", "=",
4998                catalog)).append(and("TABLE_SCHEM", "LIKE",
4999                                     schemaPattern)).append(and("TABLE_NAME",
5000                                         "LIKE", tableNamePattern));
5001
5002        return execute(select.toString());
5003    }
5004
5005//#endif JDBC3
5006

5007    /**
5008     * Retrieves a description of the given attribute of the given type
5009     * for a user-defined type (UDT) that is available in the given schema
5010     * and catalog.
5011     * <P>
5012     * Descriptions are returned only for attributes of UDTs matching the
5013     * catalog, schema, type, and attribute name criteria. They are ordered by
5014     * TYPE_SCHEM, TYPE_NAME and ORDINAL_POSITION. This description
5015     * does not contain inherited attributes.
5016     * <P>
5017     * The <code>ResultSet</code> object that is returned has the following
5018     * columns:
5019     * <OL>
5020     * <LI><B>TYPE_CAT</B> String => type catalog (may be <code>null</code>)
5021     * <LI><B>TYPE_SCHEM</B> String => type schema (may be <code>null</code>)
5022     * <LI><B>TYPE_NAME</B> String => type name
5023     * <LI><B>ATTR_NAME</B> String => attribute name
5024     * <LI><B>DATA_TYPE</B> short => attribute type SQL type from java.sql.Types
5025     * <LI><B>ATTR_TYPE_NAME</B> String => Data source dependent type name.
5026     * For a UDT, the type name is fully qualified. For a REF, the type name is
5027     * fully qualified and represents the target type of the reference type.
5028     * <LI><B>ATTR_SIZE</B> int => column size. For char or date
5029     * types this is the maximum number of characters; for numeric or
5030     * decimal types this is precision.
5031     * <LI><B>DECIMAL_DIGITS</B> int => the number of fractional digits
5032     * <LI><B>NUM_PREC_RADIX</B> int => Radix (typically either 10 or 2)
5033     * <LI><B>NULLABLE</B> int => whether NULL is allowed
5034     * <UL>
5035     * <LI> attributeNoNulls - might not allow NULL values
5036     * <LI> attributeNullable - definitely allows NULL values
5037     * <LI> attributeNullableUnknown - nullability unknown
5038     * </UL>
5039     * <LI><B>REMARKS</B> String => comment describing column (may be <code>null</code>)
5040     * <LI><B>ATTR_DEF</B> String => default value (may be <code>null</code>)
5041     * <LI><B>SQL_DATA_TYPE</B> int => unused
5042     * <LI><B>SQL_DATETIME_SUB</B> int => unused
5043     * <LI><B>CHAR_OCTET_LENGTH</B> int => for char types the
5044     * maximum number of bytes in the column
5045     * <LI><B>ORDINAL_POSITION</B> int => index of column in table
5046     * (starting at 1)
5047     * <LI><B>IS_NULLABLE</B> String => "NO" means column definitely
5048     * does not allow NULL values; "YES" means the column might
5049     * allow NULL values. An empty string means unknown.
5050     * <LI><B>SCOPE_CATALOG</B> String => catalog of table that is the
5051     * scope of a reference attribute (<code>null</code> if DATA_TYPE isn't REF)
5052     * <LI><B>SCOPE_SCHEMA</B> String => schema of table that is the
5053     * scope of a reference attribute (<code>null</code> if DATA_TYPE isn't REF)
5054     * <LI><B>SCOPE_TABLE</B> String => table name that is the scope of a
5055     * reference attribute (<code>null</code> if the DATA_TYPE isn't REF)
5056     * <LI><B>SOURCE_DATA_TYPE</B> short => source type of a distinct type or user-generated
5057     * Ref type,SQL type from java.sql.Types (<code>null</code> if DATA_TYPE
5058     * isn't DISTINCT or user-generated REF)
5059     * </OL> <p>
5060     *
5061     * <!-- start release-specific documentation -->
5062     * <div class="ReleaseSpecificDocumentation">
5063     * <h3>HSQLDB-Specific Information:</h3> <p>
5064     *
5065     * HSQLDB treats unquoted identifiers as case insensitive in SQL but stores
5066     * them in upper case; it treats quoted identifiers as case sensitive and
5067     * stores them verbatim. All jdbcDatabaseMetaData methods perform
5068     * case-sensitive comparison between name (pattern) arguments and the
5069     * corresponding identifier values as they are stored in the database.
5070     * Therefore, care must be taken to specify name arguments precisely
5071     * (including case) as they are stored in the database. <p>
5072     *
5073     * Including 1.7.1, this JDBC feature is not supported; calling
5074     * this method throws a SQLException stating that the operation
5075     * is not supported. <p>
5076     *
5077     * Since 1.7.2, this feature is supported by default. If the jar is
5078     * compiled without org.hsqldb.DatabaseInformationFull or
5079     * org.hsqldb.DatabaseInformationMain, the feature is
5080     * not supported. The default implementation is
5081     * {@link org.hsqldb.DatabaseInformationFull}.
5082     * </div>
5083     * <!-- end release-specific documentation -->
5084     *
5085     * @param catalog a catalog name; must match the catalog name as it
5086     * is stored in the database; "" retrieves those without a catalog;
5087     * <code>null</code> means that the catalog name should not be used
5088     * to narrow the search
5089     * @param schemaPattern a schema name pattern; must match the schema name
5090     * as it is stored in the database; "" retrieves those without a
5091     * schema; <code>null</code> means that the schema name should not be
5092     * used to narrow the search
5093     * @param typeNamePattern a type name pattern; must match the
5094     * type name as it is stored in the database
5095     * @param attributeNamePattern an attribute name pattern; must match the
5096     * attribute name as it is declared in the database
5097     * @return a <code>ResultSet</code> object in which each row is an
5098     * attribute description
5099     * @exception SQLException if a database access error occurs
5100     * @since JDK 1.4, HSQLDB 1.7
5101     */

5102//#ifdef JDBC3
5103
public ResultSet JavaDoc getAttributes(String JavaDoc catalog, String JavaDoc schemaPattern,
5104                                   String JavaDoc typeNamePattern,
5105                                   String JavaDoc attributeNamePattern)
5106                                   throws SQLException JavaDoc {
5107
5108        if (wantsIsNull(typeNamePattern)
5109                || wantsIsNull(attributeNamePattern)) {
5110            return executeSelect("SYSTEM_UDTATTRIBUTES", "0=1");
5111        }
5112
5113        schemaPattern = translateSchema(schemaPattern);
5114
5115        StringBuffer JavaDoc select = toQueryPrefix("SYSTEM_UDTATTRIBUTES").append(
5116            and("TYPE_CAT", "=", catalog)).append(
5117            and("TYPE_SCHEM", "LIKE", schemaPattern)).append(
5118            and("TYPE_NAME", "LIKE", typeNamePattern)).append(
5119            and("ATTR_NAME", "LIKE", attributeNamePattern));
5120
5121        return execute(select.toString());
5122    }
5123
5124//#endif JDBC3
5125

5126    /**
5127     * Retrieves whether this database supports the given result
5128     * set holdability. <p>
5129     *
5130     * <!-- start release-specific documentation -->
5131     * <div class="ReleaseSpecificDocumentation">
5132     * <h3>HSQLDB-Specific Information:</h3> <p>
5133     *
5134     * Starting with 1.7.2, HSQLDB returns true for
5135     * HOLD_CURSORS_OVER_COMMIT, else false. <p>
5136     *
5137     * </div>
5138     * <!-- end release-specific documentation -->
5139     * @param holdability one of the following constants:
5140     * <code>ResultSet.HOLD_CURSORS_OVER_COMMIT</code> or
5141     * <code>ResultSet.CLOSE_CURSORS_AT_COMMIT</code>
5142     * @return <code>true</code> if so; <code>false</code> otherwise
5143     * @exception SQLException if a database access error occurs
5144     * @see jdbcConnection
5145     * @since JDK 1.4, HSQLDB 1.7
5146     */

5147//#ifdef JDBC3
5148
public boolean supportsResultSetHoldability(int holdability)
5149    throws SQLException JavaDoc {
5150        return holdability == jdbcResultSet.HOLD_CURSORS_OVER_COMMIT;
5151    }
5152
5153//#endif JDBC3
5154

5155    /**
5156     * Retrieves the default holdability of this <code>ResultSet</code>
5157     * object. <p>
5158     *
5159     * <!-- start release-specific documentation -->
5160     * <div class="ReleaseSpecificDocumentation">
5161     * <h3>HSQLDB-Specific Information:</h3> <p>
5162     *
5163     * Starting with HSQLDB 1.7.2, this JDBC feature is supported. <p>
5164     *
5165     * Calling this method returns HOLD_CURSORS_OVER_COMMIT, since HSQLDB
5166     * ResultSet objects are never closed as the result of an implicit
5167     * or explicit commit operation. <p>
5168     *
5169     * </div>
5170     * <!-- end release-specific documentation -->
5171     *
5172     * @return the default holdability; either
5173     * <code>ResultSet.HOLD_CURSORS_OVER_COMMIT</code> or
5174     * <code>ResultSet.CLOSE_CURSORS_AT_COMMIT</code>
5175     * @exception SQLException if a database access error occurs
5176     * @since JDK 1.4, HSQLDB 1.7
5177     */

5178//#ifdef JDBC3
5179
public int getResultSetHoldability() throws SQLException JavaDoc {
5180
5181// JDBC 3.0 fr spec:
5182
// 14.1.3 ResultSet Holdability
5183
//
5184
// Calling the method Connection.commit can close the ResultSet objects that
5185
// have been created during the current transaction. In some cases, however,
5186
// this may not be the desired behaviour. The ResultSet property holdability
5187
// gives the application control over whether ResultSet objects (cursors) are
5188
// closed when a commit operation is implicity or explictly performed.
5189
// The following ResultSet constants may be supplied to the Connection methods
5190
// createStatement, prepareStatement, and prepareCall:
5191
//
5192
// 1. HOLD_CURSORS_OVER_COMMIT
5193
//
5194
// * ResultSet objects (cursors) are not closed; they are held open when a
5195
// commit operation is implicity or explicity performed.
5196
//
5197
// 2. CLOSE_CURSORS_AT_COMMIT
5198
//
5199
// * ResultSet objects (cursors) are closed when a commit operation is
5200
// implicity or explicity performed. Closing cursors at commit can result
5201
// in better performance for some applications.
5202
//
5203
// The default holdability of ResultSet objects is implementation defined.
5204
// The DatabaseMetaData method getResultSetHoldability can be called to
5205
// determine the default holdability of result sets returned by the
5206
// underlying data source.
5207
// --
5208
// boucherb@users 20030819
5209
// Our ResultSet objects are never closed as the result of a commit
5210
return jdbcResultSet.HOLD_CURSORS_OVER_COMMIT;
5211    }
5212
5213//#endif JDBC3
5214

5215    /**
5216     * Retrieves the major version number of the underlying database. <p>
5217     *
5218     * <!-- start release-specific documentation -->
5219     * <div class="ReleaseSpecificDocumentation">
5220     * <h3>HSQLDB-Specific Information:</h3> <p>
5221     *
5222     * Starting with 1.7.2, the feature is supported under JDK14 builds. <p>
5223     *
5224     * This value is retrieved through an SQL call to the new
5225     * {@link Library#getDatabaseMajorVersion} method which allows
5226     * correct determination of the database major version for both local
5227     * and remote database instances.
5228     * </div>
5229     * <!-- end release-specific documentation -->
5230     * @return the underlying database's major version
5231     * @exception SQLException if a database access error occurs
5232     * @since JDK 1.4, HSQLDB 1.7
5233     */

5234//#ifdef JDBC3
5235
public int getDatabaseMajorVersion() throws SQLException JavaDoc {
5236
5237        ResultSet JavaDoc rs =
5238            execute("call \"org.hsqldb.Library.getDatabaseMajorVersion\"()");
5239
5240        rs.next();
5241
5242        int result = rs.getInt(1);
5243
5244        rs.close();
5245
5246        return result;
5247    }
5248
5249//#endif JDBC3
5250

5251    /**
5252     * Retrieves the minor version number of the underlying database. <p>
5253     *
5254     * <!-- start release-specific documentation -->
5255     * <div class="ReleaseSpecificDocumentation">
5256     * <h3>HSQLDB-Specific Information:</h3> <p>
5257     *
5258     * Starting with 1.7.2, the feature is supported under JDK14 builds. <p>
5259     *
5260     * This value is retrieved through an SQL call to the new
5261     * {@link Library#getDatabaseMinorVersion} method which allows
5262     * correct determination of the database minor version for both local
5263     * and remote database instances.
5264     * </div>
5265     * <!-- end release-specific documentation -->
5266     * @return underlying database's minor version
5267     * @exception SQLException if a database access error occurs
5268     * @since JDK 1.4, HSQLDB 1.7
5269     */

5270//#ifdef JDBC3
5271
public int getDatabaseMinorVersion() throws SQLException JavaDoc {
5272
5273        ResultSet JavaDoc rs =
5274            execute("call \"org.hsqldb.Library.getDatabaseMinorVersion\"()");
5275
5276        rs.next();
5277
5278        int result = rs.getInt(1);
5279
5280        rs.close();
5281
5282        return result;
5283    }
5284
5285//#endif JDBC3
5286

5287    /**
5288     * Retrieves the major JDBC version number for this
5289     * driver. <p>
5290     *
5291     * <!-- start release-specific documentation -->
5292     * <div class="ReleaseSpecificDocumentation">
5293     * <h3>HSQLDB-Specific Information:</h3> <p>
5294     *
5295     * Starting with 1.7.2, the feature is supported under JDK14 builds.
5296     * </div>
5297     * <!-- end release-specific documentation -->
5298     *
5299     * @return JDBC version major number
5300     * @exception SQLException if a database access error occurs
5301     * @since JDK 1.4, HSQLDB 1.7
5302     */

5303//#ifdef JDBC3
5304
public int getJDBCMajorVersion() throws SQLException JavaDoc {
5305        return 3;
5306    }
5307
5308//#endif JDBC3
5309

5310    /**
5311     * Retrieves the minor JDBC version number for this
5312     * driver. <p>
5313     *
5314     * <!-- start release-specific documentation -->
5315     * <div class="ReleaseSpecificDocumentation">
5316     * <h3>HSQLDB-Specific Information:</h3> <p>
5317     *
5318     * Starting with 1.7.2, the feature is supported under JDK14 builds.
5319     * </div>
5320     * <!-- end release-specific documentation -->
5321     * @return JDBC version minor number
5322     * @exception SQLException if a database access error occurs
5323     * @since JDK 1.4, HSQLDB 1.7
5324     */

5325//#ifdef JDBC3
5326
public int getJDBCMinorVersion() throws SQLException JavaDoc {
5327        return 0;
5328    }
5329
5330//#endif JDBC3
5331

5332    /**
5333     * @todo fredt@users we haven't checked it all but should aim at
5334     * sqlStateSQL99; Need to review the codes.
5335     */

5336
5337    /**
5338     * Indicates whether the SQLSTATEs returned by
5339     * <code>SQLException.getSQLState</code> is X/Open (now known as Open Group)
5340     * SQL CLI or SQL99. <p>
5341     *
5342     * <!-- start release-specific documentation -->
5343     * <div class="ReleaseSpecificDocumentation">
5344     * <h3>HSQLDB-Specific Information:</h3> <p>
5345     *
5346     * Starting with 1.7.2, HSQLDB returns <code>sqlStateSQL99</code>.
5347     * </div>
5348     * <!-- end release-specific documentation -->
5349     * @return the type of SQLSTATEs, one of:
5350     * sqlStateXOpen or
5351     * sqlStateSQL99
5352     * @throws SQLException if a database access error occurs
5353     * @since JDK 1.4, HSQLDB 1.7
5354     */

5355//#ifdef JDBC3
5356
public int getSQLStateType() throws SQLException JavaDoc {
5357        return sqlStateSQL99;
5358    }
5359
5360//#endif JDBC3
5361

5362    /**
5363     * Indicates whether updates made to a LOB are made on a copy or directly
5364     * to the LOB. <p>
5365     *
5366     * <!-- start release-specific documentation -->
5367     * <div class="ReleaseSpecificDocumentation">
5368     * <h3>HSQLDB-Specific Information:</h3> <p>
5369     *
5370     * Up to and including 1.7.2, HSQLDB updates the LOB directly. This
5371     * method return false.
5372     * </div>
5373     * <!-- end release-specific documentation -->
5374     *
5375     * @return <code>true</code> if updates are made to a copy of the LOB;
5376     * <code>false</code> if updates are made directly to the LOB
5377     * @throws SQLException if a database access error occurs
5378     * @since JDK 1.4, HSQLDB 1.7
5379     */

5380//#ifdef JDBC3
5381
public boolean locatorsUpdateCopy() throws SQLException JavaDoc {
5382        return false;
5383    }
5384
5385//#endif JDBC3
5386

5387    /**
5388     * Retrieves whether this database supports statement pooling. <p>
5389     *
5390     * <!-- start release-specific documentation -->
5391     * <div class="ReleaseSpecificDocumentation">
5392     * <h3>HSQLDB-Specific Information:</h3> <p>
5393     *
5394     * Up to and including 1.7.2, HSQLDB does not support statement pooling.
5395     * This method returns false.
5396     * </div>
5397     * <!-- end release-specific documentation -->
5398     *
5399     * @return <code>true</code> is so;
5400     * <code>false</code> otherwise
5401     * @throws SQLException if a database access error occurs
5402     * @since JDK 1.4, HSQLDB 1.7
5403     */

5404//#ifdef JDBC3
5405
public boolean supportsStatementPooling() throws SQLException JavaDoc {
5406        return false;
5407    }
5408
5409//#endif JDBC3
5410
//----------------------- Internal Implementation --------------------------
5411

5412    /**
5413     * Constructs a new <code>jdbcDatabaseMetaData</code> object using the
5414     * specified connection. This contructor is used by <code>jdbcConnection</code>
5415     * when producing a <code>DatabaseMetaData</code> object from a call to
5416     * {@link jdbcConnection#getMetaData() getMetaData}.
5417     * @param c the connection this object will use to retrieve
5418     * instance-specific metadata
5419     * @throws SQLException never - reserved for future use
5420     */

5421    jdbcDatabaseMetaData(jdbcConnection c) throws SQLException JavaDoc {
5422
5423        // PRE: is non-null and not closed
5424
connection = c;
5425        useSchemaDefault = c.connProperties.isPropertyTrue("default_schema");
5426    }
5427
5428    /**
5429     * Retrieves an "AND" predicate based on the (column) <code>id</code>,
5430     * <code>op</code>(erator) and<code>val</code>(ue) arguments to be
5431     * included in an SQL "WHERE" clause, using the conventions laid out for
5432     * JDBC DatabaseMetaData filter parameter values. <p>
5433     *
5434     * @return an "AND" predicate built from the arguments
5435     * @param id the simple, non-quoted identifier of a system table
5436     * column upon which to filter. <p>
5437     *
5438     * No checking is done for column name validity. <br>
5439     * It is assumed the system table column name is correct. <p>
5440     *
5441     * @param op the conditional operation to perform using the system table
5442     * column name value and the <code>val</code> argument. <p>
5443     *
5444     * @param val an object representing the value to use in some conditional
5445     * operation, op, between the column identified by the id argument
5446     * and this argument. <p>
5447     *
5448     * <UL>
5449     * <LI>null causes the empty string to be returned. <p>
5450     *
5451     * <LI>toString().length() == 0 causes the returned expression
5452     * to be built so that the IS NULL operation will occur
5453     * against the specified column. <p>
5454     *
5455     * <LI>instanceof String causes the returned expression to be
5456     * built so that the specified operation will occur between
5457     * the specified column and the specified value, converted to
5458     * an SQL string (single quoted, with internal single quotes
5459     * escaped by doubling). If <code>op</code> is "LIKE" and
5460     * <code>val</code> does not contain any "%" or "_" wild
5461     * card characters, then <code>op</code> is silently
5462     * converted to "=". <p>
5463     *
5464     * <LI>!instanceof String causes an expression to built so that
5465     * the specified operation will occur between the specified
5466     * column and <code>String.valueOf(val)</code>. <p>
5467     *
5468     * </UL>
5469     */

5470    private static String JavaDoc and(String JavaDoc id, String JavaDoc op, Object JavaDoc val) {
5471
5472        // The JDBC standard for pattern arguments seems to be:
5473
//
5474
// - pass null to mean ignore (do not include in query),
5475
// - pass "" to mean filter on <column-ident> IS NULL,
5476
// - pass "%" to filter on <column-ident> IS NOT NULL.
5477
// - pass sequence with "%" and "_" for wildcard matches
5478
// - when searching on values reported directly from DatabaseMetaData
5479
// results, typically an exact match is desired. In this case, it
5480
// is the client's responsibility to escape any reported "%" and "_"
5481
// characters using whatever DatabaseMetaData returns from
5482
// getSearchEscapeString(). In our case, this is the standard escape
5483
// character: '\'. Typically, '%' will rarely be encountered, but
5484
// certainly '_' is to be expected on a regular basis.
5485
// - checkme: what about the (silly) case where an identifier
5486
// has been declared such as: 'create table "xxx\_yyy"(...)'?
5487
// Must the client still escape the Java string like this:
5488
// "xxx\\\\_yyy"?
5489
// Yes: because otherwise the driver is expected to
5490
// construct something like:
5491
// select ... where ... like 'xxx\_yyy' escape '\'
5492
// which will try to match 'xxx_yyy', not 'xxx\_yyy'
5493
// Testing indicates that indeed, higher quality popular JDBC
5494
// database browsers do the escapes "properly."
5495
if (val == null) {
5496            return "";
5497        }
5498
5499        StringBuffer JavaDoc sb = new StringBuffer JavaDoc();
5500        boolean isStr = (val instanceof String JavaDoc);
5501
5502        if (isStr && ((String JavaDoc) val).length() == 0) {
5503            return sb.append(" AND ").append(id).append(
5504                " IS NULL").toString();
5505        }
5506
5507        String JavaDoc v = isStr ? Column.createSQLString((String JavaDoc) val)
5508                         : String.valueOf(val);
5509
5510        sb.append(" AND ").append(id).append(' ');
5511
5512        // add the escape to like if required
5513
if (isStr && "LIKE".equalsIgnoreCase(op)) {
5514            if (v.indexOf('_') < 0 && v.indexOf('%') < 0) {
5515
5516                // then we can optimize.
5517
sb.append("=").append(' ').append(v);
5518            } else {
5519                sb.append("LIKE").append(' ').append(v);
5520
5521                if ((v.indexOf("\\_") >= 0) || (v.indexOf("\\%") >= 0)) {
5522
5523                    // then client has requested at least one escape.
5524
sb.append(" ESCAPE '\\'");
5525                }
5526            }
5527        } else {
5528            sb.append(op).append(' ').append(v);
5529        }
5530
5531        return sb.toString();
5532    }
5533
5534    /**
5535     * The main SQL statement executor. All SQL destined for execution
5536     * ultimately goes through this method. <p>
5537     *
5538     * The sqlStatement field for the result is set autoClose to comply with
5539     * ResultSet.getStatement() semantics for result sets that are not from
5540     * a user supplied Statement object. (fredt) <p>
5541     *
5542     * @param sql SQL statement to execute
5543     * @return the result of issuing the statement
5544     * @throws SQLException is a database error occurs
5545     */

5546    private ResultSet JavaDoc execute(String JavaDoc sql) throws SQLException JavaDoc {
5547
5548        // NOTE:
5549
// Need to create a jdbcStatement here so jdbcResultSet can return
5550
// its Statement object on call to getStatement().
5551
// The native jdbcConnection.execute() method does not
5552
// automatically assign a Statement object for the ResultSet, but
5553
// jdbcStatement does. That is, without this, there is no way for the
5554
// jdbcResultSet to find its way back to its Connection (or Statement)
5555
// Also, cannot use single, shared jdbcStatement object, as each
5556
// fetchResult() closes any old jdbcResultSet before fetching the
5557
// next, causing the jdbcResultSet's Result object to be nullified
5558
final int scroll = jdbcResultSet.TYPE_SCROLL_INSENSITIVE;
5559        final int concur = jdbcResultSet.CONCUR_READ_ONLY;
5560        ResultSet JavaDoc r = connection.createStatement(scroll,
5561            concur).executeQuery(sql);
5562
5563        ((jdbcResultSet) r).autoClose = true;
5564
5565        return r;
5566    }
5567
5568    /**
5569     * An SQL statement executor that knows how to create a "SELECT
5570     * * FROM" statement, given a table name and a <em>where</em> clause.<p>
5571     *
5572     * If the <em>where</em> clause is null, it is ommited. <p>
5573     *
5574     * It is assumed that the table name is non-null, since this is a private
5575     * method. No check is performed. <p>
5576     *
5577     * @return the result of executing "SELECT * FROM " + table " " + where
5578     * @param table the name of a table to "select * from"
5579     * @param where the where condition for the select
5580     * @throws SQLException if database error occurs
5581     */

5582    private ResultSet JavaDoc executeSelect(String JavaDoc table,
5583                                    String JavaDoc where) throws SQLException JavaDoc {
5584
5585        String JavaDoc select = selstar + table;
5586
5587        if (where != null) {
5588            select += " WHERE " + where;
5589        }
5590
5591        return execute(select);
5592    }
5593
5594    /**
5595     * Retrieves "SELECT * FROM &lt;table&gt; WHERE 1=1" in string
5596     * buffer form. <p>
5597     *
5598     * This is a convenience method provided because, for most
5599     * <code>DatabaseMetaData</code> queries, this is the most suitable
5600     * thing upon which to start building. <p>
5601     *
5602     * @return an StringBuffer whose content is:
5603     * "SELECT * FROM &lt;table&gt; WHERE 1=1"
5604     * @param t the name of the table
5605     */

5606    private StringBuffer JavaDoc toQueryPrefix(String JavaDoc t) {
5607
5608        StringBuffer JavaDoc sb = new StringBuffer JavaDoc(255);
5609
5610        return sb.append(selstar).append(t).append(whereTrue);
5611    }
5612
5613    /**
5614     * Retrieves whether the JDBC <code>DatabaseMetaData</code> contract
5615     * specifies that the argument <code>s</code>code> is filter parameter
5616     * value that requires a corresponding IS NULL predicate. <p>
5617     *
5618     * @param s the filter parameter to test
5619     * @return true if the argument, s, is filter paramter value that
5620     * requires a corresponding IS NULL predicate
5621     */

5622    private static boolean wantsIsNull(String JavaDoc s) {
5623        return (s != null && s.length() == 0);
5624    }
5625
5626    /**
5627     * For compatibility, when the connection property "default_schame=true"
5628     * is present, any DatabaseMetaData call with an empty string as the
5629     * schema parameter will use the default schema (noramlly "PUBLIC").
5630     */

5631    private String JavaDoc translateSchema(String JavaDoc schemaName) throws SQLException JavaDoc {
5632
5633        if (useSchemaDefault && schemaName != null
5634                && schemaName.length() == 0) {
5635            ResultSet JavaDoc rs = executeSelect("SYSTEM_SCHEMAS", "IS_DEFAULT=TRUE");
5636
5637            if (rs.next()) {
5638                return rs.getString(1);
5639            }
5640
5641            return schemaName;
5642        }
5643
5644        return schemaName;
5645    }
5646}
5647
Popular Tags