View Javadoc
1   /*
2    * Copyright (c) 1996, 2013, Oracle and/or its affiliates. All rights reserved.
3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4    *
5    * This code is free software; you can redistribute it and/or modify it
6    * under the terms of the GNU General Public License version 2 only, as
7    * published by the Free Software Foundation.  Oracle designates this
8    * particular file as subject to the "Classpath" exception as provided
9    * by Oracle in the LICENSE file that accompanied this code.
10   *
11   * This code is distributed in the hope that it will be useful, but WITHOUT
12   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13   * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14   * version 2 for more details (a copy is included in the LICENSE file that
15   * accompanied this code).
16   *
17   * You should have received a copy of the GNU General Public License version
18   * 2 along with this work; if not, write to the Free Software Foundation,
19   * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20   *
21   * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22   * or visit www.oracle.com if you need additional information or have any
23   * questions.
24   */
25  
26  
27  package java.sql;
28  
29  /**
30   * Comprehensive information about the database as a whole.
31   * <P>
32   * This interface is implemented by driver vendors to let users know the capabilities
33   * of a Database Management System (DBMS) in combination with
34   * the driver based on JDBC&trade; technology
35   * ("JDBC driver") that is used with it.  Different relational DBMSs often support
36   * different features, implement features in different ways, and use different
37   * data types.  In addition, a driver may implement a feature on top of what the
38   * DBMS offers.  Information returned by methods in this interface applies
39   * to the capabilities of a particular driver and a particular DBMS working
40   * together. Note that as used in this documentation, the term "database" is
41   * used generically to refer to both the driver and DBMS.
42   * <P>
43   * A user for this interface is commonly a tool that needs to discover how to
44   * deal with the underlying DBMS.  This is especially true for applications
45   * that are intended to be used with more than one DBMS. For example, a tool might use the method
46   * <code>getTypeInfo</code> to find out what data types can be used in a
47   * <code>CREATE TABLE</code> statement.  Or a user might call the method
48   * <code>supportsCorrelatedSubqueries</code> to see if it is possible to use
49   * a correlated subquery or <code>supportsBatchUpdates</code> to see if it is
50   * possible to use batch updates.
51   * <P>
52   * Some <code>DatabaseMetaData</code> methods return lists of information
53   * in the form of <code>ResultSet</code> objects.
54   * Regular <code>ResultSet</code> methods, such as
55   * <code>getString</code> and <code>getInt</code>, can be used
56   * to retrieve the data from these <code>ResultSet</code> objects.  If
57   * a given form of metadata is not available, an empty <code>ResultSet</code>
58   * will be returned. Additional columns beyond the columns defined to be
59   * returned by the <code>ResultSet</code> object for a given method
60   * can be defined by the JDBC driver vendor and must be accessed
61   * by their <B>column label</B>.
62   * <P>
63   * Some <code>DatabaseMetaData</code> methods take arguments that are
64   * String patterns.  These arguments all have names such as fooPattern.
65   * Within a pattern String, "%" means match any substring of 0 or more
66   * characters, and "_" means match any one character. Only metadata
67   * entries matching the search pattern are returned. If a search pattern
68   * argument is set to <code>null</code>, that argument's criterion will
69   * be dropped from the search.
70   *
71   */
72  public interface DatabaseMetaData extends Wrapper {
73  
74      //----------------------------------------------------------------------
75      // First, a variety of minor information about the target database.
76  
77      /**
78       * Retrieves whether the current user can call all the procedures
79       * returned by the method <code>getProcedures</code>.
80       *
81       * @return <code>true</code> if so; <code>false</code> otherwise
82       * @exception SQLException if a database access error occurs
83       */
84      boolean allProceduresAreCallable() throws SQLException;
85  
86      /**
87       * Retrieves whether the current user can use all the tables returned
88       * by the method <code>getTables</code> in a <code>SELECT</code>
89       * statement.
90       *
91       * @return <code>true</code> if so; <code>false</code> otherwise
92       * @exception SQLException if a database access error occurs
93       */
94      boolean allTablesAreSelectable() throws SQLException;
95  
96      /**
97       * Retrieves the URL for this DBMS.
98       *
99       * @return the URL for this DBMS or <code>null</code> if it cannot be
100      *          generated
101      * @exception SQLException if a database access error occurs
102      */
103     String getURL() throws SQLException;
104 
105     /**
106      * Retrieves the user name as known to this database.
107      *
108      * @return the database user name
109      * @exception SQLException if a database access error occurs
110      */
111     String getUserName() throws SQLException;
112 
113     /**
114      * Retrieves whether this database is in read-only mode.
115      *
116      * @return <code>true</code> if so; <code>false</code> otherwise
117      * @exception SQLException if a database access error occurs
118      */
119     boolean isReadOnly() throws SQLException;
120 
121     /**
122      * Retrieves whether <code>NULL</code> values are sorted high.
123      * Sorted high means that <code>NULL</code> values
124      * sort higher than any other value in a domain.  In an ascending order,
125      * if this method returns <code>true</code>,  <code>NULL</code> values
126      * will appear at the end. By contrast, the method
127      * <code>nullsAreSortedAtEnd</code> indicates whether <code>NULL</code> values
128      * are sorted at the end regardless of sort order.
129      *
130      * @return <code>true</code> if so; <code>false</code> otherwise
131      * @exception SQLException if a database access error occurs
132      */
133     boolean nullsAreSortedHigh() throws SQLException;
134 
135     /**
136      * Retrieves whether <code>NULL</code> values are sorted low.
137      * Sorted low means that <code>NULL</code> values
138      * sort lower than any other value in a domain.  In an ascending order,
139      * if this method returns <code>true</code>,  <code>NULL</code> values
140      * will appear at the beginning. By contrast, the method
141      * <code>nullsAreSortedAtStart</code> indicates whether <code>NULL</code> values
142      * are sorted at the beginning regardless of sort order.
143      *
144      * @return <code>true</code> if so; <code>false</code> otherwise
145      * @exception SQLException if a database access error occurs
146      */
147     boolean nullsAreSortedLow() throws SQLException;
148 
149     /**
150      * Retrieves whether <code>NULL</code> values are sorted at the start regardless
151      * of sort order.
152      *
153      * @return <code>true</code> if so; <code>false</code> otherwise
154      * @exception SQLException if a database access error occurs
155      */
156     boolean nullsAreSortedAtStart() throws SQLException;
157 
158     /**
159      * Retrieves whether <code>NULL</code> values are sorted at the end regardless of
160      * sort order.
161      *
162      * @return <code>true</code> if so; <code>false</code> otherwise
163      * @exception SQLException if a database access error occurs
164      */
165     boolean nullsAreSortedAtEnd() throws SQLException;
166 
167     /**
168      * Retrieves the name of this database product.
169      *
170      * @return database product name
171      * @exception SQLException if a database access error occurs
172      */
173     String getDatabaseProductName() throws SQLException;
174 
175     /**
176      * Retrieves the version number of this database product.
177      *
178      * @return database version number
179      * @exception SQLException if a database access error occurs
180      */
181     String getDatabaseProductVersion() throws SQLException;
182 
183     /**
184      * Retrieves the name of this JDBC driver.
185      *
186      * @return JDBC driver name
187      * @exception SQLException if a database access error occurs
188      */
189     String getDriverName() throws SQLException;
190 
191     /**
192      * Retrieves the version number of this JDBC driver as a <code>String</code>.
193      *
194      * @return JDBC driver version
195      * @exception SQLException if a database access error occurs
196      */
197     String getDriverVersion() throws SQLException;
198 
199     /**
200      * Retrieves this JDBC driver's major version number.
201      *
202      * @return JDBC driver major version
203      */
204     int getDriverMajorVersion();
205 
206     /**
207      * Retrieves this JDBC driver's minor version number.
208      *
209      * @return JDBC driver minor version number
210      */
211     int getDriverMinorVersion();
212 
213     /**
214      * Retrieves whether this database stores tables in a local file.
215      *
216      * @return <code>true</code> if so; <code>false</code> otherwise
217      * @exception SQLException if a database access error occurs
218      */
219     boolean usesLocalFiles() throws SQLException;
220 
221     /**
222      * Retrieves whether this database uses a file for each table.
223      *
224      * @return <code>true</code> if this database uses a local file for each table;
225      *         <code>false</code> otherwise
226      * @exception SQLException if a database access error occurs
227      */
228     boolean usesLocalFilePerTable() throws SQLException;
229 
230     /**
231      * Retrieves whether this database treats mixed case unquoted SQL identifiers as
232      * case sensitive and as a result stores them in mixed case.
233      *
234      * @return <code>true</code> if so; <code>false</code> otherwise
235      * @exception SQLException if a database access error occurs
236      */
237     boolean supportsMixedCaseIdentifiers() throws SQLException;
238 
239     /**
240      * Retrieves whether this database treats mixed case unquoted SQL identifiers as
241      * case insensitive and stores them in upper case.
242      *
243      * @return <code>true</code> if so; <code>false</code> otherwise
244      * @exception SQLException if a database access error occurs
245      */
246     boolean storesUpperCaseIdentifiers() throws SQLException;
247 
248     /**
249      * Retrieves whether this database treats mixed case unquoted SQL identifiers as
250      * case insensitive and stores them in lower case.
251      *
252      * @return <code>true</code> if so; <code>false</code> otherwise
253      * @exception SQLException if a database access error occurs
254      */
255     boolean storesLowerCaseIdentifiers() throws SQLException;
256 
257     /**
258      * Retrieves whether this database treats mixed case unquoted SQL identifiers as
259      * case insensitive and stores them in mixed case.
260      *
261      * @return <code>true</code> if so; <code>false</code> otherwise
262      * @exception SQLException if a database access error occurs
263      */
264     boolean storesMixedCaseIdentifiers() throws SQLException;
265 
266     /**
267      * Retrieves whether this database treats mixed case quoted SQL identifiers as
268      * case sensitive and as a result stores them in mixed case.
269      *
270      * @return <code>true</code> if so; <code>false</code> otherwise
271      * @exception SQLException if a database access error occurs
272      */
273     boolean supportsMixedCaseQuotedIdentifiers() throws SQLException;
274 
275     /**
276      * Retrieves whether this database treats mixed case quoted SQL identifiers as
277      * case insensitive and stores them in upper case.
278      *
279      * @return <code>true</code> if so; <code>false</code> otherwise
280      * @exception SQLException if a database access error occurs
281      */
282     boolean storesUpperCaseQuotedIdentifiers() throws SQLException;
283 
284     /**
285      * Retrieves whether this database treats mixed case quoted SQL identifiers as
286      * case insensitive and stores them in lower case.
287      *
288      * @return <code>true</code> if so; <code>false</code> otherwise
289      * @exception SQLException if a database access error occurs
290      */
291     boolean storesLowerCaseQuotedIdentifiers() throws SQLException;
292 
293     /**
294      * Retrieves whether this database treats mixed case quoted SQL identifiers as
295      * case insensitive and stores them in mixed case.
296      *
297      * @return <code>true</code> if so; <code>false</code> otherwise
298      * @exception SQLException if a database access error occurs
299      */
300     boolean storesMixedCaseQuotedIdentifiers() throws SQLException;
301 
302     /**
303      * Retrieves the string used to quote SQL identifiers.
304      * This method returns a space " " if identifier quoting is not supported.
305      *
306      * @return the quoting string or a space if quoting is not supported
307      * @exception SQLException if a database access error occurs
308      */
309     String getIdentifierQuoteString() throws SQLException;
310 
311     /**
312      * Retrieves a comma-separated list of all of this database's SQL keywords
313      * that are NOT also SQL:2003 keywords.
314      *
315      * @return the list of this database's keywords that are not also
316      *         SQL:2003 keywords
317      * @exception SQLException if a database access error occurs
318      */
319     String getSQLKeywords() throws SQLException;
320 
321     /**
322      * Retrieves a comma-separated list of math functions available with
323      * this database.  These are the Open /Open CLI math function names used in
324      * the JDBC function escape clause.
325      *
326      * @return the list of math functions supported by this database
327      * @exception SQLException if a database access error occurs
328      */
329     String getNumericFunctions() throws SQLException;
330 
331     /**
332      * Retrieves a comma-separated list of string functions available with
333      * this database.  These are the  Open Group CLI string function names used
334      * in the JDBC function escape clause.
335      *
336      * @return the list of string functions supported by this database
337      * @exception SQLException if a database access error occurs
338      */
339     String getStringFunctions() throws SQLException;
340 
341     /**
342      * Retrieves a comma-separated list of system functions available with
343      * this database.  These are the  Open Group CLI system function names used
344      * in the JDBC function escape clause.
345      *
346      * @return a list of system functions supported by this database
347      * @exception SQLException if a database access error occurs
348      */
349     String getSystemFunctions() throws SQLException;
350 
351     /**
352      * Retrieves a comma-separated list of the time and date functions available
353      * with this database.
354      *
355      * @return the list of time and date functions supported by this database
356      * @exception SQLException if a database access error occurs
357      */
358     String getTimeDateFunctions() throws SQLException;
359 
360     /**
361      * Retrieves the string that can be used to escape wildcard characters.
362      * This is the string that can be used to escape '_' or '%' in
363      * the catalog search parameters that are a pattern (and therefore use one
364      * of the wildcard characters).
365      *
366      * <P>The '_' character represents any single character;
367      * the '%' character represents any sequence of zero or
368      * more characters.
369      *
370      * @return the string used to escape wildcard characters
371      * @exception SQLException if a database access error occurs
372      */
373     String getSearchStringEscape() throws SQLException;
374 
375     /**
376      * Retrieves all the "extra" characters that can be used in unquoted
377      * identifier names (those beyond a-z, A-Z, 0-9 and _).
378      *
379      * @return the string containing the extra characters
380      * @exception SQLException if a database access error occurs
381      */
382     String getExtraNameCharacters() throws SQLException;
383 
384     //--------------------------------------------------------------------
385     // Functions describing which features are supported.
386 
387     /**
388      * Retrieves whether this database supports <code>ALTER TABLE</code>
389      * with add column.
390      *
391      * @return <code>true</code> if so; <code>false</code> otherwise
392      * @exception SQLException if a database access error occurs
393      */
394     boolean supportsAlterTableWithAddColumn() throws SQLException;
395 
396     /**
397      * Retrieves whether this database supports <code>ALTER TABLE</code>
398      * with drop column.
399      *
400      * @return <code>true</code> if so; <code>false</code> otherwise
401      * @exception SQLException if a database access error occurs
402      */
403     boolean supportsAlterTableWithDropColumn() throws SQLException;
404 
405     /**
406      * Retrieves whether this database supports column aliasing.
407      *
408      * <P>If so, the SQL AS clause can be used to provide names for
409      * computed columns or to provide alias names for columns as
410      * required.
411      *
412      * @return <code>true</code> if so; <code>false</code> otherwise
413      * @exception SQLException if a database access error occurs
414      */
415     boolean supportsColumnAliasing() throws SQLException;
416 
417     /**
418      * Retrieves whether this database supports concatenations between
419      * <code>NULL</code> and non-<code>NULL</code> values being
420      * <code>NULL</code>.
421      *
422      * @return <code>true</code> if so; <code>false</code> otherwise
423      * @exception SQLException if a database access error occurs
424      */
425     boolean nullPlusNonNullIsNull() throws SQLException;
426 
427     /**
428      * Retrieves whether this database supports the JDBC scalar function
429      * <code>CONVERT</code> for the conversion of one JDBC type to another.
430      * The JDBC types are the generic SQL data types defined
431      * in <code>java.sql.Types</code>.
432      *
433      * @return <code>true</code> if so; <code>false</code> otherwise
434      * @exception SQLException if a database access error occurs
435      */
436     boolean supportsConvert() throws SQLException;
437 
438     /**
439      * Retrieves whether this database supports the JDBC scalar function
440      * <code>CONVERT</code> for conversions between the JDBC types <i>fromType</i>
441      * and <i>toType</i>.  The JDBC types are the generic SQL data types defined
442      * in <code>java.sql.Types</code>.
443      *
444      * @param fromType the type to convert from; one of the type codes from
445      *        the class <code>java.sql.Types</code>
446      * @param toType the type to convert to; one of the type codes from
447      *        the class <code>java.sql.Types</code>
448      * @return <code>true</code> if so; <code>false</code> otherwise
449      * @exception SQLException if a database access error occurs
450      * @see Types
451      */
452     boolean supportsConvert(int fromType, int toType) throws SQLException;
453 
454     /**
455      * Retrieves whether this database supports table correlation names.
456      *
457      * @return <code>true</code> if so; <code>false</code> otherwise
458      * @exception SQLException if a database access error occurs
459      */
460     boolean supportsTableCorrelationNames() throws SQLException;
461 
462     /**
463      * Retrieves whether, when table correlation names are supported, they
464      * are restricted to being different from the names of the tables.
465      *
466      * @return <code>true</code> if so; <code>false</code> otherwise
467      * @exception SQLException if a database access error occurs
468      */
469     boolean supportsDifferentTableCorrelationNames() throws SQLException;
470 
471     /**
472      * Retrieves whether this database supports expressions in
473      * <code>ORDER BY</code> lists.
474      *
475      * @return <code>true</code> if so; <code>false</code> otherwise
476      * @exception SQLException if a database access error occurs
477      */
478     boolean supportsExpressionsInOrderBy() throws SQLException;
479 
480     /**
481      * Retrieves whether this database supports using a column that is
482      * not in the <code>SELECT</code> statement in an
483      * <code>ORDER BY</code> clause.
484      *
485      * @return <code>true</code> if so; <code>false</code> otherwise
486      * @exception SQLException if a database access error occurs
487      */
488     boolean supportsOrderByUnrelated() throws SQLException;
489 
490     /**
491      * Retrieves whether this database supports some form of
492      * <code>GROUP BY</code> clause.
493      *
494      * @return <code>true</code> if so; <code>false</code> otherwise
495      * @exception SQLException if a database access error occurs
496      */
497     boolean supportsGroupBy() throws SQLException;
498 
499     /**
500      * Retrieves whether this database supports using a column that is
501      * not in the <code>SELECT</code> statement in a
502      * <code>GROUP BY</code> clause.
503      *
504      * @return <code>true</code> if so; <code>false</code> otherwise
505      * @exception SQLException if a database access error occurs
506      */
507     boolean supportsGroupByUnrelated() throws SQLException;
508 
509     /**
510      * Retrieves whether this database supports using columns not included in
511      * the <code>SELECT</code> statement in a <code>GROUP BY</code> clause
512      * provided that all of the columns in the <code>SELECT</code> statement
513      * are included in the <code>GROUP BY</code> clause.
514      *
515      * @return <code>true</code> if so; <code>false</code> otherwise
516      * @exception SQLException if a database access error occurs
517      */
518     boolean supportsGroupByBeyondSelect() throws SQLException;
519 
520     /**
521      * Retrieves whether this database supports specifying a
522      * <code>LIKE</code> escape clause.
523      *
524      * @return <code>true</code> if so; <code>false</code> otherwise
525      * @exception SQLException if a database access error occurs
526      */
527     boolean supportsLikeEscapeClause() throws SQLException;
528 
529     /**
530      * Retrieves whether this database supports getting multiple
531      * <code>ResultSet</code> objects from a single call to the
532      * method <code>execute</code>.
533      *
534      * @return <code>true</code> if so; <code>false</code> otherwise
535      * @exception SQLException if a database access error occurs
536      */
537     boolean supportsMultipleResultSets() throws SQLException;
538 
539     /**
540      * Retrieves whether this database allows having multiple
541      * transactions open at once (on different connections).
542      *
543      * @return <code>true</code> if so; <code>false</code> otherwise
544      * @exception SQLException if a database access error occurs
545      */
546     boolean supportsMultipleTransactions() throws SQLException;
547 
548     /**
549      * Retrieves whether columns in this database may be defined as non-nullable.
550      *
551      * @return <code>true</code> if so; <code>false</code> otherwise
552      * @exception SQLException if a database access error occurs
553      */
554     boolean supportsNonNullableColumns() throws SQLException;
555 
556     /**
557      * Retrieves whether this database supports the ODBC Minimum SQL grammar.
558      *
559      * @return <code>true</code> if so; <code>false</code> otherwise
560      * @exception SQLException if a database access error occurs
561      */
562     boolean supportsMinimumSQLGrammar() throws SQLException;
563 
564     /**
565      * Retrieves whether this database supports the ODBC Core SQL grammar.
566      *
567      * @return <code>true</code> if so; <code>false</code> otherwise
568      * @exception SQLException if a database access error occurs
569      */
570     boolean supportsCoreSQLGrammar() throws SQLException;
571 
572     /**
573      * Retrieves whether this database supports the ODBC Extended SQL grammar.
574      *
575      * @return <code>true</code> if so; <code>false</code> otherwise
576      * @exception SQLException if a database access error occurs
577      */
578     boolean supportsExtendedSQLGrammar() throws SQLException;
579 
580     /**
581      * Retrieves whether this database supports the ANSI92 entry level SQL
582      * grammar.
583      *
584      * @return <code>true</code> if so; <code>false</code> otherwise
585      * @exception SQLException if a database access error occurs
586      */
587     boolean supportsANSI92EntryLevelSQL() throws SQLException;
588 
589     /**
590      * Retrieves whether this database supports the ANSI92 intermediate SQL grammar supported.
591      *
592      * @return <code>true</code> if so; <code>false</code> otherwise
593      * @exception SQLException if a database access error occurs
594      */
595     boolean supportsANSI92IntermediateSQL() throws SQLException;
596 
597     /**
598      * Retrieves whether this database supports the ANSI92 full SQL grammar supported.
599      *
600      * @return <code>true</code> if so; <code>false</code> otherwise
601      * @exception SQLException if a database access error occurs
602      */
603     boolean supportsANSI92FullSQL() throws SQLException;
604 
605     /**
606      * Retrieves whether this database supports the SQL Integrity
607      * Enhancement Facility.
608      *
609      * @return <code>true</code> if so; <code>false</code> otherwise
610      * @exception SQLException if a database access error occurs
611      */
612     boolean supportsIntegrityEnhancementFacility() throws SQLException;
613 
614     /**
615      * Retrieves whether this database supports some form of outer join.
616      *
617      * @return <code>true</code> if so; <code>false</code> otherwise
618      * @exception SQLException if a database access error occurs
619      */
620     boolean supportsOuterJoins() throws SQLException;
621 
622     /**
623      * Retrieves whether this database supports full nested outer joins.
624      *
625      * @return <code>true</code> if so; <code>false</code> otherwise
626      * @exception SQLException if a database access error occurs
627      */
628     boolean supportsFullOuterJoins() throws SQLException;
629 
630     /**
631      * Retrieves whether this database provides limited support for outer
632      * joins.  (This will be <code>true</code> if the method
633      * <code>supportsFullOuterJoins</code> returns <code>true</code>).
634      *
635      * @return <code>true</code> if so; <code>false</code> otherwise
636      * @exception SQLException if a database access error occurs
637      */
638     boolean supportsLimitedOuterJoins() throws SQLException;
639 
640     /**
641      * Retrieves the database vendor's preferred term for "schema".
642      *
643      * @return the vendor term for "schema"
644      * @exception SQLException if a database access error occurs
645      */
646     String getSchemaTerm() throws SQLException;
647 
648     /**
649      * Retrieves the database vendor's preferred term for "procedure".
650      *
651      * @return the vendor term for "procedure"
652      * @exception SQLException if a database access error occurs
653      */
654     String getProcedureTerm() throws SQLException;
655 
656     /**
657      * Retrieves the database vendor's preferred term for "catalog".
658      *
659      * @return the vendor term for "catalog"
660      * @exception SQLException if a database access error occurs
661      */
662     String getCatalogTerm() throws SQLException;
663 
664     /**
665      * Retrieves whether a catalog appears at the start of a fully qualified
666      * table name.  If not, the catalog appears at the end.
667      *
668      * @return <code>true</code> if the catalog name appears at the beginning
669      *         of a fully qualified table name; <code>false</code> otherwise
670      * @exception SQLException if a database access error occurs
671      */
672     boolean isCatalogAtStart() throws SQLException;
673 
674     /**
675      * Retrieves the <code>String</code> that this database uses as the
676      * separator between a catalog and table name.
677      *
678      * @return the separator string
679      * @exception SQLException if a database access error occurs
680      */
681     String getCatalogSeparator() throws SQLException;
682 
683     /**
684      * Retrieves whether a schema name can be used in a data manipulation statement.
685      *
686      * @return <code>true</code> if so; <code>false</code> otherwise
687      * @exception SQLException if a database access error occurs
688      */
689     boolean supportsSchemasInDataManipulation() throws SQLException;
690 
691     /**
692      * Retrieves whether a schema name can be used in a procedure call statement.
693      *
694      * @return <code>true</code> if so; <code>false</code> otherwise
695      * @exception SQLException if a database access error occurs
696      */
697     boolean supportsSchemasInProcedureCalls() throws SQLException;
698 
699     /**
700      * Retrieves whether a schema name can be used in a table definition statement.
701      *
702      * @return <code>true</code> if so; <code>false</code> otherwise
703      * @exception SQLException if a database access error occurs
704      */
705     boolean supportsSchemasInTableDefinitions() throws SQLException;
706 
707     /**
708      * Retrieves whether a schema name can be used in an index definition statement.
709      *
710      * @return <code>true</code> if so; <code>false</code> otherwise
711      * @exception SQLException if a database access error occurs
712      */
713     boolean supportsSchemasInIndexDefinitions() throws SQLException;
714 
715     /**
716      * Retrieves whether a schema name can be used in a privilege definition statement.
717      *
718      * @return <code>true</code> if so; <code>false</code> otherwise
719      * @exception SQLException if a database access error occurs
720      */
721     boolean supportsSchemasInPrivilegeDefinitions() throws SQLException;
722 
723     /**
724      * Retrieves whether a catalog name can be used in a data manipulation statement.
725      *
726      * @return <code>true</code> if so; <code>false</code> otherwise
727      * @exception SQLException if a database access error occurs
728      */
729     boolean supportsCatalogsInDataManipulation() throws SQLException;
730 
731     /**
732      * Retrieves whether a catalog name can be used in a procedure call statement.
733      *
734      * @return <code>true</code> if so; <code>false</code> otherwise
735      * @exception SQLException if a database access error occurs
736      */
737     boolean supportsCatalogsInProcedureCalls() throws SQLException;
738 
739     /**
740      * Retrieves whether a catalog name can be used in a table definition statement.
741      *
742      * @return <code>true</code> if so; <code>false</code> otherwise
743      * @exception SQLException if a database access error occurs
744      */
745     boolean supportsCatalogsInTableDefinitions() throws SQLException;
746 
747     /**
748      * Retrieves whether a catalog name can be used in an index definition statement.
749      *
750      * @return <code>true</code> if so; <code>false</code> otherwise
751      * @exception SQLException if a database access error occurs
752      */
753     boolean supportsCatalogsInIndexDefinitions() throws SQLException;
754 
755     /**
756      * Retrieves whether a catalog name can be used in a privilege definition statement.
757      *
758      * @return <code>true</code> if so; <code>false</code> otherwise
759      * @exception SQLException if a database access error occurs
760      */
761     boolean supportsCatalogsInPrivilegeDefinitions() throws SQLException;
762 
763 
764     /**
765      * Retrieves whether this database supports positioned <code>DELETE</code>
766      * statements.
767      *
768      * @return <code>true</code> if so; <code>false</code> otherwise
769      * @exception SQLException if a database access error occurs
770      */
771     boolean supportsPositionedDelete() throws SQLException;
772 
773     /**
774      * Retrieves whether this database supports positioned <code>UPDATE</code>
775      * statements.
776      *
777      * @return <code>true</code> if so; <code>false</code> otherwise
778      * @exception SQLException if a database access error occurs
779      */
780     boolean supportsPositionedUpdate() throws SQLException;
781 
782     /**
783      * Retrieves whether this database supports <code>SELECT FOR UPDATE</code>
784      * statements.
785      *
786      * @return <code>true</code> if so; <code>false</code> otherwise
787      * @exception SQLException if a database access error occurs
788      */
789     boolean supportsSelectForUpdate() throws SQLException;
790 
791     /**
792      * Retrieves whether this database supports stored procedure calls
793      * that use the stored procedure escape syntax.
794      *
795      * @return <code>true</code> if so; <code>false</code> otherwise
796      * @exception SQLException if a database access error occurs
797      */
798     boolean supportsStoredProcedures() throws SQLException;
799 
800     /**
801      * Retrieves whether this database supports subqueries in comparison
802      * expressions.
803      *
804      * @return <code>true</code> if so; <code>false</code> otherwise
805      * @exception SQLException if a database access error occurs
806      */
807     boolean supportsSubqueriesInComparisons() throws SQLException;
808 
809     /**
810      * Retrieves whether this database supports subqueries in
811      * <code>EXISTS</code> expressions.
812      *
813      * @return <code>true</code> if so; <code>false</code> otherwise
814      * @exception SQLException if a database access error occurs
815      */
816     boolean supportsSubqueriesInExists() throws SQLException;
817 
818     /**
819      * Retrieves whether this database supports subqueries in
820      * <code>IN</code> expressions.
821      *
822      * @return <code>true</code> if so; <code>false</code> otherwise
823      * @exception SQLException if a database access error occurs
824      */
825     boolean supportsSubqueriesInIns() throws SQLException;
826 
827     /**
828      * Retrieves whether this database supports subqueries in quantified
829      * expressions.
830      *
831      * @return <code>true</code> if so; <code>false</code> otherwise
832      * @exception SQLException if a database access error occurs
833      */
834     boolean supportsSubqueriesInQuantifieds() throws SQLException;
835 
836     /**
837      * Retrieves whether this database supports correlated subqueries.
838      *
839      * @return <code>true</code> if so; <code>false</code> otherwise
840      * @exception SQLException if a database access error occurs
841      */
842     boolean supportsCorrelatedSubqueries() throws SQLException;
843 
844     /**
845      * Retrieves whether this database supports SQL <code>UNION</code>.
846      *
847      * @return <code>true</code> if so; <code>false</code> otherwise
848      * @exception SQLException if a database access error occurs
849      */
850     boolean supportsUnion() throws SQLException;
851 
852     /**
853      * Retrieves whether this database supports SQL <code>UNION ALL</code>.
854      *
855      * @return <code>true</code> if so; <code>false</code> otherwise
856      * @exception SQLException if a database access error occurs
857      */
858     boolean supportsUnionAll() throws SQLException;
859 
860     /**
861      * Retrieves whether this database supports keeping cursors open
862      * across commits.
863      *
864      * @return <code>true</code> if cursors always remain open;
865      *       <code>false</code> if they might not remain open
866      * @exception SQLException if a database access error occurs
867      */
868     boolean supportsOpenCursorsAcrossCommit() throws SQLException;
869 
870     /**
871      * Retrieves whether this database supports keeping cursors open
872      * across rollbacks.
873      *
874      * @return <code>true</code> if cursors always remain open;
875      *       <code>false</code> if they might not remain open
876      * @exception SQLException if a database access error occurs
877      */
878     boolean supportsOpenCursorsAcrossRollback() throws SQLException;
879 
880     /**
881      * Retrieves whether this database supports keeping statements open
882      * across commits.
883      *
884      * @return <code>true</code> if statements always remain open;
885      *       <code>false</code> if they might not remain open
886      * @exception SQLException if a database access error occurs
887      */
888     boolean supportsOpenStatementsAcrossCommit() throws SQLException;
889 
890     /**
891      * Retrieves whether this database supports keeping statements open
892      * across rollbacks.
893      *
894      * @return <code>true</code> if statements always remain open;
895      *       <code>false</code> if they might not remain open
896      * @exception SQLException if a database access error occurs
897      */
898     boolean supportsOpenStatementsAcrossRollback() throws SQLException;
899 
900 
901 
902     //----------------------------------------------------------------------
903     // The following group of methods exposes various limitations
904     // based on the target database with the current driver.
905     // Unless otherwise specified, a result of zero means there is no
906     // limit, or the limit is not known.
907 
908     /**
909      * Retrieves the maximum number of hex characters this database allows in an
910      * inline binary literal.
911      *
912      * @return max the maximum length (in hex characters) for a binary literal;
913      *      a result of zero means that there is no limit or the limit
914      *      is not known
915      * @exception SQLException if a database access error occurs
916      */
917     int getMaxBinaryLiteralLength() throws SQLException;
918 
919     /**
920      * Retrieves the maximum number of characters this database allows
921      * for a character literal.
922      *
923      * @return the maximum number of characters allowed for a character literal;
924      *      a result of zero means that there is no limit or the limit is
925      *      not known
926      * @exception SQLException if a database access error occurs
927      */
928     int getMaxCharLiteralLength() throws SQLException;
929 
930     /**
931      * Retrieves the maximum number of characters this database allows
932      * for a column name.
933      *
934      * @return the maximum number of characters allowed for a column name;
935      *      a result of zero means that there is no limit or the limit
936      *      is not known
937      * @exception SQLException if a database access error occurs
938      */
939     int getMaxColumnNameLength() throws SQLException;
940 
941     /**
942      * Retrieves the maximum number of columns this database allows in a
943      * <code>GROUP BY</code> clause.
944      *
945      * @return the maximum number of columns allowed;
946      *      a result of zero means that there is no limit or the limit
947      *      is not known
948      * @exception SQLException if a database access error occurs
949      */
950     int getMaxColumnsInGroupBy() throws SQLException;
951 
952     /**
953      * Retrieves the maximum number of columns this database allows in an index.
954      *
955      * @return the maximum number of columns allowed;
956      *      a result of zero means that there is no limit or the limit
957      *      is not known
958      * @exception SQLException if a database access error occurs
959      */
960     int getMaxColumnsInIndex() throws SQLException;
961 
962     /**
963      * Retrieves the maximum number of columns this database allows in an
964      * <code>ORDER BY</code> clause.
965      *
966      * @return the maximum number of columns allowed;
967      *      a result of zero means that there is no limit or the limit
968      *      is not known
969      * @exception SQLException if a database access error occurs
970      */
971     int getMaxColumnsInOrderBy() throws SQLException;
972 
973     /**
974      * Retrieves the maximum number of columns this database allows in a
975      * <code>SELECT</code> list.
976      *
977      * @return the maximum number of columns allowed;
978      *      a result of zero means that there is no limit or the limit
979      *      is not known
980      * @exception SQLException if a database access error occurs
981      */
982     int getMaxColumnsInSelect() throws SQLException;
983 
984     /**
985      * Retrieves the maximum number of columns this database allows in a table.
986      *
987      * @return the maximum number of columns allowed;
988      *      a result of zero means that there is no limit or the limit
989      *      is not known
990      * @exception SQLException if a database access error occurs
991      */
992     int getMaxColumnsInTable() throws SQLException;
993 
994     /**
995      * Retrieves the maximum number of concurrent connections to this
996      * database that are possible.
997      *
998      * @return the maximum number of active connections possible at one time;
999      *      a result of zero means that there is no limit or the limit
1000      *      is not known
1001      * @exception SQLException if a database access error occurs
1002      */
1003     int getMaxConnections() throws SQLException;
1004 
1005     /**
1006      * Retrieves the maximum number of characters that this database allows in a
1007      * cursor name.
1008      *
1009      * @return the maximum number of characters allowed in a cursor name;
1010      *      a result of zero means that there is no limit or the limit
1011      *      is not known
1012      * @exception SQLException if a database access error occurs
1013      */
1014     int getMaxCursorNameLength() throws SQLException;
1015 
1016     /**
1017      * Retrieves the maximum number of bytes this database allows for an
1018      * index, including all of the parts of the index.
1019      *
1020      * @return the maximum number of bytes allowed; this limit includes the
1021      *      composite of all the constituent parts of the index;
1022      *      a result of zero means that there is no limit or the limit
1023      *      is not known
1024      * @exception SQLException if a database access error occurs
1025      */
1026     int getMaxIndexLength() throws SQLException;
1027 
1028     /**
1029      * Retrieves the maximum number of characters that this database allows in a
1030      * schema name.
1031      *
1032      * @return the maximum number of characters allowed in a schema name;
1033      *      a result of zero means that there is no limit or the limit
1034      *      is not known
1035      * @exception SQLException if a database access error occurs
1036      */
1037     int getMaxSchemaNameLength() throws SQLException;
1038 
1039     /**
1040      * Retrieves the maximum number of characters that this database allows in a
1041      * procedure name.
1042      *
1043      * @return the maximum number of characters allowed in a procedure name;
1044      *      a result of zero means that there is no limit or the limit
1045      *      is not known
1046      * @exception SQLException if a database access error occurs
1047      */
1048     int getMaxProcedureNameLength() throws SQLException;
1049 
1050     /**
1051      * Retrieves the maximum number of characters that this database allows in a
1052      * catalog name.
1053      *
1054      * @return the maximum number of characters allowed in a catalog name;
1055      *      a result of zero means that there is no limit or the limit
1056      *      is not known
1057      * @exception SQLException if a database access error occurs
1058      */
1059     int getMaxCatalogNameLength() throws SQLException;
1060 
1061     /**
1062      * Retrieves the maximum number of bytes this database allows in
1063      * a single row.
1064      *
1065      * @return the maximum number of bytes allowed for a row; a result of
1066      *         zero means that there is no limit or the limit is not known
1067      * @exception SQLException if a database access error occurs
1068      */
1069     int getMaxRowSize() throws SQLException;
1070 
1071     /**
1072      * Retrieves whether the return value for the method
1073      * <code>getMaxRowSize</code> includes the SQL data types
1074      * <code>LONGVARCHAR</code> and <code>LONGVARBINARY</code>.
1075      *
1076      * @return <code>true</code> if so; <code>false</code> otherwise
1077      * @exception SQLException if a database access error occurs
1078      */
1079     boolean doesMaxRowSizeIncludeBlobs() throws SQLException;
1080 
1081     /**
1082      * Retrieves the maximum number of characters this database allows in
1083      * an SQL statement.
1084      *
1085      * @return the maximum number of characters allowed for an SQL statement;
1086      *      a result of zero means that there is no limit or the limit
1087      *      is not known
1088      * @exception SQLException if a database access error occurs
1089      */
1090     int getMaxStatementLength() throws SQLException;
1091 
1092     /**
1093      * Retrieves the maximum number of active statements to this database
1094      * that can be open at the same time.
1095      *
1096      * @return the maximum number of statements that can be open at one time;
1097      *      a result of zero means that there is no limit or the limit
1098      *      is not known
1099      * @exception SQLException if a database access error occurs
1100      */
1101     int getMaxStatements() throws SQLException;
1102 
1103     /**
1104      * Retrieves the maximum number of characters this database allows in
1105      * a table name.
1106      *
1107      * @return the maximum number of characters allowed for a table name;
1108      *      a result of zero means that there is no limit or the limit
1109      *      is not known
1110      * @exception SQLException if a database access error occurs
1111      */
1112     int getMaxTableNameLength() throws SQLException;
1113 
1114     /**
1115      * Retrieves the maximum number of tables this database allows in a
1116      * <code>SELECT</code> statement.
1117      *
1118      * @return the maximum number of tables allowed in a <code>SELECT</code>
1119      *         statement; a result of zero means that there is no limit or
1120      *         the limit is not known
1121      * @exception SQLException if a database access error occurs
1122      */
1123     int getMaxTablesInSelect() throws SQLException;
1124 
1125     /**
1126      * Retrieves the maximum number of characters this database allows in
1127      * a user name.
1128      *
1129      * @return the maximum number of characters allowed for a user name;
1130      *      a result of zero means that there is no limit or the limit
1131      *      is not known
1132      * @exception SQLException if a database access error occurs
1133      */
1134     int getMaxUserNameLength() throws SQLException;
1135 
1136     //----------------------------------------------------------------------
1137 
1138     /**
1139      * Retrieves this database's default transaction isolation level.  The
1140      * possible values are defined in <code>java.sql.Connection</code>.
1141      *
1142      * @return the default isolation level
1143      * @exception SQLException if a database access error occurs
1144      * @see Connection
1145      */
1146     int getDefaultTransactionIsolation() throws SQLException;
1147 
1148     /**
1149      * Retrieves whether this database supports transactions. If not, invoking the
1150      * method <code>commit</code> is a noop, and the isolation level is
1151      * <code>TRANSACTION_NONE</code>.
1152      *
1153      * @return <code>true</code> if transactions are supported;
1154      *         <code>false</code> otherwise
1155      * @exception SQLException if a database access error occurs
1156      */
1157     boolean supportsTransactions() throws SQLException;
1158 
1159     /**
1160      * Retrieves whether this database supports the given transaction isolation level.
1161      *
1162      * @param level one of the transaction isolation levels defined in
1163      *         <code>java.sql.Connection</code>
1164      * @return <code>true</code> if so; <code>false</code> otherwise
1165      * @exception SQLException if a database access error occurs
1166      * @see Connection
1167      */
1168     boolean supportsTransactionIsolationLevel(int level)
1169         throws SQLException;
1170 
1171     /**
1172      * Retrieves whether this database supports both data definition and
1173      * data manipulation statements within a transaction.
1174      *
1175      * @return <code>true</code> if so; <code>false</code> otherwise
1176      * @exception SQLException if a database access error occurs
1177      */
1178     boolean supportsDataDefinitionAndDataManipulationTransactions()
1179         throws SQLException;
1180     /**
1181      * Retrieves whether this database supports only data manipulation
1182      * statements within a transaction.
1183      *
1184      * @return <code>true</code> if so; <code>false</code> otherwise
1185      * @exception SQLException if a database access error occurs
1186      */
1187     boolean supportsDataManipulationTransactionsOnly()
1188         throws SQLException;
1189 
1190     /**
1191      * Retrieves whether a data definition statement within a transaction forces
1192      * the transaction to commit.
1193      *
1194      * @return <code>true</code> if so; <code>false</code> otherwise
1195      * @exception SQLException if a database access error occurs
1196      */
1197     boolean dataDefinitionCausesTransactionCommit()
1198         throws SQLException;
1199 
1200     /**
1201      * Retrieves whether this database ignores a data definition statement
1202      * within a transaction.
1203      *
1204      * @return <code>true</code> if so; <code>false</code> otherwise
1205      * @exception SQLException if a database access error occurs
1206      */
1207     boolean dataDefinitionIgnoredInTransactions()
1208         throws SQLException;
1209 
1210     /**
1211      * Retrieves a description of the stored procedures available in the given
1212      * catalog.
1213      * <P>
1214      * Only procedure descriptions matching the schema and
1215      * procedure name criteria are returned.  They are ordered by
1216      * <code>PROCEDURE_CAT</code>, <code>PROCEDURE_SCHEM</code>,
1217      * <code>PROCEDURE_NAME</code> and <code>SPECIFIC_ NAME</code>.
1218      *
1219      * <P>Each procedure description has the the following columns:
1220      *  <OL>
1221      *  <LI><B>PROCEDURE_CAT</B> String {@code =>} procedure catalog (may be <code>null</code>)
1222      *  <LI><B>PROCEDURE_SCHEM</B> String {@code =>} procedure schema (may be <code>null</code>)
1223      *  <LI><B>PROCEDURE_NAME</B> String {@code =>} procedure name
1224      *  <LI> reserved for future use
1225      *  <LI> reserved for future use
1226      *  <LI> reserved for future use
1227      *  <LI><B>REMARKS</B> String {@code =>} explanatory comment on the procedure
1228      *  <LI><B>PROCEDURE_TYPE</B> short {@code =>} kind of procedure:
1229      *      <UL>
1230      *      <LI> procedureResultUnknown - Cannot determine if  a return value
1231      *       will be returned
1232      *      <LI> procedureNoResult - Does not return a return value
1233      *      <LI> procedureReturnsResult - Returns a return value
1234      *      </UL>
1235      *  <LI><B>SPECIFIC_NAME</B> String  {@code =>} The name which uniquely identifies this
1236      * procedure within its schema.
1237      *  </OL>
1238      * <p>
1239      * A user may not have permissions to execute any of the procedures that are
1240      * returned by <code>getProcedures</code>
1241      *
1242      * @param catalog a catalog name; must match the catalog name as it
1243      *        is stored in the database; "" retrieves those without a catalog;
1244      *        <code>null</code> means that the catalog name should not be used to narrow
1245      *        the search
1246      * @param schemaPattern a schema name pattern; must match the schema name
1247      *        as it is stored in the database; "" retrieves those without a schema;
1248      *        <code>null</code> means that the schema name should not be used to narrow
1249      *        the search
1250      * @param procedureNamePattern a procedure name pattern; must match the
1251      *        procedure name as it is stored in the database
1252      * @return <code>ResultSet</code> - each row is a procedure description
1253      * @exception SQLException if a database access error occurs
1254      * @see #getSearchStringEscape
1255      */
1256     ResultSet getProcedures(String catalog, String schemaPattern,
1257                             String procedureNamePattern) throws SQLException;
1258 
1259     /**
1260      * Indicates that it is not known whether the procedure returns
1261      * a result.
1262      * <P>
1263      * A possible value for column <code>PROCEDURE_TYPE</code> in the
1264      * <code>ResultSet</code> object returned by the method
1265      * <code>getProcedures</code>.
1266      */
1267     int procedureResultUnknown  = 0;
1268 
1269     /**
1270      * Indicates that the procedure does not return a result.
1271      * <P>
1272      * A possible value for column <code>PROCEDURE_TYPE</code> in the
1273      * <code>ResultSet</code> object returned by the method
1274      * <code>getProcedures</code>.
1275      */
1276     int procedureNoResult               = 1;
1277 
1278     /**
1279      * Indicates that the procedure returns a result.
1280      * <P>
1281      * A possible value for column <code>PROCEDURE_TYPE</code> in the
1282      * <code>ResultSet</code> object returned by the method
1283      * <code>getProcedures</code>.
1284      */
1285     int procedureReturnsResult  = 2;
1286 
1287     /**
1288      * Retrieves a description of the given catalog's stored procedure parameter
1289      * and result columns.
1290      *
1291      * <P>Only descriptions matching the schema, procedure and
1292      * parameter name criteria are returned.  They are ordered by
1293      * PROCEDURE_CAT, PROCEDURE_SCHEM, PROCEDURE_NAME and SPECIFIC_NAME. Within this, the return value,
1294      * if any, is first. Next are the parameter descriptions in call
1295      * order. The column descriptions follow in column number order.
1296      *
1297      * <P>Each row in the <code>ResultSet</code> is a parameter description or
1298      * column description with the following fields:
1299      *  <OL>
1300      *  <LI><B>PROCEDURE_CAT</B> String {@code =>} procedure catalog (may be <code>null</code>)
1301      *  <LI><B>PROCEDURE_SCHEM</B> String {@code =>} procedure schema (may be <code>null</code>)
1302      *  <LI><B>PROCEDURE_NAME</B> String {@code =>} procedure name
1303      *  <LI><B>COLUMN_NAME</B> String {@code =>} column/parameter name
1304      *  <LI><B>COLUMN_TYPE</B> Short {@code =>} kind of column/parameter:
1305      *      <UL>
1306      *      <LI> procedureColumnUnknown - nobody knows
1307      *      <LI> procedureColumnIn - IN parameter
1308      *      <LI> procedureColumnInOut - INOUT parameter
1309      *      <LI> procedureColumnOut - OUT parameter
1310      *      <LI> procedureColumnReturn - procedure return value
1311      *      <LI> procedureColumnResult - result column in <code>ResultSet</code>
1312      *      </UL>
1313      *  <LI><B>DATA_TYPE</B> int {@code =>} SQL type from java.sql.Types
1314      *  <LI><B>TYPE_NAME</B> String {@code =>} SQL type name, for a UDT type the
1315      *  type name is fully qualified
1316      *  <LI><B>PRECISION</B> int {@code =>} precision
1317      *  <LI><B>LENGTH</B> int {@code =>} length in bytes of data
1318      *  <LI><B>SCALE</B> short {@code =>} scale -  null is returned for data types where
1319      * SCALE is not applicable.
1320      *  <LI><B>RADIX</B> short {@code =>} radix
1321      *  <LI><B>NULLABLE</B> short {@code =>} can it contain NULL.
1322      *      <UL>
1323      *      <LI> procedureNoNulls - does not allow NULL values
1324      *      <LI> procedureNullable - allows NULL values
1325      *      <LI> procedureNullableUnknown - nullability unknown
1326      *      </UL>
1327      *  <LI><B>REMARKS</B> String {@code =>} comment describing parameter/column
1328      *  <LI><B>COLUMN_DEF</B> String {@code =>} default value for the column, which should be interpreted as a string when the value is enclosed in single quotes (may be <code>null</code>)
1329      *      <UL>
1330      *      <LI> The string NULL (not enclosed in quotes) - if NULL was specified as the default value
1331      *      <LI> TRUNCATE (not enclosed in quotes)        - if the specified default value cannot be represented without truncation
1332      *      <LI> NULL                                     - if a default value was not specified
1333      *      </UL>
1334      *  <LI><B>SQL_DATA_TYPE</B> int  {@code =>} reserved for future use
1335      *  <LI><B>SQL_DATETIME_SUB</B> int  {@code =>} reserved for future use
1336      *  <LI><B>CHAR_OCTET_LENGTH</B> int  {@code =>} the maximum length of binary and character based columns.  For any other datatype the returned value is a
1337      * NULL
1338      *  <LI><B>ORDINAL_POSITION</B> int  {@code =>} the ordinal position, starting from 1, for the input and output parameters for a procedure. A value of 0
1339      *is returned if this row describes the procedure's return value.  For result set columns, it is the
1340      *ordinal position of the column in the result set starting from 1.  If there are
1341      *multiple result sets, the column ordinal positions are implementation
1342      * defined.
1343      *  <LI><B>IS_NULLABLE</B> String  {@code =>} ISO rules are used to determine the nullability for a column.
1344      *       <UL>
1345      *       <LI> YES           --- if the column can include NULLs
1346      *       <LI> NO            --- if the column cannot include NULLs
1347      *       <LI> empty string  --- if the nullability for the
1348      * column is unknown
1349      *       </UL>
1350      *  <LI><B>SPECIFIC_NAME</B> String  {@code =>} the name which uniquely identifies this procedure within its schema.
1351      *  </OL>
1352      *
1353      * <P><B>Note:</B> Some databases may not return the column
1354      * descriptions for a procedure.
1355      *
1356      * <p>The PRECISION column represents the specified column size for the given column.
1357      * For numeric data, this is the maximum precision.  For character data, this is the length in characters.
1358      * For datetime datatypes, this is the length in characters of the String representation (assuming the
1359      * maximum allowed precision of the fractional seconds component). For binary data, this is the length in bytes.  For the ROWID datatype,
1360      * this is the length in bytes. Null is returned for data types where the
1361      * column size is not applicable.
1362      * @param catalog a catalog name; must match the catalog name as it
1363      *        is stored in the database; "" retrieves those without a catalog;
1364      *        <code>null</code> means that the catalog name should not be used to narrow
1365      *        the search
1366      * @param schemaPattern a schema name pattern; must match the schema name
1367      *        as it is stored in the database; "" retrieves those without a schema;
1368      *        <code>null</code> means that the schema name should not be used to narrow
1369      *        the search
1370      * @param procedureNamePattern a procedure name pattern; must match the
1371      *        procedure name as it is stored in the database
1372      * @param columnNamePattern a column name pattern; must match the column name
1373      *        as it is stored in the database
1374      * @return <code>ResultSet</code> - each row describes a stored procedure parameter or
1375      *      column
1376      * @exception SQLException if a database access error occurs
1377      * @see #getSearchStringEscape
1378      */
1379     ResultSet getProcedureColumns(String catalog,
1380                                   String schemaPattern,
1381                                   String procedureNamePattern,
1382                                   String columnNamePattern) throws SQLException;
1383 
1384     /**
1385      * Indicates that type of the column is unknown.
1386      * <P>
1387      * A possible value for the column
1388      * <code>COLUMN_TYPE</code>
1389      * in the <code>ResultSet</code>
1390      * returned by the method <code>getProcedureColumns</code>.
1391      */
1392     int procedureColumnUnknown = 0;
1393 
1394     /**
1395      * Indicates that the column stores IN parameters.
1396      * <P>
1397      * A possible value for the column
1398      * <code>COLUMN_TYPE</code>
1399      * in the <code>ResultSet</code>
1400      * returned by the method <code>getProcedureColumns</code>.
1401      */
1402     int procedureColumnIn = 1;
1403 
1404     /**
1405      * Indicates that the column stores INOUT parameters.
1406      * <P>
1407      * A possible value for the column
1408      * <code>COLUMN_TYPE</code>
1409      * in the <code>ResultSet</code>
1410      * returned by the method <code>getProcedureColumns</code>.
1411      */
1412     int procedureColumnInOut = 2;
1413 
1414     /**
1415      * Indicates that the column stores OUT parameters.
1416      * <P>
1417      * A possible value for the column
1418      * <code>COLUMN_TYPE</code>
1419      * in the <code>ResultSet</code>
1420     * returned by the method <code>getProcedureColumns</code>.
1421      */
1422     int procedureColumnOut = 4;
1423     /**
1424      * Indicates that the column stores return values.
1425      * <P>
1426      * A possible value for the column
1427      * <code>COLUMN_TYPE</code>
1428      * in the <code>ResultSet</code>
1429      * returned by the method <code>getProcedureColumns</code>.
1430      */
1431     int procedureColumnReturn = 5;
1432 
1433     /**
1434      * Indicates that the column stores results.
1435      * <P>
1436      * A possible value for the column
1437      * <code>COLUMN_TYPE</code>
1438      * in the <code>ResultSet</code>
1439      * returned by the method <code>getProcedureColumns</code>.
1440      */
1441     int procedureColumnResult = 3;
1442 
1443     /**
1444      * Indicates that <code>NULL</code> values are not allowed.
1445      * <P>
1446      * A possible value for the column
1447      * <code>NULLABLE</code>
1448      * in the <code>ResultSet</code> object
1449      * returned by the method <code>getProcedureColumns</code>.
1450      */
1451     int procedureNoNulls = 0;
1452 
1453     /**
1454      * Indicates that <code>NULL</code> values are allowed.
1455      * <P>
1456      * A possible value for the column
1457      * <code>NULLABLE</code>
1458      * in the <code>ResultSet</code> object
1459      * returned by the method <code>getProcedureColumns</code>.
1460      */
1461     int procedureNullable = 1;
1462 
1463     /**
1464      * Indicates that whether <code>NULL</code> values are allowed
1465      * is unknown.
1466      * <P>
1467      * A possible value for the column
1468      * <code>NULLABLE</code>
1469      * in the <code>ResultSet</code> object
1470      * returned by the method <code>getProcedureColumns</code>.
1471      */
1472     int procedureNullableUnknown = 2;
1473 
1474 
1475     /**
1476      * Retrieves a description of the tables available in the given catalog.
1477      * Only table descriptions matching the catalog, schema, table
1478      * name and type criteria are returned.  They are ordered by
1479      * <code>TABLE_TYPE</code>, <code>TABLE_CAT</code>,
1480      * <code>TABLE_SCHEM</code> and <code>TABLE_NAME</code>.
1481      * <P>
1482      * Each table description has the following columns:
1483      *  <OL>
1484      *  <LI><B>TABLE_CAT</B> String {@code =>} table catalog (may be <code>null</code>)
1485      *  <LI><B>TABLE_SCHEM</B> String {@code =>} table schema (may be <code>null</code>)
1486      *  <LI><B>TABLE_NAME</B> String {@code =>} table name
1487      *  <LI><B>TABLE_TYPE</B> String {@code =>} table type.  Typical types are "TABLE",
1488      *                  "VIEW", "SYSTEM TABLE", "GLOBAL TEMPORARY",
1489      *                  "LOCAL TEMPORARY", "ALIAS", "SYNONYM".
1490      *  <LI><B>REMARKS</B> String {@code =>} explanatory comment on the table
1491      *  <LI><B>TYPE_CAT</B> String {@code =>} the types catalog (may be <code>null</code>)
1492      *  <LI><B>TYPE_SCHEM</B> String {@code =>} the types schema (may be <code>null</code>)
1493      *  <LI><B>TYPE_NAME</B> String {@code =>} type name (may be <code>null</code>)
1494      *  <LI><B>SELF_REFERENCING_COL_NAME</B> String {@code =>} name of the designated
1495      *                  "identifier" column of a typed table (may be <code>null</code>)
1496      *  <LI><B>REF_GENERATION</B> String {@code =>} specifies how values in
1497      *                  SELF_REFERENCING_COL_NAME are created. Values are
1498      *                  "SYSTEM", "USER", "DERIVED". (may be <code>null</code>)
1499      *  </OL>
1500      *
1501      * <P><B>Note:</B> Some databases may not return information for
1502      * all tables.
1503      *
1504      * @param catalog a catalog name; must match the catalog name as it
1505      *        is stored in the database; "" retrieves those without a catalog;
1506      *        <code>null</code> means that the catalog name should not be used to narrow
1507      *        the search
1508      * @param schemaPattern a schema name pattern; must match the schema name
1509      *        as it is stored in the database; "" retrieves those without a schema;
1510      *        <code>null</code> means that the schema name should not be used to narrow
1511      *        the search
1512      * @param tableNamePattern a table name pattern; must match the
1513      *        table name as it is stored in the database
1514      * @param types a list of table types, which must be from the list of table types
1515      *         returned from {@link #getTableTypes},to include; <code>null</code> returns
1516      * all types
1517      * @return <code>ResultSet</code> - each row is a table description
1518      * @exception SQLException if a database access error occurs
1519      * @see #getSearchStringEscape
1520      */
1521     ResultSet getTables(String catalog, String schemaPattern,
1522                         String tableNamePattern, String types[]) throws SQLException;
1523 
1524     /**
1525      * Retrieves the schema names available in this database.  The results
1526      * are ordered by <code>TABLE_CATALOG</code> and
1527      * <code>TABLE_SCHEM</code>.
1528      *
1529      * <P>The schema columns are:
1530      *  <OL>
1531      *  <LI><B>TABLE_SCHEM</B> String {@code =>} schema name
1532      *  <LI><B>TABLE_CATALOG</B> String {@code =>} catalog name (may be <code>null</code>)
1533      *  </OL>
1534      *
1535      * @return a <code>ResultSet</code> object in which each row is a
1536      *         schema description
1537      * @exception SQLException if a database access error occurs
1538      *
1539      */
1540     ResultSet getSchemas() throws SQLException;
1541 
1542     /**
1543      * Retrieves the catalog names available in this database.  The results
1544      * are ordered by catalog name.
1545      *
1546      * <P>The catalog column is:
1547      *  <OL>
1548      *  <LI><B>TABLE_CAT</B> String {@code =>} catalog name
1549      *  </OL>
1550      *
1551      * @return a <code>ResultSet</code> object in which each row has a
1552      *         single <code>String</code> column that is a catalog name
1553      * @exception SQLException if a database access error occurs
1554      */
1555     ResultSet getCatalogs() throws SQLException;
1556 
1557     /**
1558      * Retrieves the table types available in this database.  The results
1559      * are ordered by table type.
1560      *
1561      * <P>The table type is:
1562      *  <OL>
1563      *  <LI><B>TABLE_TYPE</B> String {@code =>} table type.  Typical types are "TABLE",
1564      *                  "VIEW", "SYSTEM TABLE", "GLOBAL TEMPORARY",
1565      *                  "LOCAL TEMPORARY", "ALIAS", "SYNONYM".
1566      *  </OL>
1567      *
1568      * @return a <code>ResultSet</code> object in which each row has a
1569      *         single <code>String</code> column that is a table type
1570      * @exception SQLException if a database access error occurs
1571      */
1572     ResultSet getTableTypes() throws SQLException;
1573 
1574     /**
1575      * Retrieves a description of table columns available in
1576      * the specified catalog.
1577      *
1578      * <P>Only column descriptions matching the catalog, schema, table
1579      * and column name criteria are returned.  They are ordered by
1580      * <code>TABLE_CAT</code>,<code>TABLE_SCHEM</code>,
1581      * <code>TABLE_NAME</code>, and <code>ORDINAL_POSITION</code>.
1582      *
1583      * <P>Each column description has the following columns:
1584      *  <OL>
1585      *  <LI><B>TABLE_CAT</B> String {@code =>} table catalog (may be <code>null</code>)
1586      *  <LI><B>TABLE_SCHEM</B> String {@code =>} table schema (may be <code>null</code>)
1587      *  <LI><B>TABLE_NAME</B> String {@code =>} table name
1588      *  <LI><B>COLUMN_NAME</B> String {@code =>} column name
1589      *  <LI><B>DATA_TYPE</B> int {@code =>} SQL type from java.sql.Types
1590      *  <LI><B>TYPE_NAME</B> String {@code =>} Data source dependent type name,
1591      *  for a UDT the type name is fully qualified
1592      *  <LI><B>COLUMN_SIZE</B> int {@code =>} column size.
1593      *  <LI><B>BUFFER_LENGTH</B> is not used.
1594      *  <LI><B>DECIMAL_DIGITS</B> int {@code =>} the number of fractional digits. Null is returned for data types where
1595      * DECIMAL_DIGITS is not applicable.
1596      *  <LI><B>NUM_PREC_RADIX</B> int {@code =>} Radix (typically either 10 or 2)
1597      *  <LI><B>NULLABLE</B> int {@code =>} is NULL allowed.
1598      *      <UL>
1599      *      <LI> columnNoNulls - might not allow <code>NULL</code> values
1600      *      <LI> columnNullable - definitely allows <code>NULL</code> values
1601      *      <LI> columnNullableUnknown - nullability unknown
1602      *      </UL>
1603      *  <LI><B>REMARKS</B> String {@code =>} comment describing column (may be <code>null</code>)
1604      *  <LI><B>COLUMN_DEF</B> String {@code =>} default value for the column, which should be interpreted as a string when the value is enclosed in single quotes (may be <code>null</code>)
1605      *  <LI><B>SQL_DATA_TYPE</B> int {@code =>} unused
1606      *  <LI><B>SQL_DATETIME_SUB</B> int {@code =>} unused
1607      *  <LI><B>CHAR_OCTET_LENGTH</B> int {@code =>} for char types the
1608      *       maximum number of bytes in the column
1609      *  <LI><B>ORDINAL_POSITION</B> int {@code =>} index of column in table
1610      *      (starting at 1)
1611      *  <LI><B>IS_NULLABLE</B> String  {@code =>} ISO rules are used to determine the nullability for a column.
1612      *       <UL>
1613      *       <LI> YES           --- if the column can include NULLs
1614      *       <LI> NO            --- if the column cannot include NULLs
1615      *       <LI> empty string  --- if the nullability for the
1616      * column is unknown
1617      *       </UL>
1618      *  <LI><B>SCOPE_CATALOG</B> String {@code =>} catalog of table that is the scope
1619      *      of a reference attribute (<code>null</code> if DATA_TYPE isn't REF)
1620      *  <LI><B>SCOPE_SCHEMA</B> String {@code =>} schema of table that is the scope
1621      *      of a reference attribute (<code>null</code> if the DATA_TYPE isn't REF)
1622      *  <LI><B>SCOPE_TABLE</B> String {@code =>} table name that this the scope
1623      *      of a reference attribute (<code>null</code> if the DATA_TYPE isn't REF)
1624      *  <LI><B>SOURCE_DATA_TYPE</B> short {@code =>} source type of a distinct type or user-generated
1625      *      Ref type, SQL type from java.sql.Types (<code>null</code> if DATA_TYPE
1626      *      isn't DISTINCT or user-generated REF)
1627      *   <LI><B>IS_AUTOINCREMENT</B> String  {@code =>} Indicates whether this column is auto incremented
1628      *       <UL>
1629      *       <LI> YES           --- if the column is auto incremented
1630      *       <LI> NO            --- if the column is not auto incremented
1631      *       <LI> empty string  --- if it cannot be determined whether the column is auto incremented
1632      *       </UL>
1633      *   <LI><B>IS_GENERATEDCOLUMN</B> String  {@code =>} Indicates whether this is a generated column
1634      *       <UL>
1635      *       <LI> YES           --- if this a generated column
1636      *       <LI> NO            --- if this not a generated column
1637      *       <LI> empty string  --- if it cannot be determined whether this is a generated column
1638      *       </UL>
1639      *  </OL>
1640      *
1641      * <p>The COLUMN_SIZE column specifies the column size for the given column.
1642      * For numeric data, this is the maximum precision.  For character data, this is the length in characters.
1643      * For datetime datatypes, this is the length in characters of the String representation (assuming the
1644      * maximum allowed precision of the fractional seconds component). For binary data, this is the length in bytes.  For the ROWID datatype,
1645      * this is the length in bytes. Null is returned for data types where the
1646      * column size is not applicable.
1647      *
1648      * @param catalog a catalog name; must match the catalog name as it
1649      *        is stored in the database; "" retrieves those without a catalog;
1650      *        <code>null</code> means that the catalog name should not be used to narrow
1651      *        the search
1652      * @param schemaPattern a schema name pattern; must match the schema name
1653      *        as it is stored in the database; "" retrieves those without a schema;
1654      *        <code>null</code> means that the schema name should not be used to narrow
1655      *        the search
1656      * @param tableNamePattern a table name pattern; must match the
1657      *        table name as it is stored in the database
1658      * @param columnNamePattern a column name pattern; must match the column
1659      *        name as it is stored in the database
1660      * @return <code>ResultSet</code> - each row is a column description
1661      * @exception SQLException if a database access error occurs
1662      * @see #getSearchStringEscape
1663      */
1664     ResultSet getColumns(String catalog, String schemaPattern,
1665                          String tableNamePattern, String columnNamePattern)
1666         throws SQLException;
1667 
1668     /**
1669      * Indicates that the column might not allow <code>NULL</code> values.
1670      * <P>
1671      * A possible value for the column
1672      * <code>NULLABLE</code>
1673      * in the <code>ResultSet</code> returned by the method
1674      * <code>getColumns</code>.
1675      */
1676     int columnNoNulls = 0;
1677 
1678     /**
1679      * Indicates that the column definitely allows <code>NULL</code> values.
1680      * <P>
1681      * A possible value for the column
1682      * <code>NULLABLE</code>
1683      * in the <code>ResultSet</code> returned by the method
1684      * <code>getColumns</code>.
1685      */
1686     int columnNullable = 1;
1687 
1688     /**
1689      * Indicates that the nullability of columns is unknown.
1690      * <P>
1691      * A possible value for the column
1692      * <code>NULLABLE</code>
1693      * in the <code>ResultSet</code> returned by the method
1694      * <code>getColumns</code>.
1695      */
1696     int columnNullableUnknown = 2;
1697 
1698     /**
1699      * Retrieves a description of the access rights for a table's columns.
1700      *
1701      * <P>Only privileges matching the column name criteria are
1702      * returned.  They are ordered by COLUMN_NAME and PRIVILEGE.
1703      *
1704      * <P>Each privilege description has the following columns:
1705      *  <OL>
1706      *  <LI><B>TABLE_CAT</B> String {@code =>} table catalog (may be <code>null</code>)
1707      *  <LI><B>TABLE_SCHEM</B> String {@code =>} table schema (may be <code>null</code>)
1708      *  <LI><B>TABLE_NAME</B> String {@code =>} table name
1709      *  <LI><B>COLUMN_NAME</B> String {@code =>} column name
1710      *  <LI><B>GRANTOR</B> String {@code =>} grantor of access (may be <code>null</code>)
1711      *  <LI><B>GRANTEE</B> String {@code =>} grantee of access
1712      *  <LI><B>PRIVILEGE</B> String {@code =>} name of access (SELECT,
1713      *      INSERT, UPDATE, REFRENCES, ...)
1714      *  <LI><B>IS_GRANTABLE</B> String {@code =>} "YES" if grantee is permitted
1715      *      to grant to others; "NO" if not; <code>null</code> if unknown
1716      *  </OL>
1717      *
1718      * @param catalog a catalog name; must match the catalog name as it
1719      *        is stored in the database; "" retrieves those without a catalog;
1720      *        <code>null</code> means that the catalog name should not be used to narrow
1721      *        the search
1722      * @param schema a schema name; must match the schema name as it is
1723      *        stored in the database; "" retrieves those without a schema;
1724      *        <code>null</code> means that the schema name should not be used to narrow
1725      *        the search
1726      * @param table a table name; must match the table name as it is
1727      *        stored in the database
1728      * @param columnNamePattern a column name pattern; must match the column
1729      *        name as it is stored in the database
1730      * @return <code>ResultSet</code> - each row is a column privilege description
1731      * @exception SQLException if a database access error occurs
1732      * @see #getSearchStringEscape
1733      */
1734     ResultSet getColumnPrivileges(String catalog, String schema,
1735                                   String table, String columnNamePattern) throws SQLException;
1736 
1737     /**
1738      * Retrieves a description of the access rights for each table available
1739      * in a catalog. Note that a table privilege applies to one or
1740      * more columns in the table. It would be wrong to assume that
1741      * this privilege applies to all columns (this may be true for
1742      * some systems but is not true for all.)
1743      *
1744      * <P>Only privileges matching the schema and table name
1745      * criteria are returned.  They are ordered by
1746      * <code>TABLE_CAT</code>,
1747      * <code>TABLE_SCHEM</code>, <code>TABLE_NAME</code>,
1748      * and <code>PRIVILEGE</code>.
1749      *
1750      * <P>Each privilege description has the following columns:
1751      *  <OL>
1752      *  <LI><B>TABLE_CAT</B> String {@code =>} table catalog (may be <code>null</code>)
1753      *  <LI><B>TABLE_SCHEM</B> String {@code =>} table schema (may be <code>null</code>)
1754      *  <LI><B>TABLE_NAME</B> String {@code =>} table name
1755      *  <LI><B>GRANTOR</B> String {@code =>} grantor of access (may be <code>null</code>)
1756      *  <LI><B>GRANTEE</B> String {@code =>} grantee of access
1757      *  <LI><B>PRIVILEGE</B> String {@code =>} name of access (SELECT,
1758      *      INSERT, UPDATE, REFRENCES, ...)
1759      *  <LI><B>IS_GRANTABLE</B> String {@code =>} "YES" if grantee is permitted
1760      *      to grant to others; "NO" if not; <code>null</code> if unknown
1761      *  </OL>
1762      *
1763      * @param catalog a catalog name; must match the catalog name as it
1764      *        is stored in the database; "" retrieves those without a catalog;
1765      *        <code>null</code> means that the catalog name should not be used to narrow
1766      *        the search
1767      * @param schemaPattern a schema name pattern; must match the schema name
1768      *        as it is stored in the database; "" retrieves those without a schema;
1769      *        <code>null</code> means that the schema name should not be used to narrow
1770      *        the search
1771      * @param tableNamePattern a table name pattern; must match the
1772      *        table name as it is stored in the database
1773      * @return <code>ResultSet</code> - each row is a table privilege description
1774      * @exception SQLException if a database access error occurs
1775      * @see #getSearchStringEscape
1776      */
1777     ResultSet getTablePrivileges(String catalog, String schemaPattern,
1778                                  String tableNamePattern) throws SQLException;
1779 
1780     /**
1781      * Retrieves a description of a table's optimal set of columns that
1782      * uniquely identifies a row. They are ordered by SCOPE.
1783      *
1784      * <P>Each column description has the following columns:
1785      *  <OL>
1786      *  <LI><B>SCOPE</B> short {@code =>} actual scope of result
1787      *      <UL>
1788      *      <LI> bestRowTemporary - very temporary, while using row
1789      *      <LI> bestRowTransaction - valid for remainder of current transaction
1790      *      <LI> bestRowSession - valid for remainder of current session
1791      *      </UL>
1792      *  <LI><B>COLUMN_NAME</B> String {@code =>} column name
1793      *  <LI><B>DATA_TYPE</B> int {@code =>} SQL data type from java.sql.Types
1794      *  <LI><B>TYPE_NAME</B> String {@code =>} Data source dependent type name,
1795      *  for a UDT the type name is fully qualified
1796      *  <LI><B>COLUMN_SIZE</B> int {@code =>} precision
1797      *  <LI><B>BUFFER_LENGTH</B> int {@code =>} not used
1798      *  <LI><B>DECIMAL_DIGITS</B> short  {@code =>} scale - Null is returned for data types where
1799      * DECIMAL_DIGITS is not applicable.
1800      *  <LI><B>PSEUDO_COLUMN</B> short {@code =>} is this a pseudo column
1801      *      like an Oracle ROWID
1802      *      <UL>
1803      *      <LI> bestRowUnknown - may or may not be pseudo column
1804      *      <LI> bestRowNotPseudo - is NOT a pseudo column
1805      *      <LI> bestRowPseudo - is a pseudo column
1806      *      </UL>
1807      *  </OL>
1808      *
1809      * <p>The COLUMN_SIZE column represents the specified column size for the given column.
1810      * For numeric data, this is the maximum precision.  For character data, this is the length in characters.
1811      * For datetime datatypes, this is the length in characters of the String representation (assuming the
1812      * maximum allowed precision of the fractional seconds component). For binary data, this is the length in bytes.  For the ROWID datatype,
1813      * this is the length in bytes. Null is returned for data types where the
1814      * column size is not applicable.
1815      *
1816      * @param catalog a catalog name; must match the catalog name as it
1817      *        is stored in the database; "" retrieves those without a catalog;
1818      *        <code>null</code> means that the catalog name should not be used to narrow
1819      *        the search
1820      * @param schema a schema name; must match the schema name
1821      *        as it is stored in the database; "" retrieves those without a schema;
1822      *        <code>null</code> means that the schema name should not be used to narrow
1823      *        the search
1824      * @param table a table name; must match the table name as it is stored
1825      *        in the database
1826      * @param scope the scope of interest; use same values as SCOPE
1827      * @param nullable include columns that are nullable.
1828      * @return <code>ResultSet</code> - each row is a column description
1829      * @exception SQLException if a database access error occurs
1830      */
1831     ResultSet getBestRowIdentifier(String catalog, String schema,
1832                                    String table, int scope, boolean nullable) throws SQLException;
1833 
1834     /**
1835      * Indicates that the scope of the best row identifier is
1836      * very temporary, lasting only while the
1837      * row is being used.
1838      * <P>
1839      * A possible value for the column
1840      * <code>SCOPE</code>
1841      * in the <code>ResultSet</code> object
1842      * returned by the method <code>getBestRowIdentifier</code>.
1843      */
1844     int bestRowTemporary   = 0;
1845 
1846     /**
1847      * Indicates that the scope of the best row identifier is
1848      * the remainder of the current transaction.
1849      * <P>
1850      * A possible value for the column
1851      * <code>SCOPE</code>
1852      * in the <code>ResultSet</code> object
1853      * returned by the method <code>getBestRowIdentifier</code>.
1854      */
1855     int bestRowTransaction = 1;
1856 
1857     /**
1858      * Indicates that the scope of the best row identifier is
1859      * the remainder of the current session.
1860      * <P>
1861      * A possible value for the column
1862      * <code>SCOPE</code>
1863      * in the <code>ResultSet</code> object
1864      * returned by the method <code>getBestRowIdentifier</code>.
1865      */
1866     int bestRowSession     = 2;
1867 
1868     /**
1869      * Indicates that the best row identifier may or may not be a pseudo column.
1870      * <P>
1871      * A possible value for the column
1872      * <code>PSEUDO_COLUMN</code>
1873      * in the <code>ResultSet</code> object
1874      * returned by the method <code>getBestRowIdentifier</code>.
1875      */
1876     int bestRowUnknown  = 0;
1877 
1878     /**
1879      * Indicates that the best row identifier is NOT a pseudo column.
1880      * <P>
1881      * A possible value for the column
1882      * <code>PSEUDO_COLUMN</code>
1883      * in the <code>ResultSet</code> object
1884      * returned by the method <code>getBestRowIdentifier</code>.
1885      */
1886     int bestRowNotPseudo        = 1;
1887 
1888     /**
1889      * Indicates that the best row identifier is a pseudo column.
1890      * <P>
1891      * A possible value for the column
1892      * <code>PSEUDO_COLUMN</code>
1893      * in the <code>ResultSet</code> object
1894      * returned by the method <code>getBestRowIdentifier</code>.
1895      */
1896     int bestRowPseudo   = 2;
1897 
1898     /**
1899      * Retrieves a description of a table's columns that are automatically
1900      * updated when any value in a row is updated.  They are
1901      * unordered.
1902      *
1903      * <P>Each column description has the following columns:
1904      *  <OL>
1905      *  <LI><B>SCOPE</B> short {@code =>} is not used
1906      *  <LI><B>COLUMN_NAME</B> String {@code =>} column name
1907      *  <LI><B>DATA_TYPE</B> int {@code =>} SQL data type from <code>java.sql.Types</code>
1908      *  <LI><B>TYPE_NAME</B> String {@code =>} Data source-dependent type name
1909      *  <LI><B>COLUMN_SIZE</B> int {@code =>} precision
1910      *  <LI><B>BUFFER_LENGTH</B> int {@code =>} length of column value in bytes
1911      *  <LI><B>DECIMAL_DIGITS</B> short  {@code =>} scale - Null is returned for data types where
1912      * DECIMAL_DIGITS is not applicable.
1913      *  <LI><B>PSEUDO_COLUMN</B> short {@code =>} whether this is pseudo column
1914      *      like an Oracle ROWID
1915      *      <UL>
1916      *      <LI> versionColumnUnknown - may or may not be pseudo column
1917      *      <LI> versionColumnNotPseudo - is NOT a pseudo column
1918      *      <LI> versionColumnPseudo - is a pseudo column
1919      *      </UL>
1920      *  </OL>
1921      *
1922      * <p>The COLUMN_SIZE column represents the specified column size for the given column.
1923      * For numeric data, this is the maximum precision.  For character data, this is the length in characters.
1924      * For datetime datatypes, this is the length in characters of the String representation (assuming the
1925      * maximum allowed precision of the fractional seconds component). For binary data, this is the length in bytes.  For the ROWID datatype,
1926      * this is the length in bytes. Null is returned for data types where the
1927      * column size is not applicable.
1928      * @param catalog a catalog name; must match the catalog name as it
1929      *        is stored in the database; "" retrieves those without a catalog;
1930      *        <code>null</code> means that the catalog name should not be used to narrow
1931      *        the search
1932      * @param schema a schema name; must match the schema name
1933      *        as it is stored in the database; "" retrieves those without a schema;
1934      *        <code>null</code> means that the schema name should not be used to narrow
1935      *        the search
1936      * @param table a table name; must match the table name as it is stored
1937      *        in the database
1938      * @return a <code>ResultSet</code> object in which each row is a
1939      *         column description
1940      * @exception SQLException if a database access error occurs
1941      */
1942     ResultSet getVersionColumns(String catalog, String schema,
1943                                 String table) throws SQLException;
1944 
1945     /**
1946      * Indicates that this version column may or may not be a pseudo column.
1947      * <P>
1948      * A possible value for the column
1949      * <code>PSEUDO_COLUMN</code>
1950      * in the <code>ResultSet</code> object
1951      * returned by the method <code>getVersionColumns</code>.
1952      */
1953     int versionColumnUnknown    = 0;
1954 
1955     /**
1956      * Indicates that this version column is NOT a pseudo column.
1957      * <P>
1958      * A possible value for the column
1959      * <code>PSEUDO_COLUMN</code>
1960      * in the <code>ResultSet</code> object
1961      * returned by the method <code>getVersionColumns</code>.
1962      */
1963     int versionColumnNotPseudo  = 1;
1964 
1965     /**
1966      * Indicates that this version column is a pseudo column.
1967      * <P>
1968      * A possible value for the column
1969      * <code>PSEUDO_COLUMN</code>
1970      * in the <code>ResultSet</code> object
1971      * returned by the method <code>getVersionColumns</code>.
1972      */
1973     int versionColumnPseudo     = 2;
1974 
1975     /**
1976      * Retrieves a description of the given table's primary key columns.  They
1977      * are ordered by COLUMN_NAME.
1978      *
1979      * <P>Each primary key column description has the following columns:
1980      *  <OL>
1981      *  <LI><B>TABLE_CAT</B> String {@code =>} table catalog (may be <code>null</code>)
1982      *  <LI><B>TABLE_SCHEM</B> String {@code =>} table schema (may be <code>null</code>)
1983      *  <LI><B>TABLE_NAME</B> String {@code =>} table name
1984      *  <LI><B>COLUMN_NAME</B> String {@code =>} column name
1985      *  <LI><B>KEY_SEQ</B> short {@code =>} sequence number within primary key( a value
1986      *  of 1 represents the first column of the primary key, a value of 2 would
1987      *  represent the second column within the primary key).
1988      *  <LI><B>PK_NAME</B> String {@code =>} primary key name (may be <code>null</code>)
1989      *  </OL>
1990      *
1991      * @param catalog a catalog name; must match the catalog name as it
1992      *        is stored in the database; "" retrieves those without a catalog;
1993      *        <code>null</code> means that the catalog name should not be used to narrow
1994      *        the search
1995      * @param schema a schema name; must match the schema name
1996      *        as it is stored in the database; "" retrieves those without a schema;
1997      *        <code>null</code> means that the schema name should not be used to narrow
1998      *        the search
1999      * @param table a table name; must match the table name as it is stored
2000      *        in the database
2001      * @return <code>ResultSet</code> - each row is a primary key column description
2002      * @exception SQLException if a database access error occurs
2003      */
2004     ResultSet getPrimaryKeys(String catalog, String schema,
2005                              String table) throws SQLException;
2006 
2007     /**
2008      * Retrieves a description of the primary key columns that are
2009      * referenced by the given table's foreign key columns (the primary keys
2010      * imported by a table).  They are ordered by PKTABLE_CAT,
2011      * PKTABLE_SCHEM, PKTABLE_NAME, and KEY_SEQ.
2012      *
2013      * <P>Each primary key column description has the following columns:
2014      *  <OL>
2015      *  <LI><B>PKTABLE_CAT</B> String {@code =>} primary key table catalog
2016      *      being imported (may be <code>null</code>)
2017      *  <LI><B>PKTABLE_SCHEM</B> String {@code =>} primary key table schema
2018      *      being imported (may be <code>null</code>)
2019      *  <LI><B>PKTABLE_NAME</B> String {@code =>} primary key table name
2020      *      being imported
2021      *  <LI><B>PKCOLUMN_NAME</B> String {@code =>} primary key column name
2022      *      being imported
2023      *  <LI><B>FKTABLE_CAT</B> String {@code =>} foreign key table catalog (may be <code>null</code>)
2024      *  <LI><B>FKTABLE_SCHEM</B> String {@code =>} foreign key table schema (may be <code>null</code>)
2025      *  <LI><B>FKTABLE_NAME</B> String {@code =>} foreign key table name
2026      *  <LI><B>FKCOLUMN_NAME</B> String {@code =>} foreign key column name
2027      *  <LI><B>KEY_SEQ</B> short {@code =>} sequence number within a foreign key( a value
2028      *  of 1 represents the first column of the foreign key, a value of 2 would
2029      *  represent the second column within the foreign key).
2030      *  <LI><B>UPDATE_RULE</B> short {@code =>} What happens to a
2031      *       foreign key when the primary key is updated:
2032      *      <UL>
2033      *      <LI> importedNoAction - do not allow update of primary
2034      *               key if it has been imported
2035      *      <LI> importedKeyCascade - change imported key to agree
2036      *               with primary key update
2037      *      <LI> importedKeySetNull - change imported key to <code>NULL</code>
2038      *               if its primary key has been updated
2039      *      <LI> importedKeySetDefault - change imported key to default values
2040      *               if its primary key has been updated
2041      *      <LI> importedKeyRestrict - same as importedKeyNoAction
2042      *                                 (for ODBC 2.x compatibility)
2043      *      </UL>
2044      *  <LI><B>DELETE_RULE</B> short {@code =>} What happens to
2045      *      the foreign key when primary is deleted.
2046      *      <UL>
2047      *      <LI> importedKeyNoAction - do not allow delete of primary
2048      *               key if it has been imported
2049      *      <LI> importedKeyCascade - delete rows that import a deleted key
2050      *      <LI> importedKeySetNull - change imported key to NULL if
2051      *               its primary key has been deleted
2052      *      <LI> importedKeyRestrict - same as importedKeyNoAction
2053      *                                 (for ODBC 2.x compatibility)
2054      *      <LI> importedKeySetDefault - change imported key to default if
2055      *               its primary key has been deleted
2056      *      </UL>
2057      *  <LI><B>FK_NAME</B> String {@code =>} foreign key name (may be <code>null</code>)
2058      *  <LI><B>PK_NAME</B> String {@code =>} primary key name (may be <code>null</code>)
2059      *  <LI><B>DEFERRABILITY</B> short {@code =>} can the evaluation of foreign key
2060      *      constraints be deferred until commit
2061      *      <UL>
2062      *      <LI> importedKeyInitiallyDeferred - see SQL92 for definition
2063      *      <LI> importedKeyInitiallyImmediate - see SQL92 for definition
2064      *      <LI> importedKeyNotDeferrable - see SQL92 for definition
2065      *      </UL>
2066      *  </OL>
2067      *
2068      * @param catalog a catalog name; must match the catalog name as it
2069      *        is stored in the database; "" retrieves those without a catalog;
2070      *        <code>null</code> means that the catalog name should not be used to narrow
2071      *        the search
2072      * @param schema a schema name; must match the schema name
2073      *        as it is stored in the database; "" retrieves those without a schema;
2074      *        <code>null</code> means that the schema name should not be used to narrow
2075      *        the search
2076      * @param table a table name; must match the table name as it is stored
2077      *        in the database
2078      * @return <code>ResultSet</code> - each row is a primary key column description
2079      * @exception SQLException if a database access error occurs
2080      * @see #getExportedKeys
2081      */
2082     ResultSet getImportedKeys(String catalog, String schema,
2083                               String table) throws SQLException;
2084 
2085     /**
2086      * For the column <code>UPDATE_RULE</code>,
2087      * indicates that
2088      * when the primary key is updated, the foreign key (imported key)
2089      * is changed to agree with it.
2090      * For the column <code>DELETE_RULE</code>,
2091      * it indicates that
2092      * when the primary key is deleted, rows that imported that key
2093      * are deleted.
2094      * <P>
2095      * A possible value for the columns <code>UPDATE_RULE</code>
2096      * and <code>DELETE_RULE</code> in the
2097      * <code>ResultSet</code> objects returned by the methods
2098      * <code>getImportedKeys</code>,  <code>getExportedKeys</code>,
2099      * and <code>getCrossReference</code>.
2100      */
2101     int importedKeyCascade      = 0;
2102 
2103     /**
2104      * For the column <code>UPDATE_RULE</code>, indicates that
2105      * a primary key may not be updated if it has been imported by
2106      * another table as a foreign key.
2107      * For the column <code>DELETE_RULE</code>, indicates that
2108      * a primary key may not be deleted if it has been imported by
2109      * another table as a foreign key.
2110      * <P>
2111      * A possible value for the columns <code>UPDATE_RULE</code>
2112      * and <code>DELETE_RULE</code> in the
2113      * <code>ResultSet</code> objects returned by the methods
2114      * <code>getImportedKeys</code>,  <code>getExportedKeys</code>,
2115      * and <code>getCrossReference</code>.
2116      */
2117     int importedKeyRestrict = 1;
2118 
2119     /**
2120      * For the columns <code>UPDATE_RULE</code>
2121      * and <code>DELETE_RULE</code>, indicates that
2122      * when the primary key is updated or deleted, the foreign key (imported key)
2123      * is changed to <code>NULL</code>.
2124      * <P>
2125      * A possible value for the columns <code>UPDATE_RULE</code>
2126      * and <code>DELETE_RULE</code> in the
2127      * <code>ResultSet</code> objects returned by the methods
2128      * <code>getImportedKeys</code>,  <code>getExportedKeys</code>,
2129      * and <code>getCrossReference</code>.
2130      */
2131     int importedKeySetNull  = 2;
2132 
2133     /**
2134      * For the columns <code>UPDATE_RULE</code>
2135      * and <code>DELETE_RULE</code>, indicates that
2136      * if the primary key has been imported, it cannot be updated or deleted.
2137      * <P>
2138      * A possible value for the columns <code>UPDATE_RULE</code>
2139      * and <code>DELETE_RULE</code> in the
2140      * <code>ResultSet</code> objects returned by the methods
2141      * <code>getImportedKeys</code>,  <code>getExportedKeys</code>,
2142      * and <code>getCrossReference</code>.
2143      */
2144     int importedKeyNoAction = 3;
2145 
2146     /**
2147      * For the columns <code>UPDATE_RULE</code>
2148      * and <code>DELETE_RULE</code>, indicates that
2149      * if the primary key is updated or deleted, the foreign key (imported key)
2150      * is set to the default value.
2151      * <P>
2152      * A possible value for the columns <code>UPDATE_RULE</code>
2153      * and <code>DELETE_RULE</code> in the
2154      * <code>ResultSet</code> objects returned by the methods
2155      * <code>getImportedKeys</code>,  <code>getExportedKeys</code>,
2156      * and <code>getCrossReference</code>.
2157      */
2158     int importedKeySetDefault  = 4;
2159 
2160     /**
2161      * Indicates deferrability.  See SQL-92 for a definition.
2162      * <P>
2163      * A possible value for the column <code>DEFERRABILITY</code>
2164      * in the <code>ResultSet</code> objects returned by the methods
2165      * <code>getImportedKeys</code>,  <code>getExportedKeys</code>,
2166      * and <code>getCrossReference</code>.
2167      */
2168     int importedKeyInitiallyDeferred  = 5;
2169 
2170     /**
2171      * Indicates deferrability.  See SQL-92 for a definition.
2172      * <P>
2173      * A possible value for the column <code>DEFERRABILITY</code>
2174      * in the <code>ResultSet</code> objects returned by the methods
2175      * <code>getImportedKeys</code>,  <code>getExportedKeys</code>,
2176      * and <code>getCrossReference</code>.
2177      */
2178     int importedKeyInitiallyImmediate  = 6;
2179 
2180     /**
2181      * Indicates deferrability.  See SQL-92 for a definition.
2182      * <P>
2183      * A possible value for the column <code>DEFERRABILITY</code>
2184      * in the <code>ResultSet</code> objects returned by the methods
2185      * <code>getImportedKeys</code>,  <code>getExportedKeys</code>,
2186      * and <code>getCrossReference</code>.
2187      */
2188     int importedKeyNotDeferrable  = 7;
2189 
2190     /**
2191      * Retrieves a description of the foreign key columns that reference the
2192      * given table's primary key columns (the foreign keys exported by a
2193      * table).  They are ordered by FKTABLE_CAT, FKTABLE_SCHEM,
2194      * FKTABLE_NAME, and KEY_SEQ.
2195      *
2196      * <P>Each foreign key column description has the following columns:
2197      *  <OL>
2198      *  <LI><B>PKTABLE_CAT</B> String {@code =>} primary key table catalog (may be <code>null</code>)
2199      *  <LI><B>PKTABLE_SCHEM</B> String {@code =>} primary key table schema (may be <code>null</code>)
2200      *  <LI><B>PKTABLE_NAME</B> String {@code =>} primary key table name
2201      *  <LI><B>PKCOLUMN_NAME</B> String {@code =>} primary key column name
2202      *  <LI><B>FKTABLE_CAT</B> String {@code =>} foreign key table catalog (may be <code>null</code>)
2203      *      being exported (may be <code>null</code>)
2204      *  <LI><B>FKTABLE_SCHEM</B> String {@code =>} foreign key table schema (may be <code>null</code>)
2205      *      being exported (may be <code>null</code>)
2206      *  <LI><B>FKTABLE_NAME</B> String {@code =>} foreign key table name
2207      *      being exported
2208      *  <LI><B>FKCOLUMN_NAME</B> String {@code =>} foreign key column name
2209      *      being exported
2210      *  <LI><B>KEY_SEQ</B> short {@code =>} sequence number within foreign key( a value
2211      *  of 1 represents the first column of the foreign key, a value of 2 would
2212      *  represent the second column within the foreign key).
2213      *  <LI><B>UPDATE_RULE</B> short {@code =>} What happens to
2214      *       foreign key when primary is updated:
2215      *      <UL>
2216      *      <LI> importedNoAction - do not allow update of primary
2217      *               key if it has been imported
2218      *      <LI> importedKeyCascade - change imported key to agree
2219      *               with primary key update
2220      *      <LI> importedKeySetNull - change imported key to <code>NULL</code> if
2221      *               its primary key has been updated
2222      *      <LI> importedKeySetDefault - change imported key to default values
2223      *               if its primary key has been updated
2224      *      <LI> importedKeyRestrict - same as importedKeyNoAction
2225      *                                 (for ODBC 2.x compatibility)
2226      *      </UL>
2227      *  <LI><B>DELETE_RULE</B> short {@code =>} What happens to
2228      *      the foreign key when primary is deleted.
2229      *      <UL>
2230      *      <LI> importedKeyNoAction - do not allow delete of primary
2231      *               key if it has been imported
2232      *      <LI> importedKeyCascade - delete rows that import a deleted key
2233      *      <LI> importedKeySetNull - change imported key to <code>NULL</code> if
2234      *               its primary key has been deleted
2235      *      <LI> importedKeyRestrict - same as importedKeyNoAction
2236      *                                 (for ODBC 2.x compatibility)
2237      *      <LI> importedKeySetDefault - change imported key to default if
2238      *               its primary key has been deleted
2239      *      </UL>
2240      *  <LI><B>FK_NAME</B> String {@code =>} foreign key name (may be <code>null</code>)
2241      *  <LI><B>PK_NAME</B> String {@code =>} primary key name (may be <code>null</code>)
2242      *  <LI><B>DEFERRABILITY</B> short {@code =>} can the evaluation of foreign key
2243      *      constraints be deferred until commit
2244      *      <UL>
2245      *      <LI> importedKeyInitiallyDeferred - see SQL92 for definition
2246      *      <LI> importedKeyInitiallyImmediate - see SQL92 for definition
2247      *      <LI> importedKeyNotDeferrable - see SQL92 for definition
2248      *      </UL>
2249      *  </OL>
2250      *
2251      * @param catalog a catalog name; must match the catalog name as it
2252      *        is stored in this database; "" retrieves those without a catalog;
2253      *        <code>null</code> means that the catalog name should not be used to narrow
2254      *        the search
2255      * @param schema a schema name; must match the schema name
2256      *        as it is stored in the database; "" retrieves those without a schema;
2257      *        <code>null</code> means that the schema name should not be used to narrow
2258      *        the search
2259      * @param table a table name; must match the table name as it is stored
2260      *        in this database
2261      * @return a <code>ResultSet</code> object in which each row is a
2262      *         foreign key column description
2263      * @exception SQLException if a database access error occurs
2264      * @see #getImportedKeys
2265      */
2266     ResultSet getExportedKeys(String catalog, String schema,
2267                               String table) throws SQLException;
2268 
2269     /**
2270      * Retrieves a description of the foreign key columns in the given foreign key
2271      * table that reference the primary key or the columns representing a unique constraint of the  parent table (could be the same or a different table).
2272      * The number of columns returned from the parent table must match the number of
2273      * columns that make up the foreign key.  They
2274      * are ordered by FKTABLE_CAT, FKTABLE_SCHEM, FKTABLE_NAME, and
2275      * KEY_SEQ.
2276      *
2277      * <P>Each foreign key column description has the following columns:
2278      *  <OL>
2279      *  <LI><B>PKTABLE_CAT</B> String {@code =>} parent key table catalog (may be <code>null</code>)
2280      *  <LI><B>PKTABLE_SCHEM</B> String {@code =>} parent key table schema (may be <code>null</code>)
2281      *  <LI><B>PKTABLE_NAME</B> String {@code =>} parent key table name
2282      *  <LI><B>PKCOLUMN_NAME</B> String {@code =>} parent key column name
2283      *  <LI><B>FKTABLE_CAT</B> String {@code =>} foreign key table catalog (may be <code>null</code>)
2284      *      being exported (may be <code>null</code>)
2285      *  <LI><B>FKTABLE_SCHEM</B> String {@code =>} foreign key table schema (may be <code>null</code>)
2286      *      being exported (may be <code>null</code>)
2287      *  <LI><B>FKTABLE_NAME</B> String {@code =>} foreign key table name
2288      *      being exported
2289      *  <LI><B>FKCOLUMN_NAME</B> String {@code =>} foreign key column name
2290      *      being exported
2291      *  <LI><B>KEY_SEQ</B> short {@code =>} sequence number within foreign key( a value
2292      *  of 1 represents the first column of the foreign key, a value of 2 would
2293      *  represent the second column within the foreign key).
2294      *  <LI><B>UPDATE_RULE</B> short {@code =>} What happens to
2295      *       foreign key when parent key is updated:
2296      *      <UL>
2297      *      <LI> importedNoAction - do not allow update of parent
2298      *               key if it has been imported
2299      *      <LI> importedKeyCascade - change imported key to agree
2300      *               with parent key update
2301      *      <LI> importedKeySetNull - change imported key to <code>NULL</code> if
2302      *               its parent key has been updated
2303      *      <LI> importedKeySetDefault - change imported key to default values
2304      *               if its parent key has been updated
2305      *      <LI> importedKeyRestrict - same as importedKeyNoAction
2306      *                                 (for ODBC 2.x compatibility)
2307      *      </UL>
2308      *  <LI><B>DELETE_RULE</B> short {@code =>} What happens to
2309      *      the foreign key when parent key is deleted.
2310      *      <UL>
2311      *      <LI> importedKeyNoAction - do not allow delete of parent
2312      *               key if it has been imported
2313      *      <LI> importedKeyCascade - delete rows that import a deleted key
2314      *      <LI> importedKeySetNull - change imported key to <code>NULL</code> if
2315      *               its primary key has been deleted
2316      *      <LI> importedKeyRestrict - same as importedKeyNoAction
2317      *                                 (for ODBC 2.x compatibility)
2318      *      <LI> importedKeySetDefault - change imported key to default if
2319      *               its parent key has been deleted
2320      *      </UL>
2321      *  <LI><B>FK_NAME</B> String {@code =>} foreign key name (may be <code>null</code>)
2322      *  <LI><B>PK_NAME</B> String {@code =>} parent key name (may be <code>null</code>)
2323      *  <LI><B>DEFERRABILITY</B> short {@code =>} can the evaluation of foreign key
2324      *      constraints be deferred until commit
2325      *      <UL>
2326      *      <LI> importedKeyInitiallyDeferred - see SQL92 for definition
2327      *      <LI> importedKeyInitiallyImmediate - see SQL92 for definition
2328      *      <LI> importedKeyNotDeferrable - see SQL92 for definition
2329      *      </UL>
2330      *  </OL>
2331      *
2332      * @param parentCatalog a catalog name; must match the catalog name
2333      * as it is stored in the database; "" retrieves those without a
2334      * catalog; <code>null</code> means drop catalog name from the selection criteria
2335      * @param parentSchema a schema name; must match the schema name as
2336      * it is stored in the database; "" retrieves those without a schema;
2337      * <code>null</code> means drop schema name from the selection criteria
2338      * @param parentTable the name of the table that exports the key; must match
2339      * the table name as it is stored in the database
2340      * @param foreignCatalog a catalog name; must match the catalog name as
2341      * it is stored in the database; "" retrieves those without a
2342      * catalog; <code>null</code> means drop catalog name from the selection criteria
2343      * @param foreignSchema a schema name; must match the schema name as it
2344      * is stored in the database; "" retrieves those without a schema;
2345      * <code>null</code> means drop schema name from the selection criteria
2346      * @param foreignTable the name of the table that imports the key; must match
2347      * the table name as it is stored in the database
2348      * @return <code>ResultSet</code> - each row is a foreign key column description
2349      * @exception SQLException if a database access error occurs
2350      * @see #getImportedKeys
2351      */
2352     ResultSet getCrossReference(
2353                                 String parentCatalog, String parentSchema, String parentTable,
2354                                 String foreignCatalog, String foreignSchema, String foreignTable
2355                                 ) throws SQLException;
2356 
2357     /**
2358      * Retrieves a description of all the data types supported by
2359      * this database. They are ordered by DATA_TYPE and then by how
2360      * closely the data type maps to the corresponding JDBC SQL type.
2361      *
2362      * <P>If the database supports SQL distinct types, then getTypeInfo() will return
2363      * a single row with a TYPE_NAME of DISTINCT and a DATA_TYPE of Types.DISTINCT.
2364      * If the database supports SQL structured types, then getTypeInfo() will return
2365      * a single row with a TYPE_NAME of STRUCT and a DATA_TYPE of Types.STRUCT.
2366      *
2367      * <P>If SQL distinct or structured types are supported, then information on the
2368      * individual types may be obtained from the getUDTs() method.
2369      *
2370 
2371      *
2372      * <P>Each type description has the following columns:
2373      *  <OL>
2374      *  <LI><B>TYPE_NAME</B> String {@code =>} Type name
2375      *  <LI><B>DATA_TYPE</B> int {@code =>} SQL data type from java.sql.Types
2376      *  <LI><B>PRECISION</B> int {@code =>} maximum precision
2377      *  <LI><B>LITERAL_PREFIX</B> String {@code =>} prefix used to quote a literal
2378      *      (may be <code>null</code>)
2379      *  <LI><B>LITERAL_SUFFIX</B> String {@code =>} suffix used to quote a literal
2380      (may be <code>null</code>)
2381      *  <LI><B>CREATE_PARAMS</B> String {@code =>} parameters used in creating
2382      *      the type (may be <code>null</code>)
2383      *  <LI><B>NULLABLE</B> short {@code =>} can you use NULL for this type.
2384      *      <UL>
2385      *      <LI> typeNoNulls - does not allow NULL values
2386      *      <LI> typeNullable - allows NULL values
2387      *      <LI> typeNullableUnknown - nullability unknown
2388      *      </UL>
2389      *  <LI><B>CASE_SENSITIVE</B> boolean{@code =>} is it case sensitive.
2390      *  <LI><B>SEARCHABLE</B> short {@code =>} can you use "WHERE" based on this type:
2391      *      <UL>
2392      *      <LI> typePredNone - No support
2393      *      <LI> typePredChar - Only supported with WHERE .. LIKE
2394      *      <LI> typePredBasic - Supported except for WHERE .. LIKE
2395      *      <LI> typeSearchable - Supported for all WHERE ..
2396      *      </UL>
2397      *  <LI><B>UNSIGNED_ATTRIBUTE</B> boolean {@code =>} is it unsigned.
2398      *  <LI><B>FIXED_PREC_SCALE</B> boolean {@code =>} can it be a money value.
2399      *  <LI><B>AUTO_INCREMENT</B> boolean {@code =>} can it be used for an
2400      *      auto-increment value.
2401      *  <LI><B>LOCAL_TYPE_NAME</B> String {@code =>} localized version of type name
2402      *      (may be <code>null</code>)
2403      *  <LI><B>MINIMUM_SCALE</B> short {@code =>} minimum scale supported
2404      *  <LI><B>MAXIMUM_SCALE</B> short {@code =>} maximum scale supported
2405      *  <LI><B>SQL_DATA_TYPE</B> int {@code =>} unused
2406      *  <LI><B>SQL_DATETIME_SUB</B> int {@code =>} unused
2407      *  <LI><B>NUM_PREC_RADIX</B> int {@code =>} usually 2 or 10
2408      *  </OL>
2409      *
2410      * <p>The PRECISION column represents the maximum column size that the server supports for the given datatype.
2411      * For numeric data, this is the maximum precision.  For character data, this is the length in characters.
2412      * For datetime datatypes, this is the length in characters of the String representation (assuming the
2413      * maximum allowed precision of the fractional seconds component). For binary data, this is the length in bytes.  For the ROWID datatype,
2414      * this is the length in bytes. Null is returned for data types where the
2415      * column size is not applicable.
2416      *
2417      * @return a <code>ResultSet</code> object in which each row is an SQL
2418      *         type description
2419      * @exception SQLException if a database access error occurs
2420      */
2421     ResultSet getTypeInfo() throws SQLException;
2422 
2423     /**
2424      * Indicates that a <code>NULL</code> value is NOT allowed for this
2425      * data type.
2426      * <P>
2427      * A possible value for column <code>NULLABLE</code> in the
2428      * <code>ResultSet</code> object returned by the method
2429      * <code>getTypeInfo</code>.
2430      */
2431     int typeNoNulls = 0;
2432 
2433     /**
2434      * Indicates that a <code>NULL</code> value is allowed for this
2435      * data type.
2436      * <P>
2437      * A possible value for column <code>NULLABLE</code> in the
2438      * <code>ResultSet</code> object returned by the method
2439      * <code>getTypeInfo</code>.
2440      */
2441     int typeNullable = 1;
2442 
2443     /**
2444      * Indicates that it is not known whether a <code>NULL</code> value
2445      * is allowed for this data type.
2446      * <P>
2447      * A possible value for column <code>NULLABLE</code> in the
2448      * <code>ResultSet</code> object returned by the method
2449      * <code>getTypeInfo</code>.
2450      */
2451     int typeNullableUnknown = 2;
2452 
2453     /**
2454      * Indicates that <code>WHERE</code> search clauses are not supported
2455      * for this type.
2456      * <P>
2457      * A possible value for column <code>SEARCHABLE</code> in the
2458      * <code>ResultSet</code> object returned by the method
2459      * <code>getTypeInfo</code>.
2460      */
2461     int typePredNone = 0;
2462 
2463     /**
2464      * Indicates that the data type
2465      * can be only be used in <code>WHERE</code> search clauses
2466      * that  use <code>LIKE</code> predicates.
2467      * <P>
2468      * A possible value for column <code>SEARCHABLE</code> in the
2469      * <code>ResultSet</code> object returned by the method
2470      * <code>getTypeInfo</code>.
2471      */
2472     int typePredChar = 1;
2473 
2474     /**
2475      * Indicates that the data type can be only be used in <code>WHERE</code>
2476      * search clauses
2477      * that do not use <code>LIKE</code> predicates.
2478      * <P>
2479      * A possible value for column <code>SEARCHABLE</code> in the
2480      * <code>ResultSet</code> object returned by the method
2481      * <code>getTypeInfo</code>.
2482      */
2483     int typePredBasic = 2;
2484 
2485     /**
2486      * Indicates that all <code>WHERE</code> search clauses can be
2487      * based on this type.
2488      * <P>
2489      * A possible value for column <code>SEARCHABLE</code> in the
2490      * <code>ResultSet</code> object returned by the method
2491      * <code>getTypeInfo</code>.
2492      */
2493     int typeSearchable  = 3;
2494 
2495     /**
2496      * Retrieves a description of the given table's indices and statistics. They are
2497      * ordered by NON_UNIQUE, TYPE, INDEX_NAME, and ORDINAL_POSITION.
2498      *
2499      * <P>Each index column description has the following columns:
2500      *  <OL>
2501      *  <LI><B>TABLE_CAT</B> String {@code =>} table catalog (may be <code>null</code>)
2502      *  <LI><B>TABLE_SCHEM</B> String {@code =>} table schema (may be <code>null</code>)
2503      *  <LI><B>TABLE_NAME</B> String {@code =>} table name
2504      *  <LI><B>NON_UNIQUE</B> boolean {@code =>} Can index values be non-unique.
2505      *      false when TYPE is tableIndexStatistic
2506      *  <LI><B>INDEX_QUALIFIER</B> String {@code =>} index catalog (may be <code>null</code>);
2507      *      <code>null</code> when TYPE is tableIndexStatistic
2508      *  <LI><B>INDEX_NAME</B> String {@code =>} index name; <code>null</code> when TYPE is
2509      *      tableIndexStatistic
2510      *  <LI><B>TYPE</B> short {@code =>} index type:
2511      *      <UL>
2512      *      <LI> tableIndexStatistic - this identifies table statistics that are
2513      *           returned in conjuction with a table's index descriptions
2514      *      <LI> tableIndexClustered - this is a clustered index
2515      *      <LI> tableIndexHashed - this is a hashed index
2516      *      <LI> tableIndexOther - this is some other style of index
2517      *      </UL>
2518      *  <LI><B>ORDINAL_POSITION</B> short {@code =>} column sequence number
2519      *      within index; zero when TYPE is tableIndexStatistic
2520      *  <LI><B>COLUMN_NAME</B> String {@code =>} column name; <code>null</code> when TYPE is
2521      *      tableIndexStatistic
2522      *  <LI><B>ASC_OR_DESC</B> String {@code =>} column sort sequence, "A" {@code =>} ascending,
2523      *      "D" {@code =>} descending, may be <code>null</code> if sort sequence is not supported;
2524      *      <code>null</code> when TYPE is tableIndexStatistic
2525      *  <LI><B>CARDINALITY</B> long {@code =>} When TYPE is tableIndexStatistic, then
2526      *      this is the number of rows in the table; otherwise, it is the
2527      *      number of unique values in the index.
2528      *  <LI><B>PAGES</B> long {@code =>} When TYPE is  tableIndexStatisic then
2529      *      this is the number of pages used for the table, otherwise it
2530      *      is the number of pages used for the current index.
2531      *  <LI><B>FILTER_CONDITION</B> String {@code =>} Filter condition, if any.
2532      *      (may be <code>null</code>)
2533      *  </OL>
2534      *
2535      * @param catalog a catalog name; must match the catalog name as it
2536      *        is stored in this database; "" retrieves those without a catalog;
2537      *        <code>null</code> means that the catalog name should not be used to narrow
2538      *        the search
2539      * @param schema a schema name; must match the schema name
2540      *        as it is stored in this database; "" retrieves those without a schema;
2541      *        <code>null</code> means that the schema name should not be used to narrow
2542      *        the search
2543      * @param table a table name; must match the table name as it is stored
2544      *        in this database
2545      * @param unique when true, return only indices for unique values;
2546      *     when false, return indices regardless of whether unique or not
2547      * @param approximate when true, result is allowed to reflect approximate
2548      *     or out of data values; when false, results are requested to be
2549      *     accurate
2550      * @return <code>ResultSet</code> - each row is an index column description
2551      * @exception SQLException if a database access error occurs
2552      */
2553     ResultSet getIndexInfo(String catalog, String schema, String table,
2554                            boolean unique, boolean approximate)
2555         throws SQLException;
2556 
2557     /**
2558      * Indicates that this column contains table statistics that
2559      * are returned in conjunction with a table's index descriptions.
2560      * <P>
2561      * A possible value for column <code>TYPE</code> in the
2562      * <code>ResultSet</code> object returned by the method
2563      * <code>getIndexInfo</code>.
2564      */
2565     short tableIndexStatistic = 0;
2566 
2567     /**
2568      * Indicates that this table index is a clustered index.
2569      * <P>
2570      * A possible value for column <code>TYPE</code> in the
2571      * <code>ResultSet</code> object returned by the method
2572      * <code>getIndexInfo</code>.
2573      */
2574     short tableIndexClustered = 1;
2575 
2576     /**
2577      * Indicates that this table index is a hashed index.
2578      * <P>
2579      * A possible value for column <code>TYPE</code> in the
2580      * <code>ResultSet</code> object returned by the method
2581      * <code>getIndexInfo</code>.
2582      */
2583     short tableIndexHashed    = 2;
2584 
2585     /**
2586      * Indicates that this table index is not a clustered
2587      * index, a hashed index, or table statistics;
2588      * it is something other than these.
2589      * <P>
2590      * A possible value for column <code>TYPE</code> in the
2591      * <code>ResultSet</code> object returned by the method
2592      * <code>getIndexInfo</code>.
2593      */
2594     short tableIndexOther     = 3;
2595 
2596     //--------------------------JDBC 2.0-----------------------------
2597 
2598     /**
2599      * Retrieves whether this database supports the given result set type.
2600      *
2601      * @param type defined in <code>java.sql.ResultSet</code>
2602      * @return <code>true</code> if so; <code>false</code> otherwise
2603      * @exception SQLException if a database access error occurs
2604      * @see Connection
2605      * @since 1.2
2606      */
2607     boolean supportsResultSetType(int type) throws SQLException;
2608 
2609     /**
2610      * Retrieves whether this database supports the given concurrency type
2611      * in combination with the given result set type.
2612      *
2613      * @param type defined in <code>java.sql.ResultSet</code>
2614      * @param concurrency type defined in <code>java.sql.ResultSet</code>
2615      * @return <code>true</code> if so; <code>false</code> otherwise
2616      * @exception SQLException if a database access error occurs
2617      * @see Connection
2618      * @since 1.2
2619      */
2620     boolean supportsResultSetConcurrency(int type, int concurrency)
2621         throws SQLException;
2622 
2623     /**
2624      *
2625      * Retrieves whether for the given type of <code>ResultSet</code> object,
2626      * the result set's own updates are visible.
2627      *
2628      * @param type the <code>ResultSet</code> type; one of
2629      *        <code>ResultSet.TYPE_FORWARD_ONLY</code>,
2630      *        <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
2631      *        <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
2632      * @return <code>true</code> if updates are visible for the given result set type;
2633      *        <code>false</code> otherwise
2634      * @exception SQLException if a database access error occurs
2635      * @since 1.2
2636      */
2637     boolean ownUpdatesAreVisible(int type) throws SQLException;
2638 
2639     /**
2640      * Retrieves whether a result set's own deletes are visible.
2641      *
2642      * @param type the <code>ResultSet</code> type; one of
2643      *        <code>ResultSet.TYPE_FORWARD_ONLY</code>,
2644      *        <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
2645      *        <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
2646      * @return <code>true</code> if deletes are visible for the given result set type;
2647      *        <code>false</code> otherwise
2648      * @exception SQLException if a database access error occurs
2649      * @since 1.2
2650      */
2651     boolean ownDeletesAreVisible(int type) throws SQLException;
2652 
2653     /**
2654      * Retrieves whether a result set's own inserts are visible.
2655      *
2656      * @param type the <code>ResultSet</code> type; one of
2657      *        <code>ResultSet.TYPE_FORWARD_ONLY</code>,
2658      *        <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
2659      *        <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
2660      * @return <code>true</code> if inserts are visible for the given result set type;
2661      *        <code>false</code> otherwise
2662      * @exception SQLException if a database access error occurs
2663      * @since 1.2
2664      */
2665     boolean ownInsertsAreVisible(int type) throws SQLException;
2666 
2667     /**
2668      * Retrieves whether updates made by others are visible.
2669      *
2670      * @param type the <code>ResultSet</code> type; one of
2671      *        <code>ResultSet.TYPE_FORWARD_ONLY</code>,
2672      *        <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
2673      *        <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
2674      * @return <code>true</code> if updates made by others
2675      *        are visible for the given result set type;
2676      *        <code>false</code> otherwise
2677      * @exception SQLException if a database access error occurs
2678      * @since 1.2
2679      */
2680     boolean othersUpdatesAreVisible(int type) throws SQLException;
2681 
2682     /**
2683      * Retrieves whether deletes made by others are visible.
2684      *
2685      * @param type the <code>ResultSet</code> type; one of
2686      *        <code>ResultSet.TYPE_FORWARD_ONLY</code>,
2687      *        <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
2688      *        <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
2689      * @return <code>true</code> if deletes made by others
2690      *        are visible for the given result set type;
2691      *        <code>false</code> otherwise
2692      * @exception SQLException if a database access error occurs
2693      * @since 1.2
2694      */
2695     boolean othersDeletesAreVisible(int type) throws SQLException;
2696 
2697     /**
2698      * Retrieves whether inserts made by others are visible.
2699      *
2700      * @param type the <code>ResultSet</code> type; one of
2701      *        <code>ResultSet.TYPE_FORWARD_ONLY</code>,
2702      *        <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
2703      *        <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
2704      * @return <code>true</code> if inserts made by others
2705      *         are visible for the given result set type;
2706      *         <code>false</code> otherwise
2707      * @exception SQLException if a database access error occurs
2708      * @since 1.2
2709      */
2710     boolean othersInsertsAreVisible(int type) throws SQLException;
2711 
2712     /**
2713      * Retrieves whether or not a visible row update can be detected by
2714      * calling the method <code>ResultSet.rowUpdated</code>.
2715      *
2716      * @param type the <code>ResultSet</code> type; one of
2717      *        <code>ResultSet.TYPE_FORWARD_ONLY</code>,
2718      *        <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
2719      *        <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
2720      * @return <code>true</code> if changes are detected by the result set type;
2721      *         <code>false</code> otherwise
2722      * @exception SQLException if a database access error occurs
2723      * @since 1.2
2724      */
2725     boolean updatesAreDetected(int type) throws SQLException;
2726 
2727     /**
2728      * Retrieves whether or not a visible row delete can be detected by
2729      * calling the method <code>ResultSet.rowDeleted</code>.  If the method
2730      * <code>deletesAreDetected</code> returns <code>false</code>, it means that
2731      * deleted rows are removed from the result set.
2732      *
2733      * @param type the <code>ResultSet</code> type; one of
2734      *        <code>ResultSet.TYPE_FORWARD_ONLY</code>,
2735      *        <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
2736      *        <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
2737      * @return <code>true</code> if deletes are detected by the given result set type;
2738      *         <code>false</code> otherwise
2739      * @exception SQLException if a database access error occurs
2740      * @since 1.2
2741      */
2742     boolean deletesAreDetected(int type) throws SQLException;
2743 
2744     /**
2745      * Retrieves whether or not a visible row insert can be detected
2746      * by calling the method <code>ResultSet.rowInserted</code>.
2747      *
2748      * @param type the <code>ResultSet</code> type; one of
2749      *        <code>ResultSet.TYPE_FORWARD_ONLY</code>,
2750      *        <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
2751      *        <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
2752      * @return <code>true</code> if changes are detected by the specified result
2753      *         set type; <code>false</code> otherwise
2754      * @exception SQLException if a database access error occurs
2755      * @since 1.2
2756      */
2757     boolean insertsAreDetected(int type) throws SQLException;
2758 
2759     /**
2760      * Retrieves whether this database supports batch updates.
2761      *
2762      * @return <code>true</code> if this database supports batch updates;
2763      *         <code>false</code> otherwise
2764      * @exception SQLException if a database access error occurs
2765      * @since 1.2
2766      */
2767     boolean supportsBatchUpdates() throws SQLException;
2768 
2769     /**
2770      * Retrieves a description of the user-defined types (UDTs) defined
2771      * in a particular schema.  Schema-specific UDTs may have type
2772      * <code>JAVA_OBJECT</code>, <code>STRUCT</code>,
2773      * or <code>DISTINCT</code>.
2774      *
2775      * <P>Only types matching the catalog, schema, type name and type
2776      * criteria are returned.  They are ordered by <code>DATA_TYPE</code>,
2777      * <code>TYPE_CAT</code>, <code>TYPE_SCHEM</code>  and
2778      * <code>TYPE_NAME</code>.  The type name parameter may be a fully-qualified
2779      * name.  In this case, the catalog and schemaPattern parameters are
2780      * ignored.
2781      *
2782      * <P>Each type description has the following columns:
2783      *  <OL>
2784      *  <LI><B>TYPE_CAT</B> String {@code =>} the type's catalog (may be <code>null</code>)
2785      *  <LI><B>TYPE_SCHEM</B> String {@code =>} type's schema (may be <code>null</code>)
2786      *  <LI><B>TYPE_NAME</B> String {@code =>} type name
2787      *  <LI><B>CLASS_NAME</B> String {@code =>} Java class name
2788      *  <LI><B>DATA_TYPE</B> int {@code =>} type value defined in java.sql.Types.
2789      *     One of JAVA_OBJECT, STRUCT, or DISTINCT
2790      *  <LI><B>REMARKS</B> String {@code =>} explanatory comment on the type
2791      *  <LI><B>BASE_TYPE</B> short {@code =>} type code of the source type of a
2792      *     DISTINCT type or the type that implements the user-generated
2793      *     reference type of the SELF_REFERENCING_COLUMN of a structured
2794      *     type as defined in java.sql.Types (<code>null</code> if DATA_TYPE is not
2795      *     DISTINCT or not STRUCT with REFERENCE_GENERATION = USER_DEFINED)
2796      *  </OL>
2797      *
2798      * <P><B>Note:</B> If the driver does not support UDTs, an empty
2799      * result set is returned.
2800      *
2801      * @param catalog a catalog name; must match the catalog name as it
2802      *        is stored in the database; "" retrieves those without a catalog;
2803      *        <code>null</code> means that the catalog name should not be used to narrow
2804      *        the search
2805      * @param schemaPattern a schema pattern name; must match the schema name
2806      *        as it is stored in the database; "" retrieves those without a schema;
2807      *        <code>null</code> means that the schema name should not be used to narrow
2808      *        the search
2809      * @param typeNamePattern a type name pattern; must match the type name
2810      *        as it is stored in the database; may be a fully qualified name
2811      * @param types a list of user-defined types (JAVA_OBJECT,
2812      *        STRUCT, or DISTINCT) to include; <code>null</code> returns all types
2813      * @return <code>ResultSet</code> object in which each row describes a UDT
2814      * @exception SQLException if a database access error occurs
2815      * @see #getSearchStringEscape
2816      * @since 1.2
2817      */
2818     ResultSet getUDTs(String catalog, String schemaPattern,
2819                       String typeNamePattern, int[] types)
2820         throws SQLException;
2821 
2822     /**
2823      * Retrieves the connection that produced this metadata object.
2824      * <P>
2825      * @return the connection that produced this metadata object
2826      * @exception SQLException if a database access error occurs
2827      * @since 1.2
2828      */
2829     Connection getConnection() throws SQLException;
2830 
2831     // ------------------- JDBC 3.0 -------------------------
2832 
2833     /**
2834      * Retrieves whether this database supports savepoints.
2835      *
2836      * @return <code>true</code> if savepoints are supported;
2837      *         <code>false</code> otherwise
2838      * @exception SQLException if a database access error occurs
2839      * @since 1.4
2840      */
2841     boolean supportsSavepoints() throws SQLException;
2842 
2843     /**
2844      * Retrieves whether this database supports named parameters to callable
2845      * statements.
2846      *
2847      * @return <code>true</code> if named parameters are supported;
2848      *         <code>false</code> otherwise
2849      * @exception SQLException if a database access error occurs
2850      * @since 1.4
2851      */
2852     boolean supportsNamedParameters() throws SQLException;
2853 
2854     /**
2855      * Retrieves whether it is possible to have multiple <code>ResultSet</code> objects
2856      * returned from a <code>CallableStatement</code> object
2857      * simultaneously.
2858      *
2859      * @return <code>true</code> if a <code>CallableStatement</code> object
2860      *         can return multiple <code>ResultSet</code> objects
2861      *         simultaneously; <code>false</code> otherwise
2862      * @exception SQLException if a datanase access error occurs
2863      * @since 1.4
2864      */
2865     boolean supportsMultipleOpenResults() throws SQLException;
2866 
2867     /**
2868      * Retrieves whether auto-generated keys can be retrieved after
2869      * a statement has been executed
2870      *
2871      * @return <code>true</code> if auto-generated keys can be retrieved
2872      *         after a statement has executed; <code>false</code> otherwise
2873      *<p>If <code>true</code> is returned, the JDBC driver must support the
2874      * returning of auto-generated keys for at least SQL INSERT statements
2875      *<p>
2876      * @exception SQLException if a database access error occurs
2877      * @since 1.4
2878      */
2879     boolean supportsGetGeneratedKeys() throws SQLException;
2880 
2881     /**
2882      * Retrieves a description of the user-defined type (UDT) hierarchies defined in a
2883      * particular schema in this database. Only the immediate super type/
2884      * sub type relationship is modeled.
2885      * <P>
2886      * Only supertype information for UDTs matching the catalog,
2887      * schema, and type name is returned. The type name parameter
2888      * may be a fully-qualified name. When the UDT name supplied is a
2889      * fully-qualified name, the catalog and schemaPattern parameters are
2890      * ignored.
2891      * <P>
2892      * If a UDT does not have a direct super type, it is not listed here.
2893      * A row of the <code>ResultSet</code> object returned by this method
2894      * describes the designated UDT and a direct supertype. A row has the following
2895      * columns:
2896      *  <OL>
2897      *  <LI><B>TYPE_CAT</B> String {@code =>} the UDT's catalog (may be <code>null</code>)
2898      *  <LI><B>TYPE_SCHEM</B> String {@code =>} UDT's schema (may be <code>null</code>)
2899      *  <LI><B>TYPE_NAME</B> String {@code =>} type name of the UDT
2900      *  <LI><B>SUPERTYPE_CAT</B> String {@code =>} the direct super type's catalog
2901      *                           (may be <code>null</code>)
2902      *  <LI><B>SUPERTYPE_SCHEM</B> String {@code =>} the direct super type's schema
2903      *                             (may be <code>null</code>)
2904      *  <LI><B>SUPERTYPE_NAME</B> String {@code =>} the direct super type's name
2905      *  </OL>
2906      *
2907      * <P><B>Note:</B> If the driver does not support type hierarchies, an
2908      * empty result set is returned.
2909      *
2910      * @param catalog a catalog name; "" retrieves those without a catalog;
2911      *        <code>null</code> means drop catalog name from the selection criteria
2912      * @param schemaPattern a schema name pattern; "" retrieves those
2913      *        without a schema
2914      * @param typeNamePattern a UDT name pattern; may be a fully-qualified
2915      *        name
2916      * @return a <code>ResultSet</code> object in which a row gives information
2917      *         about the designated UDT
2918      * @throws SQLException if a database access error occurs
2919      * @see #getSearchStringEscape
2920      * @since 1.4
2921      */
2922     ResultSet getSuperTypes(String catalog, String schemaPattern,
2923                             String typeNamePattern) throws SQLException;
2924 
2925     /**
2926      * Retrieves a description of the table hierarchies defined in a particular
2927      * schema in this database.
2928      *
2929      * <P>Only supertable information for tables matching the catalog, schema
2930      * and table name are returned. The table name parameter may be a fully-
2931      * qualified name, in which case, the catalog and schemaPattern parameters
2932      * are ignored. If a table does not have a super table, it is not listed here.
2933      * Supertables have to be defined in the same catalog and schema as the
2934      * sub tables. Therefore, the type description does not need to include
2935      * this information for the supertable.
2936      *
2937      * <P>Each type description has the following columns:
2938      *  <OL>
2939      *  <LI><B>TABLE_CAT</B> String {@code =>} the type's catalog (may be <code>null</code>)
2940      *  <LI><B>TABLE_SCHEM</B> String {@code =>} type's schema (may be <code>null</code>)
2941      *  <LI><B>TABLE_NAME</B> String {@code =>} type name
2942      *  <LI><B>SUPERTABLE_NAME</B> String {@code =>} the direct super type's name
2943      *  </OL>
2944      *
2945      * <P><B>Note:</B> If the driver does not support type hierarchies, an
2946      * empty result set is returned.
2947      *
2948      * @param catalog a catalog name; "" retrieves those without a catalog;
2949      *        <code>null</code> means drop catalog name from the selection criteria
2950      * @param schemaPattern a schema name pattern; "" retrieves those
2951      *        without a schema
2952      * @param tableNamePattern a table name pattern; may be a fully-qualified
2953      *        name
2954      * @return a <code>ResultSet</code> object in which each row is a type description
2955      * @throws SQLException if a database access error occurs
2956      * @see #getSearchStringEscape
2957      * @since 1.4
2958      */
2959     ResultSet getSuperTables(String catalog, String schemaPattern,
2960                              String tableNamePattern) throws SQLException;
2961 
2962     /**
2963      * Indicates that <code>NULL</code> values might not be allowed.
2964      * <P>
2965      * A possible value for the column
2966      * <code>NULLABLE</code> in the <code>ResultSet</code> object
2967      * returned by the method <code>getAttributes</code>.
2968      */
2969     short attributeNoNulls = 0;
2970 
2971     /**
2972      * Indicates that <code>NULL</code> values are definitely allowed.
2973      * <P>
2974      * A possible value for the column <code>NULLABLE</code>
2975      * in the <code>ResultSet</code> object
2976      * returned by the method <code>getAttributes</code>.
2977      */
2978     short attributeNullable = 1;
2979 
2980     /**
2981      * Indicates that whether <code>NULL</code> values are allowed is not
2982      * known.
2983      * <P>
2984      * A possible value for the column <code>NULLABLE</code>
2985      * in the <code>ResultSet</code> object
2986      * returned by the method <code>getAttributes</code>.
2987      */
2988     short attributeNullableUnknown = 2;
2989 
2990     /**
2991      * Retrieves a description of the given attribute of the given type
2992      * for a user-defined type (UDT) that is available in the given schema
2993      * and catalog.
2994      * <P>
2995      * Descriptions are returned only for attributes of UDTs matching the
2996      * catalog, schema, type, and attribute name criteria. They are ordered by
2997      * <code>TYPE_CAT</code>, <code>TYPE_SCHEM</code>,
2998      * <code>TYPE_NAME</code> and <code>ORDINAL_POSITION</code>. This description
2999      * does not contain inherited attributes.
3000      * <P>
3001      * The <code>ResultSet</code> object that is returned has the following
3002      * columns:
3003      * <OL>
3004      *  <LI><B>TYPE_CAT</B> String {@code =>} type catalog (may be <code>null</code>)
3005      *  <LI><B>TYPE_SCHEM</B> String {@code =>} type schema (may be <code>null</code>)
3006      *  <LI><B>TYPE_NAME</B> String {@code =>} type name
3007      *  <LI><B>ATTR_NAME</B> String {@code =>} attribute name
3008      *  <LI><B>DATA_TYPE</B> int {@code =>} attribute type SQL type from java.sql.Types
3009      *  <LI><B>ATTR_TYPE_NAME</B> String {@code =>} Data source dependent type name.
3010      *  For a UDT, the type name is fully qualified. For a REF, the type name is
3011      *  fully qualified and represents the target type of the reference type.
3012      *  <LI><B>ATTR_SIZE</B> int {@code =>} column size.  For char or date
3013      *      types this is the maximum number of characters; for numeric or
3014      *      decimal types this is precision.
3015      *  <LI><B>DECIMAL_DIGITS</B> int {@code =>} the number of fractional digits. Null is returned for data types where
3016      * DECIMAL_DIGITS is not applicable.
3017      *  <LI><B>NUM_PREC_RADIX</B> int {@code =>} Radix (typically either 10 or 2)
3018      *  <LI><B>NULLABLE</B> int {@code =>} whether NULL is allowed
3019      *      <UL>
3020      *      <LI> attributeNoNulls - might not allow NULL values
3021      *      <LI> attributeNullable - definitely allows NULL values
3022      *      <LI> attributeNullableUnknown - nullability unknown
3023      *      </UL>
3024      *  <LI><B>REMARKS</B> String {@code =>} comment describing column (may be <code>null</code>)
3025      *  <LI><B>ATTR_DEF</B> String {@code =>} default value (may be <code>null</code>)
3026      *  <LI><B>SQL_DATA_TYPE</B> int {@code =>} unused
3027      *  <LI><B>SQL_DATETIME_SUB</B> int {@code =>} unused
3028      *  <LI><B>CHAR_OCTET_LENGTH</B> int {@code =>} for char types the
3029      *       maximum number of bytes in the column
3030      *  <LI><B>ORDINAL_POSITION</B> int {@code =>} index of the attribute in the UDT
3031      *      (starting at 1)
3032      *  <LI><B>IS_NULLABLE</B> String  {@code =>} ISO rules are used to determine
3033      * the nullability for a attribute.
3034      *       <UL>
3035      *       <LI> YES           --- if the attribute can include NULLs
3036      *       <LI> NO            --- if the attribute cannot include NULLs
3037      *       <LI> empty string  --- if the nullability for the
3038      * attribute is unknown
3039      *       </UL>
3040      *  <LI><B>SCOPE_CATALOG</B> String {@code =>} catalog of table that is the
3041      *      scope of a reference attribute (<code>null</code> if DATA_TYPE isn't REF)
3042      *  <LI><B>SCOPE_SCHEMA</B> String {@code =>} schema of table that is the
3043      *      scope of a reference attribute (<code>null</code> if DATA_TYPE isn't REF)
3044      *  <LI><B>SCOPE_TABLE</B> String {@code =>} table name that is the scope of a
3045      *      reference attribute (<code>null</code> if the DATA_TYPE isn't REF)
3046      * <LI><B>SOURCE_DATA_TYPE</B> short {@code =>} source type of a distinct type or user-generated
3047      *      Ref type,SQL type from java.sql.Types (<code>null</code> if DATA_TYPE
3048      *      isn't DISTINCT or user-generated REF)
3049      *  </OL>
3050      * @param catalog a catalog name; must match the catalog name as it
3051      *        is stored in the database; "" retrieves those without a catalog;
3052      *        <code>null</code> means that the catalog name should not be used to narrow
3053      *        the search
3054      * @param schemaPattern a schema name pattern; must match the schema name
3055      *        as it is stored in the database; "" retrieves those without a schema;
3056      *        <code>null</code> means that the schema name should not be used to narrow
3057      *        the search
3058      * @param typeNamePattern a type name pattern; must match the
3059      *        type name as it is stored in the database
3060      * @param attributeNamePattern an attribute name pattern; must match the attribute
3061      *        name as it is declared in the database
3062      * @return a <code>ResultSet</code> object in which each row is an
3063      *         attribute description
3064      * @exception SQLException if a database access error occurs
3065      * @see #getSearchStringEscape
3066      * @since 1.4
3067      */
3068     ResultSet getAttributes(String catalog, String schemaPattern,
3069                             String typeNamePattern, String attributeNamePattern)
3070         throws SQLException;
3071 
3072     /**
3073      * Retrieves whether this database supports the given result set holdability.
3074      *
3075      * @param holdability one of the following constants:
3076      *          <code>ResultSet.HOLD_CURSORS_OVER_COMMIT</code> or
3077      *          <code>ResultSet.CLOSE_CURSORS_AT_COMMIT</code>
3078      * @return <code>true</code> if so; <code>false</code> otherwise
3079      * @exception SQLException if a database access error occurs
3080      * @see Connection
3081      * @since 1.4
3082      */
3083     boolean supportsResultSetHoldability(int holdability) throws SQLException;
3084 
3085     /**
3086      * Retrieves this database's default holdability for <code>ResultSet</code>
3087      * objects.
3088      *
3089      * @return the default holdability; either
3090      *         <code>ResultSet.HOLD_CURSORS_OVER_COMMIT</code> or
3091      *         <code>ResultSet.CLOSE_CURSORS_AT_COMMIT</code>
3092      * @exception SQLException if a database access error occurs
3093      * @since 1.4
3094      */
3095     int getResultSetHoldability() throws SQLException;
3096 
3097     /**
3098      * Retrieves the major version number of the underlying database.
3099      *
3100      * @return the underlying database's major version
3101      * @exception SQLException if a database access error occurs
3102      * @since 1.4
3103      */
3104     int getDatabaseMajorVersion() throws SQLException;
3105 
3106     /**
3107      * Retrieves the minor version number of the underlying database.
3108      *
3109      * @return underlying database's minor version
3110      * @exception SQLException if a database access error occurs
3111      * @since 1.4
3112      */
3113     int getDatabaseMinorVersion() throws SQLException;
3114 
3115     /**
3116      * Retrieves the major JDBC version number for this
3117      * driver.
3118      *
3119      * @return JDBC version major number
3120      * @exception SQLException if a database access error occurs
3121      * @since 1.4
3122      */
3123     int getJDBCMajorVersion() throws SQLException;
3124 
3125     /**
3126      * Retrieves the minor JDBC version number for this
3127      * driver.
3128      *
3129      * @return JDBC version minor number
3130      * @exception SQLException if a database access error occurs
3131      * @since 1.4
3132      */
3133     int getJDBCMinorVersion() throws SQLException;
3134 
3135     /**
3136      *  A possible return value for the method
3137      * <code>DatabaseMetaData.getSQLStateType</code> which is used to indicate
3138      * whether the value returned by the method
3139      * <code>SQLException.getSQLState</code> is an
3140      * X/Open (now know as Open Group) SQL CLI SQLSTATE value.
3141      * <P>
3142      * @since 1.4
3143      */
3144     int sqlStateXOpen = 1;
3145 
3146     /**
3147      *  A possible return value for the method
3148      * <code>DatabaseMetaData.getSQLStateType</code> which is used to indicate
3149      * whether the value returned by the method
3150      * <code>SQLException.getSQLState</code> is an SQLSTATE value.
3151      * <P>
3152      * @since 1.6
3153      */
3154     int sqlStateSQL = 2;
3155 
3156      /**
3157      *  A possible return value for the method
3158      * <code>DatabaseMetaData.getSQLStateType</code> which is used to indicate
3159      * whether the value returned by the method
3160      * <code>SQLException.getSQLState</code> is an SQL99 SQLSTATE value.
3161      * <P>
3162      * <b>Note:</b>This constant remains only for compatibility reasons. Developers
3163      * should use the constant <code>sqlStateSQL</code> instead.
3164      *
3165      * @since 1.4
3166      */
3167     int sqlStateSQL99 = sqlStateSQL;
3168 
3169     /**
3170      * Indicates whether the SQLSTATE returned by <code>SQLException.getSQLState</code>
3171      * is X/Open (now known as Open Group) SQL CLI or SQL:2003.
3172      * @return the type of SQLSTATE; one of:
3173      *        sqlStateXOpen or
3174      *        sqlStateSQL
3175      * @throws SQLException if a database access error occurs
3176      * @since 1.4
3177      */
3178     int getSQLStateType() throws SQLException;
3179 
3180     /**
3181      * Indicates whether updates made to a LOB are made on a copy or directly
3182      * to the LOB.
3183      * @return <code>true</code> if updates are made to a copy of the LOB;
3184      *         <code>false</code> if updates are made directly to the LOB
3185      * @throws SQLException if a database access error occurs
3186      * @since 1.4
3187      */
3188     boolean locatorsUpdateCopy() throws SQLException;
3189 
3190     /**
3191      * Retrieves whether this database supports statement pooling.
3192      *
3193      * @return <code>true</code> if so; <code>false</code> otherwise
3194      * @throws SQLException if a database access error occurs
3195      * @since 1.4
3196      */
3197     boolean supportsStatementPooling() throws SQLException;
3198 
3199     //------------------------- JDBC 4.0 -----------------------------------
3200 
3201     /**
3202      * Indicates whether or not this data source supports the SQL <code>ROWID</code> type,
3203      * and if so  the lifetime for which a <code>RowId</code> object remains valid.
3204      * <p>
3205      * The returned int values have the following relationship:
3206      * <pre>{@code
3207      *     ROWID_UNSUPPORTED < ROWID_VALID_OTHER < ROWID_VALID_TRANSACTION
3208      *         < ROWID_VALID_SESSION < ROWID_VALID_FOREVER
3209      * }</pre>
3210      * so conditional logic such as
3211      * <pre>{@code
3212      *     if (metadata.getRowIdLifetime() > DatabaseMetaData.ROWID_VALID_TRANSACTION)
3213      * }</pre>
3214      * can be used. Valid Forever means valid across all Sessions, and valid for
3215      * a Session means valid across all its contained Transactions.
3216      *
3217      * @return the status indicating the lifetime of a <code>RowId</code>
3218      * @throws SQLException if a database access error occurs
3219      * @since 1.6
3220      */
3221     RowIdLifetime getRowIdLifetime() throws SQLException;
3222 
3223     /**
3224      * Retrieves the schema names available in this database.  The results
3225      * are ordered by <code>TABLE_CATALOG</code> and
3226      * <code>TABLE_SCHEM</code>.
3227      *
3228      * <P>The schema columns are:
3229      *  <OL>
3230      *  <LI><B>TABLE_SCHEM</B> String {@code =>} schema name
3231      *  <LI><B>TABLE_CATALOG</B> String {@code =>} catalog name (may be <code>null</code>)
3232      *  </OL>
3233      *
3234      *
3235      * @param catalog a catalog name; must match the catalog name as it is stored
3236      * in the database;"" retrieves those without a catalog; null means catalog
3237      * name should not be used to narrow down the search.
3238      * @param schemaPattern a schema name; must match the schema name as it is
3239      * stored in the database; null means
3240      * schema name should not be used to narrow down the search.
3241      * @return a <code>ResultSet</code> object in which each row is a
3242      *         schema description
3243      * @exception SQLException if a database access error occurs
3244      * @see #getSearchStringEscape
3245      * @since 1.6
3246      */
3247     ResultSet getSchemas(String catalog, String schemaPattern) throws SQLException;
3248 
3249     /**
3250      * Retrieves whether this database supports invoking user-defined or vendor functions
3251      * using the stored procedure escape syntax.
3252      *
3253      * @return <code>true</code> if so; <code>false</code> otherwise
3254      * @exception SQLException if a database access error occurs
3255      * @since 1.6
3256      */
3257     boolean supportsStoredFunctionsUsingCallSyntax() throws SQLException;
3258 
3259     /**
3260      * Retrieves whether a <code>SQLException</code> while autoCommit is <code>true</code> indicates
3261      * that all open ResultSets are closed, even ones that are holdable.  When a <code>SQLException</code> occurs while
3262      * autocommit is <code>true</code>, it is vendor specific whether the JDBC driver responds with a commit operation, a
3263      * rollback operation, or by doing neither a commit nor a rollback.  A potential result of this difference
3264      * is in whether or not holdable ResultSets are closed.
3265      *
3266      * @return <code>true</code> if so; <code>false</code> otherwise
3267      * @exception SQLException if a database access error occurs
3268      * @since 1.6
3269      */
3270     boolean autoCommitFailureClosesAllResultSets() throws SQLException;
3271         /**
3272          * Retrieves a list of the client info properties
3273          * that the driver supports.  The result set contains the following columns
3274          *
3275          * <ol>
3276          * <li><b>NAME</b> String{@code =>} The name of the client info property<br>
3277          * <li><b>MAX_LEN</b> int{@code =>} The maximum length of the value for the property<br>
3278          * <li><b>DEFAULT_VALUE</b> String{@code =>} The default value of the property<br>
3279          * <li><b>DESCRIPTION</b> String{@code =>} A description of the property.  This will typically
3280          *                                              contain information as to where this property is
3281          *                                              stored in the database.
3282          * </ol>
3283          * <p>
3284          * The <code>ResultSet</code> is sorted by the NAME column
3285          * <p>
3286          * @return      A <code>ResultSet</code> object; each row is a supported client info
3287          * property
3288          * <p>
3289          *  @exception SQLException if a database access error occurs
3290          * <p>
3291          * @since 1.6
3292          */
3293         ResultSet getClientInfoProperties()
3294                 throws SQLException;
3295 
3296     /**
3297      * Retrieves a description of the  system and user functions available
3298      * in the given catalog.
3299      * <P>
3300      * Only system and user function descriptions matching the schema and
3301      * function name criteria are returned.  They are ordered by
3302      * <code>FUNCTION_CAT</code>, <code>FUNCTION_SCHEM</code>,
3303      * <code>FUNCTION_NAME</code> and
3304      * <code>SPECIFIC_ NAME</code>.
3305      *
3306      * <P>Each function description has the the following columns:
3307      *  <OL>
3308      *  <LI><B>FUNCTION_CAT</B> String {@code =>} function catalog (may be <code>null</code>)
3309      *  <LI><B>FUNCTION_SCHEM</B> String {@code =>} function schema (may be <code>null</code>)
3310      *  <LI><B>FUNCTION_NAME</B> String {@code =>} function name.  This is the name
3311      * used to invoke the function
3312      *  <LI><B>REMARKS</B> String {@code =>} explanatory comment on the function
3313      * <LI><B>FUNCTION_TYPE</B> short {@code =>} kind of function:
3314      *      <UL>
3315      *      <LI>functionResultUnknown - Cannot determine if a return value
3316      *       or table will be returned
3317      *      <LI> functionNoTable- Does not return a table
3318      *      <LI> functionReturnsTable - Returns a table
3319      *      </UL>
3320      *  <LI><B>SPECIFIC_NAME</B> String  {@code =>} the name which uniquely identifies
3321      *  this function within its schema.  This is a user specified, or DBMS
3322      * generated, name that may be different then the <code>FUNCTION_NAME</code>
3323      * for example with overload functions
3324      *  </OL>
3325      * <p>
3326      * A user may not have permission to execute any of the functions that are
3327      * returned by <code>getFunctions</code>
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 to narrow
3332      *        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 schema;
3335      *        <code>null</code> means that the schema name should not be used to narrow
3336      *        the search
3337      * @param functionNamePattern a function name pattern; must match the
3338      *        function name as it is stored in the database
3339      * @return <code>ResultSet</code> - each row is a function description
3340      * @exception SQLException if a database access error occurs
3341      * @see #getSearchStringEscape
3342      * @since 1.6
3343      */
3344     ResultSet getFunctions(String catalog, String schemaPattern,
3345                             String functionNamePattern) throws SQLException;
3346     /**
3347      * Retrieves a description of the given catalog's system or user
3348      * function parameters and return type.
3349      *
3350      * <P>Only descriptions matching the schema,  function and
3351      * parameter name criteria are returned. They are ordered by
3352      * <code>FUNCTION_CAT</code>, <code>FUNCTION_SCHEM</code>,
3353      * <code>FUNCTION_NAME</code> and
3354      * <code>SPECIFIC_ NAME</code>. Within this, the return value,
3355      * if any, is first. Next are the parameter descriptions in call
3356      * order. The column descriptions follow in column number order.
3357      *
3358      * <P>Each row in the <code>ResultSet</code>
3359      * is a parameter description, column description or
3360      * return type description with the following fields:
3361      *  <OL>
3362      *  <LI><B>FUNCTION_CAT</B> String {@code =>} function catalog (may be <code>null</code>)
3363      *  <LI><B>FUNCTION_SCHEM</B> String {@code =>} function schema (may be <code>null</code>)
3364      *  <LI><B>FUNCTION_NAME</B> String {@code =>} function name.  This is the name
3365      * used to invoke the function
3366      *  <LI><B>COLUMN_NAME</B> String {@code =>} column/parameter name
3367      *  <LI><B>COLUMN_TYPE</B> Short {@code =>} kind of column/parameter:
3368      *      <UL>
3369      *      <LI> functionColumnUnknown - nobody knows
3370      *      <LI> functionColumnIn - IN parameter
3371      *      <LI> functionColumnInOut - INOUT parameter
3372      *      <LI> functionColumnOut - OUT parameter
3373      *      <LI> functionColumnReturn - function return value
3374      *      <LI> functionColumnResult - Indicates that the parameter or column
3375      *  is a column in the <code>ResultSet</code>
3376      *      </UL>
3377      *  <LI><B>DATA_TYPE</B> int {@code =>} SQL type from java.sql.Types
3378      *  <LI><B>TYPE_NAME</B> String {@code =>} SQL type name, for a UDT type the
3379      *  type name is fully qualified
3380      *  <LI><B>PRECISION</B> int {@code =>} precision
3381      *  <LI><B>LENGTH</B> int {@code =>} length in bytes of data
3382      *  <LI><B>SCALE</B> short {@code =>} scale -  null is returned for data types where
3383      * SCALE is not applicable.
3384      *  <LI><B>RADIX</B> short {@code =>} radix
3385      *  <LI><B>NULLABLE</B> short {@code =>} can it contain NULL.
3386      *      <UL>
3387      *      <LI> functionNoNulls - does not allow NULL values
3388      *      <LI> functionNullable - allows NULL values
3389      *      <LI> functionNullableUnknown - nullability unknown
3390      *      </UL>
3391      *  <LI><B>REMARKS</B> String {@code =>} comment describing column/parameter
3392      *  <LI><B>CHAR_OCTET_LENGTH</B> int  {@code =>} the maximum length of binary
3393      * and character based parameters or columns.  For any other datatype the returned value
3394      * is a NULL
3395      *  <LI><B>ORDINAL_POSITION</B> int  {@code =>} the ordinal position, starting
3396      * from 1, for the input and output parameters. A value of 0
3397      * is returned if this row describes the function's return value.
3398      * For result set columns, it is the
3399      * ordinal position of the column in the result set starting from 1.
3400      *  <LI><B>IS_NULLABLE</B> String  {@code =>} ISO rules are used to determine
3401      * the nullability for a parameter or column.
3402      *       <UL>
3403      *       <LI> YES           --- if the parameter or column can include NULLs
3404      *       <LI> NO            --- if the parameter or column  cannot include NULLs
3405      *       <LI> empty string  --- if the nullability for the
3406      * parameter  or column is unknown
3407      *       </UL>
3408      *  <LI><B>SPECIFIC_NAME</B> String  {@code =>} the name which uniquely identifies
3409      * this function within its schema.  This is a user specified, or DBMS
3410      * generated, name that may be different then the <code>FUNCTION_NAME</code>
3411      * for example with overload functions
3412      *  </OL>
3413      *
3414      * <p>The PRECISION column represents the specified column size for the given
3415      * parameter or column.
3416      * For numeric data, this is the maximum precision.  For character data, this is the length in characters.
3417      * For datetime datatypes, this is the length in characters of the String representation (assuming the
3418      * maximum allowed precision of the fractional seconds component). For binary data, this is the length in bytes.  For the ROWID datatype,
3419      * this is the length in bytes. Null is returned for data types where the
3420      * column size is not applicable.
3421      * @param catalog a catalog name; must match the catalog name as it
3422      *        is stored in the database; "" retrieves those without a catalog;
3423      *        <code>null</code> means that the catalog name should not be used to narrow
3424      *        the search
3425      * @param schemaPattern a schema name pattern; must match the schema name
3426      *        as it is stored in the database; "" retrieves those without a schema;
3427      *        <code>null</code> means that the schema name should not be used to narrow
3428      *        the search
3429      * @param functionNamePattern a procedure name pattern; must match the
3430      *        function name as it is stored in the database
3431      * @param columnNamePattern a parameter name pattern; must match the
3432      * parameter or column name as it is stored in the database
3433      * @return <code>ResultSet</code> - each row describes a
3434      * user function parameter, column  or return type
3435      *
3436      * @exception SQLException if a database access error occurs
3437      * @see #getSearchStringEscape
3438      * @since 1.6
3439      */
3440     ResultSet getFunctionColumns(String catalog,
3441                                   String schemaPattern,
3442                                   String functionNamePattern,
3443                                   String columnNamePattern) throws SQLException;
3444 
3445 
3446     /**
3447      * Indicates that type of the parameter or column is unknown.
3448      * <P>
3449      * A possible value for the column
3450      * <code>COLUMN_TYPE</code>
3451      * in the <code>ResultSet</code>
3452      * returned by the method <code>getFunctionColumns</code>.
3453      */
3454     int functionColumnUnknown = 0;
3455 
3456     /**
3457      * Indicates that the parameter or column is an IN parameter.
3458      * <P>
3459      *  A possible value for the column
3460      * <code>COLUMN_TYPE</code>
3461      * in the <code>ResultSet</code>
3462      * returned by the method <code>getFunctionColumns</code>.
3463      * @since 1.6
3464      */
3465     int functionColumnIn = 1;
3466 
3467     /**
3468      * Indicates that the parameter or column is an INOUT parameter.
3469      * <P>
3470      * A possible value for the column
3471      * <code>COLUMN_TYPE</code>
3472      * in the <code>ResultSet</code>
3473      * returned by the method <code>getFunctionColumns</code>.
3474      * @since 1.6
3475      */
3476     int functionColumnInOut = 2;
3477 
3478     /**
3479      * Indicates that the parameter or column is an OUT parameter.
3480      * <P>
3481      * A possible value for the column
3482      * <code>COLUMN_TYPE</code>
3483      * in the <code>ResultSet</code>
3484      * returned by the method <code>getFunctionColumns</code>.
3485      * @since 1.6
3486      */
3487     int functionColumnOut = 3;
3488     /**
3489      * Indicates that the parameter or column is a return value.
3490      * <P>
3491      *  A possible value for the column
3492      * <code>COLUMN_TYPE</code>
3493      * in the <code>ResultSet</code>
3494      * returned by the method <code>getFunctionColumns</code>.
3495      * @since 1.6
3496      */
3497     int functionReturn = 4;
3498 
3499        /**
3500      * Indicates that the parameter or column is a column in a result set.
3501      * <P>
3502      *  A possible value for the column
3503      * <code>COLUMN_TYPE</code>
3504      * in the <code>ResultSet</code>
3505      * returned by the method <code>getFunctionColumns</code>.
3506      * @since 1.6
3507      */
3508     int functionColumnResult = 5;
3509 
3510 
3511     /**
3512      * Indicates that <code>NULL</code> values are not allowed.
3513      * <P>
3514      * A possible value for the column
3515      * <code>NULLABLE</code>
3516      * in the <code>ResultSet</code> object
3517      * returned by the method <code>getFunctionColumns</code>.
3518      * @since 1.6
3519      */
3520     int functionNoNulls = 0;
3521 
3522     /**
3523      * Indicates that <code>NULL</code> values are allowed.
3524      * <P>
3525      * A possible value for the column
3526      * <code>NULLABLE</code>
3527      * in the <code>ResultSet</code> object
3528      * returned by the method <code>getFunctionColumns</code>.
3529      * @since 1.6
3530      */
3531     int functionNullable = 1;
3532 
3533     /**
3534      * Indicates that whether <code>NULL</code> values are allowed
3535      * is unknown.
3536      * <P>
3537      * A possible value for the column
3538      * <code>NULLABLE</code>
3539      * in the <code>ResultSet</code> object
3540      * returned by the method <code>getFunctionColumns</code>.
3541      * @since 1.6
3542      */
3543     int functionNullableUnknown = 2;
3544 
3545     /**
3546      * Indicates that it is not known whether the function returns
3547      * a result or a table.
3548      * <P>
3549      * A possible value for column <code>FUNCTION_TYPE</code> in the
3550      * <code>ResultSet</code> object returned by the method
3551      * <code>getFunctions</code>.
3552      * @since 1.6
3553      */
3554     int functionResultUnknown   = 0;
3555 
3556     /**
3557      * Indicates that the function  does not return a table.
3558      * <P>
3559      * A possible value for column <code>FUNCTION_TYPE</code> in the
3560      * <code>ResultSet</code> object returned by the method
3561      * <code>getFunctions</code>.
3562      * @since 1.6
3563      */
3564     int functionNoTable         = 1;
3565 
3566     /**
3567      * Indicates that the function  returns a table.
3568      * <P>
3569      * A possible value for column <code>FUNCTION_TYPE</code> in the
3570      * <code>ResultSet</code> object returned by the method
3571      * <code>getFunctions</code>.
3572      * @since 1.6
3573      */
3574     int functionReturnsTable    = 2;
3575 
3576     //--------------------------JDBC 4.1 -----------------------------
3577 
3578     /**
3579      * Retrieves a description of the pseudo or hidden columns available
3580      * in a given table within the specified catalog and schema.
3581      * Pseudo or hidden columns may not always be stored within
3582      * a table and are not visible in a ResultSet unless they are
3583      * specified in the query's outermost SELECT list. Pseudo or hidden
3584      * columns may not necessarily be able to be modified. If there are
3585      * no pseudo or hidden columns, an empty ResultSet is returned.
3586      *
3587      * <P>Only column descriptions matching the catalog, schema, table
3588      * and column name criteria are returned.  They are ordered by
3589      * <code>TABLE_CAT</code>,<code>TABLE_SCHEM</code>, <code>TABLE_NAME</code>
3590      * and <code>COLUMN_NAME</code>.
3591      *
3592      * <P>Each column description has the following columns:
3593      *  <OL>
3594      *  <LI><B>TABLE_CAT</B> String {@code =>} table catalog (may be <code>null</code>)
3595      *  <LI><B>TABLE_SCHEM</B> String {@code =>} table schema (may be <code>null</code>)
3596      *  <LI><B>TABLE_NAME</B> String {@code =>} table name
3597      *  <LI><B>COLUMN_NAME</B> String {@code =>} column name
3598      *  <LI><B>DATA_TYPE</B> int {@code =>} SQL type from java.sql.Types
3599      *  <LI><B>COLUMN_SIZE</B> int {@code =>} column size.
3600      *  <LI><B>DECIMAL_DIGITS</B> int {@code =>} the number of fractional digits. Null is returned for data types where
3601      * DECIMAL_DIGITS is not applicable.
3602      *  <LI><B>NUM_PREC_RADIX</B> int {@code =>} Radix (typically either 10 or 2)
3603      *  <LI><B>COLUMN_USAGE</B> String {@code =>} The allowed usage for the column.  The
3604      *  value returned will correspond to the enum name returned by {@link PseudoColumnUsage#name PseudoColumnUsage.name()}
3605      *  <LI><B>REMARKS</B> String {@code =>} comment describing column (may be <code>null</code>)
3606      *  <LI><B>CHAR_OCTET_LENGTH</B> int {@code =>} for char types the
3607      *       maximum number of bytes in the column
3608      *  <LI><B>IS_NULLABLE</B> String  {@code =>} ISO rules are used to determine the nullability for a column.
3609      *       <UL>
3610      *       <LI> YES           --- if the column can include NULLs
3611      *       <LI> NO            --- if the column cannot include NULLs
3612      *       <LI> empty string  --- if the nullability for the column is unknown
3613      *       </UL>
3614      *  </OL>
3615      *
3616      * <p>The COLUMN_SIZE column specifies the column size for the given column.
3617      * For numeric data, this is the maximum precision.  For character data, this is the length in characters.
3618      * For datetime datatypes, this is the length in characters of the String representation (assuming the
3619      * maximum allowed precision of the fractional seconds component). For binary data, this is the length in bytes.  For the ROWID datatype,
3620      * this is the length in bytes. Null is returned for data types where the
3621      * column size is not applicable.
3622      *
3623      * @param catalog a catalog name; must match the catalog name as it
3624      *        is stored in the database; "" retrieves those without a catalog;
3625      *        <code>null</code> means that the catalog name should not be used to narrow
3626      *        the search
3627      * @param schemaPattern a schema name pattern; must match the schema name
3628      *        as it is stored in the database; "" retrieves those without a schema;
3629      *        <code>null</code> means that the schema name should not be used to narrow
3630      *        the search
3631      * @param tableNamePattern a table name pattern; must match the
3632      *        table name as it is stored in the database
3633      * @param columnNamePattern a column name pattern; must match the column
3634      *        name as it is stored in the database
3635      * @return <code>ResultSet</code> - each row is a column description
3636      * @exception SQLException if a database access error occurs
3637      * @see PseudoColumnUsage
3638      * @since 1.7
3639      */
3640     ResultSet getPseudoColumns(String catalog, String schemaPattern,
3641                          String tableNamePattern, String columnNamePattern)
3642         throws SQLException;
3643 
3644     /**
3645      * Retrieves whether a generated key will always be returned if the column
3646      * name(s) or index(es) specified for the auto generated key column(s)
3647      * are valid and the statement succeeds.  The key that is returned may or
3648      * may not be based on the column(s) for the auto generated key.
3649      * Consult your JDBC driver documentation for additional details.
3650      * @return <code>true</code> if so; <code>false</code> otherwise
3651      * @exception SQLException if a database access error occurs
3652      * @since 1.7
3653      */
3654     boolean  generatedKeyAlwaysReturned() throws SQLException;
3655 
3656     //--------------------------JDBC 4.2 -----------------------------
3657 
3658     /**
3659      *
3660      * Retrieves the maximum number of bytes this database allows for
3661      * the logical size for a {@code LOB}.
3662      *<p>
3663      * The default implementation will return {@code 0}
3664      *
3665      * @return the maximum number of bytes allowed; a result of zero
3666      * means that there is no limit or the limit is not known
3667      * @exception SQLException if a database access error occurs
3668      * @since 1.8
3669      */
3670     default long getMaxLogicalLobSize() throws SQLException {
3671         return 0;
3672     }
3673 
3674     /**
3675      * Retrieves whether this database supports REF CURSOR.
3676      *<p>
3677      * The default implementation will return {@code false}
3678      *
3679      * @return {@code true} if this database supports REF CURSOR;
3680      *         {@code false} otherwise
3681      * @exception SQLException if a database access error occurs
3682      * @since 1.8
3683      */
3684     default boolean supportsRefCursors() throws SQLException{
3685         return false;
3686     }
3687 
3688 }