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