1 /*
2 * Copyright (c) 1996, 2017, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26
27 package java.sql;
28
29 /**
30 * Comprehensive information about the database as a whole.
31 * <P>
32 * This interface is implemented by driver vendors to let users know the capabilities
33 * of a Database Management System (DBMS) in combination with
34 * the driver based on JDBC™ technology
35 * ("JDBC driver") that is used with it. Different relational DBMSs often support
36 * different features, implement features in different ways, and use different
37 * data types. In addition, a driver may implement a feature on top of what the
38 * DBMS offers. Information returned by methods in this interface applies
39 * to the capabilities of a particular driver and a particular DBMS working
40 * together. Note that as used in this documentation, the term "database" is
41 * used generically to refer to both the driver and DBMS.
42 * <P>
43 * A user for this interface is commonly a tool that needs to discover how to
44 * deal with the underlying DBMS. This is especially true for applications
45 * that are intended to be used with more than one DBMS. For example, a tool might use the method
46 * <code>getTypeInfo</code> to find out what data types can be used in a
47 * <code>CREATE TABLE</code> statement. Or a user might call the method
48 * <code>supportsCorrelatedSubqueries</code> to see if it is possible to use
49 * a correlated subquery or <code>supportsBatchUpdates</code> to see if it is
50 * possible to use batch updates.
51 * <P>
52 * Some <code>DatabaseMetaData</code> methods return lists of information
53 * in the form of <code>ResultSet</code> objects.
54 * Regular <code>ResultSet</code> methods, such as
55 * <code>getString</code> and <code>getInt</code>, can be used
56 * to retrieve the data from these <code>ResultSet</code> objects. If
57 * a given form of metadata is not available, an empty <code>ResultSet</code>
58 * will be returned. Additional columns beyond the columns defined to be
59 * returned by the <code>ResultSet</code> object for a given method
60 * can be defined by the JDBC driver vendor and must be accessed
61 * by their <B>column label</B>.
62 * <P>
63 * Some <code>DatabaseMetaData</code> methods take arguments that are
64 * String patterns. These arguments all have names such as fooPattern.
65 * Within a pattern String, "%" means match any substring of 0 or more
66 * characters, and "_" means match any one character. Only metadata
67 * entries matching the search pattern are returned. If a search pattern
68 * argument is set to <code>null</code>, that argument's criterion will
69 * be dropped from the search.
70 *
71 * @since 1.1
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
198 String getDriverVersion() throws SQLException;
199
200 /**
201 * Retrieves this JDBC driver's major version number.
202 *
203 * @return JDBC driver major version
204 */
205 int getDriverMajorVersion();
206
207 /**
208 * Retrieves this JDBC driver's minor version number.
209 *
210 * @return JDBC driver minor version number
211 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 following columns:
1221 * <OL>
1222 * <LI><B>PROCEDURE_CAT</B> String {@code =>} procedure catalog (may be <code>null</code>)
1223 * <LI><B>PROCEDURE_SCHEM</B> String {@code =>} procedure schema (may be <code>null</code>)
1224 * <LI><B>PROCEDURE_NAME</B> String {@code =>} 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 {@code =>} explanatory comment on the procedure
1229 * <LI><B>PROCEDURE_TYPE</B> short {@code =>} 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 {@code =>} 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 */
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 {@code =>} procedure catalog (may be <code>null</code>)
1302 * <LI><B>PROCEDURE_SCHEM</B> String {@code =>} procedure schema (may be <code>null</code>)
1303 * <LI><B>PROCEDURE_NAME</B> String {@code =>} procedure name
1304 * <LI><B>COLUMN_NAME</B> String {@code =>} column/parameter name
1305 * <LI><B>COLUMN_TYPE</B> Short {@code =>} 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 {@code =>} SQL type from java.sql.Types
1315 * <LI><B>TYPE_NAME</B> String {@code =>} SQL type name, for a UDT type the
1316 * type name is fully qualified
1317 * <LI><B>PRECISION</B> int {@code =>} precision
1318 * <LI><B>LENGTH</B> int {@code =>} length in bytes of data
1319 * <LI><B>SCALE</B> short {@code =>} scale - null is returned for data types where
1320 * SCALE is not applicable.
1321 * <LI><B>RADIX</B> short {@code =>} radix
1322 * <LI><B>NULLABLE</B> short {@code =>} 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 {@code =>} comment describing parameter/column
1329 * <LI><B>COLUMN_DEF</B> String {@code =>} default value for the column, which should be interpreted as a string when the value is enclosed in single quotes (may be <code>null</code>)
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 {@code =>} reserved for future use
1336 * <LI><B>SQL_DATETIME_SUB</B> int {@code =>} reserved for future use
1337 * <LI><B>CHAR_OCTET_LENGTH</B> int {@code =>} the maximum length of binary and character based columns. For any other datatype the returned value is a
1338 * NULL
1339 * <LI><B>ORDINAL_POSITION</B> int {@code =>} the ordinal position, starting from 1, for the input and output parameters for a procedure. A value of 0
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 {@code =>} 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 {@code =>} 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 */
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 {@code =>} table catalog (may be <code>null</code>)
1486 * <LI><B>TABLE_SCHEM</B> String {@code =>} table schema (may be <code>null</code>)
1487 * <LI><B>TABLE_NAME</B> String {@code =>} table name
1488 * <LI><B>TABLE_TYPE</B> String {@code =>} table type. Typical types are "TABLE",
1489 * "VIEW", "SYSTEM TABLE", "GLOBAL TEMPORARY",
1490 * "LOCAL TEMPORARY", "ALIAS", "SYNONYM".
1491 * <LI><B>REMARKS</B> String {@code =>} explanatory comment on the table (may be {@code null})
1492 * <LI><B>TYPE_CAT</B> String {@code =>} the types catalog (may be <code>null</code>)
1493 * <LI><B>TYPE_SCHEM</B> String {@code =>} the types schema (may be <code>null</code>)
1494 * <LI><B>TYPE_NAME</B> String {@code =>} type name (may be <code>null</code>)
1495 * <LI><B>SELF_REFERENCING_COL_NAME</B> String {@code =>} name of the designated
1496 * "identifier" column of a typed table (may be <code>null</code>)
1497 * <LI><B>REF_GENERATION</B> String {@code =>} 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 */
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 {@code =>} schema name
1533 * <LI><B>TABLE_CATALOG</B> String {@code =>} 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 */
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 {@code =>} 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 */
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 {@code =>} 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 */
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 {@code =>} table catalog (may be <code>null</code>)
1587 * <LI><B>TABLE_SCHEM</B> String {@code =>} table schema (may be <code>null</code>)
1588 * <LI><B>TABLE_NAME</B> String {@code =>} table name
1589 * <LI><B>COLUMN_NAME</B> String {@code =>} column name
1590 * <LI><B>DATA_TYPE</B> int {@code =>} SQL type from java.sql.Types
1591 * <LI><B>TYPE_NAME</B> String {@code =>} Data source dependent type name,
1592 * for a UDT the type name is fully qualified
1593 * <LI><B>COLUMN_SIZE</B> int {@code =>} column size.
1594 * <LI><B>BUFFER_LENGTH</B> is not used.
1595 * <LI><B>DECIMAL_DIGITS</B> int {@code =>} 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 {@code =>} Radix (typically either 10 or 2)
1598 * <LI><B>NULLABLE</B> int {@code =>} 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 {@code =>} comment describing column (may be <code>null</code>)
1605 * <LI><B>COLUMN_DEF</B> String {@code =>} default value for the column, which should be interpreted as a string when the value is enclosed in single quotes (may be <code>null</code>)
1606 * <LI><B>SQL_DATA_TYPE</B> int {@code =>} unused
1607 * <LI><B>SQL_DATETIME_SUB</B> int {@code =>} unused
1608 * <LI><B>CHAR_OCTET_LENGTH</B> int {@code =>} for char types the
1609 * maximum number of bytes in the column
1610 * <LI><B>ORDINAL_POSITION</B> int {@code =>} index of column in table
1611 * (starting at 1)
1612 * <LI><B>IS_NULLABLE</B> String {@code =>} 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 {@code =>} 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 {@code =>} 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 {@code =>} 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 {@code =>} 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 {@code =>} 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 {@code =>} 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 */
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 privilege description has the following columns:
1706 * <OL>
1707 * <LI><B>TABLE_CAT</B> String {@code =>} table catalog (may be <code>null</code>)
1708 * <LI><B>TABLE_SCHEM</B> String {@code =>} table schema (may be <code>null</code>)
1709 * <LI><B>TABLE_NAME</B> String {@code =>} table name
1710 * <LI><B>COLUMN_NAME</B> String {@code =>} column name
1711 * <LI><B>GRANTOR</B> String {@code =>} grantor of access (may be <code>null</code>)
1712 * <LI><B>GRANTEE</B> String {@code =>} grantee of access
1713 * <LI><B>PRIVILEGE</B> String {@code =>} name of access (SELECT,
1714 * INSERT, UPDATE, REFERENCES, ...)
1715 * <LI><B>IS_GRANTABLE</B> String {@code =>} "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 */
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 privilege description has the following columns:
1752 * <OL>
1753 * <LI><B>TABLE_CAT</B> String {@code =>} table catalog (may be <code>null</code>)
1754 * <LI><B>TABLE_SCHEM</B> String {@code =>} table schema (may be <code>null</code>)
1755 * <LI><B>TABLE_NAME</B> String {@code =>} table name
1756 * <LI><B>GRANTOR</B> String {@code =>} grantor of access (may be <code>null</code>)
1757 * <LI><B>GRANTEE</B> String {@code =>} grantee of access
1758 * <LI><B>PRIVILEGE</B> String {@code =>} name of access (SELECT,
1759 * INSERT, UPDATE, REFERENCES, ...)
1760 * <LI><B>IS_GRANTABLE</B> String {@code =>} "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 */
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 {@code =>} 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 {@code =>} column name
1794 * <LI><B>DATA_TYPE</B> int {@code =>} SQL data type from java.sql.Types
1795 * <LI><B>TYPE_NAME</B> String {@code =>} Data source dependent type name,
1796 * for a UDT the type name is fully qualified
1797 * <LI><B>COLUMN_SIZE</B> int {@code =>} precision
1798 * <LI><B>BUFFER_LENGTH</B> int {@code =>} not used
1799 * <LI><B>DECIMAL_DIGITS</B> short {@code =>} scale - Null is returned for data types where
1800 * DECIMAL_DIGITS is not applicable.
1801 * <LI><B>PSEUDO_COLUMN</B> short {@code =>} 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 */
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 {@code =>} is not used
1907 * <LI><B>COLUMN_NAME</B> String {@code =>} column name
1908 * <LI><B>DATA_TYPE</B> int {@code =>} SQL data type from <code>java.sql.Types</code>
1909 * <LI><B>TYPE_NAME</B> String {@code =>} Data source-dependent type name
1910 * <LI><B>COLUMN_SIZE</B> int {@code =>} precision
1911 * <LI><B>BUFFER_LENGTH</B> int {@code =>} length of column value in bytes
1912 * <LI><B>DECIMAL_DIGITS</B> short {@code =>} scale - Null is returned for data types where
1913 * DECIMAL_DIGITS is not applicable.
1914 * <LI><B>PSEUDO_COLUMN</B> short {@code =>} 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 */
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 {@code =>} table catalog (may be <code>null</code>)
1983 * <LI><B>TABLE_SCHEM</B> String {@code =>} table schema (may be <code>null</code>)
1984 * <LI><B>TABLE_NAME</B> String {@code =>} table name
1985 * <LI><B>COLUMN_NAME</B> String {@code =>} column name
1986 * <LI><B>KEY_SEQ</B> short {@code =>} 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 {@code =>} 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 */
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 {@code =>} primary key table catalog
2017 * being imported (may be <code>null</code>)
2018 * <LI><B>PKTABLE_SCHEM</B> String {@code =>} primary key table schema
2019 * being imported (may be <code>null</code>)
2020 * <LI><B>PKTABLE_NAME</B> String {@code =>} primary key table name
2021 * being imported
2022 * <LI><B>PKCOLUMN_NAME</B> String {@code =>} primary key column name
2023 * being imported
2024 * <LI><B>FKTABLE_CAT</B> String {@code =>} foreign key table catalog (may be <code>null</code>)
2025 * <LI><B>FKTABLE_SCHEM</B> String {@code =>} foreign key table schema (may be <code>null</code>)
2026 * <LI><B>FKTABLE_NAME</B> String {@code =>} foreign key table name
2027 * <LI><B>FKCOLUMN_NAME</B> String {@code =>} foreign key column name
2028 * <LI><B>KEY_SEQ</B> short {@code =>} 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 {@code =>} 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 {@code =>} 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 {@code =>} foreign key name (may be <code>null</code>)
2059 * <LI><B>PK_NAME</B> String {@code =>} primary key name (may be <code>null</code>)
2060 * <LI><B>DEFERRABILITY</B> short {@code =>} 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 */
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 {@code =>} primary key table catalog (may be <code>null</code>)
2200 * <LI><B>PKTABLE_SCHEM</B> String {@code =>} primary key table schema (may be <code>null</code>)
2201 * <LI><B>PKTABLE_NAME</B> String {@code =>} primary key table name
2202 * <LI><B>PKCOLUMN_NAME</B> String {@code =>} primary key column name
2203 * <LI><B>FKTABLE_CAT</B> String {@code =>} foreign key table catalog (may be <code>null</code>)
2204 * being exported (may be <code>null</code>)
2205 * <LI><B>FKTABLE_SCHEM</B> String {@code =>} foreign key table schema (may be <code>null</code>)
2206 * being exported (may be <code>null</code>)
2207 * <LI><B>FKTABLE_NAME</B> String {@code =>} foreign key table name
2208 * being exported
2209 * <LI><B>FKCOLUMN_NAME</B> String {@code =>} foreign key column name
2210 * being exported
2211 * <LI><B>KEY_SEQ</B> short {@code =>} 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 {@code =>} 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 {@code =>} 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 {@code =>} foreign key name (may be <code>null</code>)
2242 * <LI><B>PK_NAME</B> String {@code =>} primary key name (may be <code>null</code>)
2243 * <LI><B>DEFERRABILITY</B> short {@code =>} 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 */
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 {@code =>} parent key table catalog (may be <code>null</code>)
2281 * <LI><B>PKTABLE_SCHEM</B> String {@code =>} parent key table schema (may be <code>null</code>)
2282 * <LI><B>PKTABLE_NAME</B> String {@code =>} parent key table name
2283 * <LI><B>PKCOLUMN_NAME</B> String {@code =>} parent key column name
2284 * <LI><B>FKTABLE_CAT</B> String {@code =>} foreign key table catalog (may be <code>null</code>)
2285 * being exported (may be <code>null</code>)
2286 * <LI><B>FKTABLE_SCHEM</B> String {@code =>} foreign key table schema (may be <code>null</code>)
2287 * being exported (may be <code>null</code>)
2288 * <LI><B>FKTABLE_NAME</B> String {@code =>} foreign key table name
2289 * being exported
2290 * <LI><B>FKCOLUMN_NAME</B> String {@code =>} foreign key column name
2291 * being exported
2292 * <LI><B>KEY_SEQ</B> short {@code =>} 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 {@code =>} 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 {@code =>} 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 {@code =>} foreign key name (may be <code>null</code>)
2323 * <LI><B>PK_NAME</B> String {@code =>} parent key name (may be <code>null</code>)
2324 * <LI><B>DEFERRABILITY</B> short {@code =>} 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 */
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 * <P>Each type description has the following columns:
2373 * <OL>
2374 * <LI><B>TYPE_NAME</B> String {@code =>} Type name
2375 * <LI><B>DATA_TYPE</B> int {@code =>} SQL data type from java.sql.Types
2376 * <LI><B>PRECISION</B> int {@code =>} maximum precision
2377 * <LI><B>LITERAL_PREFIX</B> String {@code =>} prefix used to quote a literal
2378 * (may be <code>null</code>)
2379 * <LI><B>LITERAL_SUFFIX</B> String {@code =>} suffix used to quote a literal
2380 * (may be <code>null</code>)
2381 * <LI><B>CREATE_PARAMS</B> String {@code =>} parameters used in creating
2382 * the type (may be <code>null</code>)
2383 * <LI><B>NULLABLE</B> short {@code =>} can you use NULL for this type.
2384 * <UL>
2385 * <LI> typeNoNulls - does not allow NULL values
2386 * <LI> typeNullable - allows NULL values
2387 * <LI> typeNullableUnknown - nullability unknown
2388 * </UL>
2389 * <LI><B>CASE_SENSITIVE</B> boolean{@code =>} is it case sensitive.
2390 * <LI><B>SEARCHABLE</B> short {@code =>} can you use "WHERE" based on this type:
2391 * <UL>
2392 * <LI> typePredNone - No support
2393 * <LI> typePredChar - Only supported with WHERE .. LIKE
2394 * <LI> typePredBasic - Supported except for WHERE .. LIKE
2395 * <LI> typeSearchable - Supported for all WHERE ..
2396 * </UL>
2397 * <LI><B>UNSIGNED_ATTRIBUTE</B> boolean {@code =>} is it unsigned.
2398 * <LI><B>FIXED_PREC_SCALE</B> boolean {@code =>} can it be a money value.
2399 * <LI><B>AUTO_INCREMENT</B> boolean {@code =>} can it be used for an
2400 * auto-increment value.
2401 * <LI><B>LOCAL_TYPE_NAME</B> String {@code =>} localized version of type name
2402 * (may be <code>null</code>)
2403 * <LI><B>MINIMUM_SCALE</B> short {@code =>} minimum scale supported
2404 * <LI><B>MAXIMUM_SCALE</B> short {@code =>} maximum scale supported
2405 * <LI><B>SQL_DATA_TYPE</B> int {@code =>} unused
2406 * <LI><B>SQL_DATETIME_SUB</B> int {@code =>} unused
2407 * <LI><B>NUM_PREC_RADIX</B> int {@code =>} usually 2 or 10
2408 * </OL>
2409 *
2410 * <p>The PRECISION column represents the maximum column size that the server supports for the given datatype.
2411 * For numeric data, this is the maximum precision. For character data, this is the length in characters.
2412 * For datetime datatypes, this is the length in characters of the String representation (assuming the
2413 * maximum allowed precision of the fractional seconds component). For binary data, this is the length in bytes. For the ROWID datatype,
2414 * this is the length in bytes. Null is returned for data types where the
2415 * column size is not applicable.
2416 *
2417 * @return a <code>ResultSet</code> object in which each row is an SQL
2418 * type description
2419 * @exception SQLException if a database access error occurs
2420 */
2421 ResultSet getTypeInfo() throws SQLException;
2422
2423 /**
2424 * Indicates that a <code>NULL</code> value is NOT allowed for this
2425 * data type.
2426 * <P>
2427 * A possible value for column <code>NULLABLE</code> in the
2428 * <code>ResultSet</code> object returned by the method
2429 * <code>getTypeInfo</code>.
2430 */
2431 int typeNoNulls = 0;
2432
2433 /**
2434 * Indicates that a <code>NULL</code> value is allowed for this
2435 * data type.
2436 * <P>
2437 * A possible value for column <code>NULLABLE</code> in the
2438 * <code>ResultSet</code> object returned by the method
2439 * <code>getTypeInfo</code>.
2440 */
2441 int typeNullable = 1;
2442
2443 /**
2444 * Indicates that it is not known whether a <code>NULL</code> value
2445 * is allowed for this data type.
2446 * <P>
2447 * A possible value for column <code>NULLABLE</code> in the
2448 * <code>ResultSet</code> object returned by the method
2449 * <code>getTypeInfo</code>.
2450 */
2451 int typeNullableUnknown = 2;
2452
2453 /**
2454 * Indicates that <code>WHERE</code> search clauses are not supported
2455 * for this type.
2456 * <P>
2457 * A possible value for column <code>SEARCHABLE</code> in the
2458 * <code>ResultSet</code> object returned by the method
2459 * <code>getTypeInfo</code>.
2460 */
2461 int typePredNone = 0;
2462
2463 /**
2464 * Indicates that the data type
2465 * can be only be used in <code>WHERE</code> search clauses
2466 * that use <code>LIKE</code> predicates.
2467 * <P>
2468 * A possible value for column <code>SEARCHABLE</code> in the
2469 * <code>ResultSet</code> object returned by the method
2470 * <code>getTypeInfo</code>.
2471 */
2472 int typePredChar = 1;
2473
2474 /**
2475 * Indicates that the data type can be only be used in <code>WHERE</code>
2476 * search clauses
2477 * that do not use <code>LIKE</code> predicates.
2478 * <P>
2479 * A possible value for column <code>SEARCHABLE</code> in the
2480 * <code>ResultSet</code> object returned by the method
2481 * <code>getTypeInfo</code>.
2482 */
2483 int typePredBasic = 2;
2484
2485 /**
2486 * Indicates that all <code>WHERE</code> search clauses can be
2487 * based on this type.
2488 * <P>
2489 * A possible value for column <code>SEARCHABLE</code> in the
2490 * <code>ResultSet</code> object returned by the method
2491 * <code>getTypeInfo</code>.
2492 */
2493 int typeSearchable = 3;
2494
2495 /**
2496 * Retrieves a description of the given table's indices and statistics. They are
2497 * ordered by NON_UNIQUE, TYPE, INDEX_NAME, and ORDINAL_POSITION.
2498 *
2499 * <P>Each index column description has the following columns:
2500 * <OL>
2501 * <LI><B>TABLE_CAT</B> String {@code =>} table catalog (may be <code>null</code>)
2502 * <LI><B>TABLE_SCHEM</B> String {@code =>} table schema (may be <code>null</code>)
2503 * <LI><B>TABLE_NAME</B> String {@code =>} table name
2504 * <LI><B>NON_UNIQUE</B> boolean {@code =>} Can index values be non-unique.
2505 * false when TYPE is tableIndexStatistic
2506 * <LI><B>INDEX_QUALIFIER</B> String {@code =>} index catalog (may be <code>null</code>);
2507 * <code>null</code> when TYPE is tableIndexStatistic
2508 * <LI><B>INDEX_NAME</B> String {@code =>} index name; <code>null</code> when TYPE is
2509 * tableIndexStatistic
2510 * <LI><B>TYPE</B> short {@code =>} index type:
2511 * <UL>
2512 * <LI> tableIndexStatistic - this identifies table statistics that are
2513 * returned in conjunction with a table's index descriptions
2514 * <LI> tableIndexClustered - this is a clustered index
2515 * <LI> tableIndexHashed - this is a hashed index
2516 * <LI> tableIndexOther - this is some other style of index
2517 * </UL>
2518 * <LI><B>ORDINAL_POSITION</B> short {@code =>} column sequence number
2519 * within index; zero when TYPE is tableIndexStatistic
2520 * <LI><B>COLUMN_NAME</B> String {@code =>} column name; <code>null</code> when TYPE is
2521 * tableIndexStatistic
2522 * <LI><B>ASC_OR_DESC</B> String {@code =>} column sort sequence, "A" {@code =>} ascending,
2523 * "D" {@code =>} descending, may be <code>null</code> if sort sequence is not supported;
2524 * <code>null</code> when TYPE is tableIndexStatistic
2525 * <LI><B>CARDINALITY</B> long {@code =>} When TYPE is tableIndexStatistic, then
2526 * this is the number of rows in the table; otherwise, it is the
2527 * number of unique values in the index.
2528 * <LI><B>PAGES</B> long {@code =>} When TYPE is tableIndexStatistic then
2529 * this is the number of pages used for the table, otherwise it
2530 * is the number of pages used for the current index.
2531 * <LI><B>FILTER_CONDITION</B> String {@code =>} Filter condition, if any.
2532 * (may be <code>null</code>)
2533 * </OL>
2534 *
2535 * @param catalog a catalog name; must match the catalog name as it
2536 * is stored in this database; "" retrieves those without a catalog;
2537 * <code>null</code> means that the catalog name should not be used to narrow
2538 * the search
2539 * @param schema a schema name; must match the schema name
2540 * as it is stored in this database; "" retrieves those without a schema;
2541 * <code>null</code> means that the schema name should not be used to narrow
2542 * the search
2543 * @param table a table name; must match the table name as it is stored
2544 * in this database
2545 * @param unique when true, return only indices for unique values;
2546 * when false, return indices regardless of whether unique or not
2547 * @param approximate when true, result is allowed to reflect approximate
2548 * or out of data values; when false, results are requested to be
2549 * accurate
2550 * @return <code>ResultSet</code> - each row is an index column description
2551 * @exception SQLException if a database access error occurs
2552 */
2553 ResultSet getIndexInfo(String catalog, String schema, String table,
2554 boolean unique, boolean approximate)
2555 throws SQLException;
2556
2557 /**
2558 * Indicates that this column contains table statistics that
2559 * are returned in conjunction with a table's index descriptions.
2560 * <P>
2561 * A possible value for column <code>TYPE</code> in the
2562 * <code>ResultSet</code> object returned by the method
2563 * <code>getIndexInfo</code>.
2564 */
2565 short tableIndexStatistic = 0;
2566
2567 /**
2568 * Indicates that this table index is a clustered index.
2569 * <P>
2570 * A possible value for column <code>TYPE</code> in the
2571 * <code>ResultSet</code> object returned by the method
2572 * <code>getIndexInfo</code>.
2573 */
2574 short tableIndexClustered = 1;
2575
2576 /**
2577 * Indicates that this table index is a hashed index.
2578 * <P>
2579 * A possible value for column <code>TYPE</code> in the
2580 * <code>ResultSet</code> object returned by the method
2581 * <code>getIndexInfo</code>.
2582 */
2583 short tableIndexHashed = 2;
2584
2585 /**
2586 * Indicates that this table index is not a clustered
2587 * index, a hashed index, or table statistics;
2588 * it is something other than these.
2589 * <P>
2590 * A possible value for column <code>TYPE</code> in the
2591 * <code>ResultSet</code> object returned by the method
2592 * <code>getIndexInfo</code>.
2593 */
2594 short tableIndexOther = 3;
2595
2596 //--------------------------JDBC 2.0-----------------------------
2597
2598 /**
2599 * Retrieves whether this database supports the given result set type.
2600 *
2601 * @param type defined in <code>java.sql.ResultSet</code>
2602 * @return <code>true</code> if so; <code>false</code> otherwise
2603 * @exception SQLException if a database access error occurs
2604 * @see Connection
2605 * @since 1.2
2606 */
2607 boolean supportsResultSetType(int type) throws SQLException;
2608
2609 /**
2610 * Retrieves whether this database supports the given concurrency type
2611 * in combination with the given result set type.
2612 *
2613 * @param type defined in <code>java.sql.ResultSet</code>
2614 * @param concurrency type defined in <code>java.sql.ResultSet</code>
2615 * @return <code>true</code> if so; <code>false</code> otherwise
2616 * @exception SQLException if a database access error occurs
2617 * @see Connection
2618 * @since 1.2
2619 */
2620 boolean supportsResultSetConcurrency(int type, int concurrency)
2621 throws SQLException;
2622
2623 /**
2624 *
2625 * Retrieves whether for the given type of <code>ResultSet</code> object,
2626 * the result set's own updates are visible.
2627 *
2628 * @param type the <code>ResultSet</code> type; one of
2629 * <code>ResultSet.TYPE_FORWARD_ONLY</code>,
2630 * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
2631 * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
2632 * @return <code>true</code> if updates are visible for the given result set type;
2633 * <code>false</code> otherwise
2634 * @exception SQLException if a database access error occurs
2635 * @since 1.2
2636 */
2637 boolean ownUpdatesAreVisible(int type) throws SQLException;
2638
2639 /**
2640 * Retrieves whether a result set's own deletes are visible.
2641 *
2642 * @param type the <code>ResultSet</code> type; one of
2643 * <code>ResultSet.TYPE_FORWARD_ONLY</code>,
2644 * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
2645 * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
2646 * @return <code>true</code> if deletes are visible for the given result set type;
2647 * <code>false</code> otherwise
2648 * @exception SQLException if a database access error occurs
2649 * @since 1.2
2650 */
2651 boolean ownDeletesAreVisible(int type) throws SQLException;
2652
2653 /**
2654 * Retrieves whether a result set's own inserts are visible.
2655 *
2656 * @param type the <code>ResultSet</code> type; one of
2657 * <code>ResultSet.TYPE_FORWARD_ONLY</code>,
2658 * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
2659 * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
2660 * @return <code>true</code> if inserts are visible for the given result set type;
2661 * <code>false</code> otherwise
2662 * @exception SQLException if a database access error occurs
2663 * @since 1.2
2664 */
2665 boolean ownInsertsAreVisible(int type) throws SQLException;
2666
2667 /**
2668 * Retrieves whether updates made by others are visible.
2669 *
2670 * @param type the <code>ResultSet</code> type; one of
2671 * <code>ResultSet.TYPE_FORWARD_ONLY</code>,
2672 * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
2673 * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
2674 * @return <code>true</code> if updates made by others
2675 * are visible for the given result set type;
2676 * <code>false</code> otherwise
2677 * @exception SQLException if a database access error occurs
2678 * @since 1.2
2679 */
2680 boolean othersUpdatesAreVisible(int type) throws SQLException;
2681
2682 /**
2683 * Retrieves whether deletes made by others are visible.
2684 *
2685 * @param type the <code>ResultSet</code> type; one of
2686 * <code>ResultSet.TYPE_FORWARD_ONLY</code>,
2687 * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
2688 * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
2689 * @return <code>true</code> if deletes made by others
2690 * are visible for the given result set type;
2691 * <code>false</code> otherwise
2692 * @exception SQLException if a database access error occurs
2693 * @since 1.2
2694 */
2695 boolean othersDeletesAreVisible(int type) throws SQLException;
2696
2697 /**
2698 * Retrieves whether inserts made by others are visible.
2699 *
2700 * @param type the <code>ResultSet</code> type; one of
2701 * <code>ResultSet.TYPE_FORWARD_ONLY</code>,
2702 * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
2703 * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
2704 * @return <code>true</code> if inserts made by others
2705 * are visible for the given result set type;
2706 * <code>false</code> otherwise
2707 * @exception SQLException if a database access error occurs
2708 * @since 1.2
2709 */
2710 boolean othersInsertsAreVisible(int type) throws SQLException;
2711
2712 /**
2713 * Retrieves whether or not a visible row update can be detected by
2714 * calling the method <code>ResultSet.rowUpdated</code>.
2715 *
2716 * @param type the <code>ResultSet</code> type; one of
2717 * <code>ResultSet.TYPE_FORWARD_ONLY</code>,
2718 * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
2719 * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
2720 * @return <code>true</code> if changes are detected by the result set type;
2721 * <code>false</code> otherwise
2722 * @exception SQLException if a database access error occurs
2723 * @since 1.2
2724 */
2725 boolean updatesAreDetected(int type) throws SQLException;
2726
2727 /**
2728 * Retrieves whether or not a visible row delete can be detected by
2729 * calling the method <code>ResultSet.rowDeleted</code>. If the method
2730 * <code>deletesAreDetected</code> returns <code>false</code>, it means that
2731 * deleted rows are removed from the result set.
2732 *
2733 * @param type the <code>ResultSet</code> type; one of
2734 * <code>ResultSet.TYPE_FORWARD_ONLY</code>,
2735 * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
2736 * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
2737 * @return <code>true</code> if deletes are detected by the given result set type;
2738 * <code>false</code> otherwise
2739 * @exception SQLException if a database access error occurs
2740 * @since 1.2
2741 */
2742 boolean deletesAreDetected(int type) throws SQLException;
2743
2744 /**
2745 * Retrieves whether or not a visible row insert can be detected
2746 * by calling the method <code>ResultSet.rowInserted</code>.
2747 *
2748 * @param type the <code>ResultSet</code> type; one of
2749 * <code>ResultSet.TYPE_FORWARD_ONLY</code>,
2750 * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
2751 * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
2752 * @return <code>true</code> if changes are detected by the specified result
2753 * set type; <code>false</code> otherwise
2754 * @exception SQLException if a database access error occurs
2755 * @since 1.2
2756 */
2757 boolean insertsAreDetected(int type) throws SQLException;
2758
2759 /**
2760 * Retrieves whether this database supports batch updates.
2761 *
2762 * @return <code>true</code> if this database supports batch updates;
2763 * <code>false</code> otherwise
2764 * @exception SQLException if a database access error occurs
2765 * @since 1.2
2766 */
2767 boolean supportsBatchUpdates() throws SQLException;
2768
2769 /**
2770 * Retrieves a description of the user-defined types (UDTs) defined
2771 * in a particular schema. Schema-specific UDTs may have type
2772 * <code>JAVA_OBJECT</code>, <code>STRUCT</code>,
2773 * or <code>DISTINCT</code>.
2774 *
2775 * <P>Only types matching the catalog, schema, type name and type
2776 * criteria are returned. They are ordered by <code>DATA_TYPE</code>,
2777 * <code>TYPE_CAT</code>, <code>TYPE_SCHEM</code> and
2778 * <code>TYPE_NAME</code>. The type name parameter may be a fully-qualified
2779 * name. In this case, the catalog and schemaPattern parameters are
2780 * ignored.
2781 *
2782 * <P>Each type description has the following columns:
2783 * <OL>
2784 * <LI><B>TYPE_CAT</B> String {@code =>} the type's catalog (may be <code>null</code>)
2785 * <LI><B>TYPE_SCHEM</B> String {@code =>} type's schema (may be <code>null</code>)
2786 * <LI><B>TYPE_NAME</B> String {@code =>} type name
2787 * <LI><B>CLASS_NAME</B> String {@code =>} Java class name
2788 * <LI><B>DATA_TYPE</B> int {@code =>} type value defined in java.sql.Types.
2789 * One of JAVA_OBJECT, STRUCT, or DISTINCT
2790 * <LI><B>REMARKS</B> String {@code =>} explanatory comment on the type
2791 * <LI><B>BASE_TYPE</B> short {@code =>} type code of the source type of a
2792 * DISTINCT type or the type that implements the user-generated
2793 * reference type of the SELF_REFERENCING_COLUMN of a structured
2794 * type as defined in java.sql.Types (<code>null</code> if DATA_TYPE is not
2795 * DISTINCT or not STRUCT with REFERENCE_GENERATION = USER_DEFINED)
2796 * </OL>
2797 *
2798 * <P><B>Note:</B> If the driver does not support UDTs, an empty
2799 * result set is returned.
2800 *
2801 * @param catalog a catalog name; must match the catalog name as it
2802 * is stored in the database; "" retrieves those without a catalog;
2803 * <code>null</code> means that the catalog name should not be used to narrow
2804 * the search
2805 * @param schemaPattern a schema pattern name; must match the schema name
2806 * as it is stored in the database; "" retrieves those without a schema;
2807 * <code>null</code> means that the schema name should not be used to narrow
2808 * the search
2809 * @param typeNamePattern a type name pattern; must match the type name
2810 * as it is stored in the database; may be a fully qualified name
2811 * @param types a list of user-defined types (JAVA_OBJECT,
2812 * STRUCT, or DISTINCT) to include; <code>null</code> returns all types
2813 * @return <code>ResultSet</code> object in which each row describes a UDT
2814 * @exception SQLException if a database access error occurs
2815 * @see #getSearchStringEscape
2816 * @since 1.2
2817 */
2818 ResultSet getUDTs(String catalog, String schemaPattern,
2819 String typeNamePattern, int[] types)
2820 throws SQLException;
2821
2822 /**
2823 * Retrieves the connection that produced this metadata object.
2824 *
2825 * @return the connection that produced this metadata object
2826 * @exception SQLException if a database access error occurs
2827 * @since 1.2
2828 */
2829 Connection getConnection() throws SQLException;
2830
2831 // ------------------- JDBC 3.0 -------------------------
2832
2833 /**
2834 * Retrieves whether this database supports savepoints.
2835 *
2836 * @return <code>true</code> if savepoints are supported;
2837 * <code>false</code> otherwise
2838 * @exception SQLException if a database access error occurs
2839 * @since 1.4
2840 */
2841 boolean supportsSavepoints() throws SQLException;
2842
2843 /**
2844 * Retrieves whether this database supports named parameters to callable
2845 * statements.
2846 *
2847 * @return <code>true</code> if named parameters are supported;
2848 * <code>false</code> otherwise
2849 * @exception SQLException if a database access error occurs
2850 * @since 1.4
2851 */
2852 boolean supportsNamedParameters() throws SQLException;
2853
2854 /**
2855 * Retrieves whether it is possible to have multiple <code>ResultSet</code> objects
2856 * returned from a <code>CallableStatement</code> object
2857 * simultaneously.
2858 *
2859 * @return <code>true</code> if a <code>CallableStatement</code> object
2860 * can return multiple <code>ResultSet</code> objects
2861 * simultaneously; <code>false</code> otherwise
2862 * @exception SQLException if a database access error occurs
2863 * @since 1.4
2864 */
2865 boolean supportsMultipleOpenResults() throws SQLException;
2866
2867 /**
2868 * Retrieves whether auto-generated keys can be retrieved after
2869 * a statement has been executed
2870 *
2871 * @return <code>true</code> if auto-generated keys can be retrieved
2872 * after a statement has executed; <code>false</code> otherwise
2873 * <p>If <code>true</code> is returned, the JDBC driver must support the
2874 * returning of auto-generated keys for at least SQL INSERT statements
2875 *
2876 * @exception SQLException if a database access error occurs
2877 * @since 1.4
2878 */
2879 boolean supportsGetGeneratedKeys() throws SQLException;
2880
2881 /**
2882 * Retrieves a description of the user-defined type (UDT) hierarchies defined in a
2883 * particular schema in this database. Only the immediate super type/
2884 * sub type relationship is modeled.
2885 * <P>
2886 * Only supertype information for UDTs matching the catalog,
2887 * schema, and type name is returned. The type name parameter
2888 * may be a fully-qualified name. When the UDT name supplied is a
2889 * fully-qualified name, the catalog and schemaPattern parameters are
2890 * ignored.
2891 * <P>
2892 * If a UDT does not have a direct super type, it is not listed here.
2893 * A row of the <code>ResultSet</code> object returned by this method
2894 * describes the designated UDT and a direct supertype. A row has the following
2895 * columns:
2896 * <OL>
2897 * <LI><B>TYPE_CAT</B> String {@code =>} the UDT's catalog (may be <code>null</code>)
2898 * <LI><B>TYPE_SCHEM</B> String {@code =>} UDT's schema (may be <code>null</code>)
2899 * <LI><B>TYPE_NAME</B> String {@code =>} type name of the UDT
2900 * <LI><B>SUPERTYPE_CAT</B> String {@code =>} the direct super type's catalog
2901 * (may be <code>null</code>)
2902 * <LI><B>SUPERTYPE_SCHEM</B> String {@code =>} the direct super type's schema
2903 * (may be <code>null</code>)
2904 * <LI><B>SUPERTYPE_NAME</B> String {@code =>} the direct super type's name
2905 * </OL>
2906 *
2907 * <P><B>Note:</B> If the driver does not support type hierarchies, an
2908 * empty result set is returned.
2909 *
2910 * @param catalog a catalog name; "" retrieves those without a catalog;
2911 * <code>null</code> means drop catalog name from the selection criteria
2912 * @param schemaPattern a schema name pattern; "" retrieves those
2913 * without a schema
2914 * @param typeNamePattern a UDT name pattern; may be a fully-qualified
2915 * name
2916 * @return a <code>ResultSet</code> object in which a row gives information
2917 * about the designated UDT
2918 * @throws SQLException if a database access error occurs
2919 * @see #getSearchStringEscape
2920 * @since 1.4
2921 */
2922 ResultSet getSuperTypes(String catalog, String schemaPattern,
2923 String typeNamePattern) throws SQLException;
2924
2925 /**
2926 * Retrieves a description of the table hierarchies defined in a particular
2927 * schema in this database.
2928 *
2929 * <P>Only supertable information for tables matching the catalog, schema
2930 * and table name are returned. The table name parameter may be a fully-
2931 * qualified name, in which case, the catalog and schemaPattern parameters
2932 * are ignored. If a table does not have a super table, it is not listed here.
2933 * Supertables have to be defined in the same catalog and schema as the
2934 * sub tables. Therefore, the type description does not need to include
2935 * this information for the supertable.
2936 *
2937 * <P>Each type description has the following columns:
2938 * <OL>
2939 * <LI><B>TABLE_CAT</B> String {@code =>} the type's catalog (may be <code>null</code>)
2940 * <LI><B>TABLE_SCHEM</B> String {@code =>} type's schema (may be <code>null</code>)
2941 * <LI><B>TABLE_NAME</B> String {@code =>} type name
2942 * <LI><B>SUPERTABLE_NAME</B> String {@code =>} the direct super type's name
2943 * </OL>
2944 *
2945 * <P><B>Note:</B> If the driver does not support type hierarchies, an
2946 * empty result set is returned.
2947 *
2948 * @param catalog a catalog name; "" retrieves those without a catalog;
2949 * <code>null</code> means drop catalog name from the selection criteria
2950 * @param schemaPattern a schema name pattern; "" retrieves those
2951 * without a schema
2952 * @param tableNamePattern a table name pattern; may be a fully-qualified
2953 * name
2954 * @return a <code>ResultSet</code> object in which each row is a type description
2955 * @throws SQLException if a database access error occurs
2956 * @see #getSearchStringEscape
2957 * @since 1.4
2958 */
2959 ResultSet getSuperTables(String catalog, String schemaPattern,
2960 String tableNamePattern) throws SQLException;
2961
2962 /**
2963 * Indicates that <code>NULL</code> values might not be allowed.
2964 * <P>
2965 * A possible value for the column
2966 * <code>NULLABLE</code> in the <code>ResultSet</code> object
2967 * returned by the method <code>getAttributes</code>.
2968 */
2969 short attributeNoNulls = 0;
2970
2971 /**
2972 * Indicates that <code>NULL</code> values are definitely allowed.
2973 * <P>
2974 * A possible value for the column <code>NULLABLE</code>
2975 * in the <code>ResultSet</code> object
2976 * returned by the method <code>getAttributes</code>.
2977 */
2978 short attributeNullable = 1;
2979
2980 /**
2981 * Indicates that whether <code>NULL</code> values are allowed is not
2982 * known.
2983 * <P>
2984 * A possible value for the column <code>NULLABLE</code>
2985 * in the <code>ResultSet</code> object
2986 * returned by the method <code>getAttributes</code>.
2987 */
2988 short attributeNullableUnknown = 2;
2989
2990 /**
2991 * Retrieves a description of the given attribute of the given type
2992 * for a user-defined type (UDT) that is available in the given schema
2993 * and catalog.
2994 * <P>
2995 * Descriptions are returned only for attributes of UDTs matching the
2996 * catalog, schema, type, and attribute name criteria. They are ordered by
2997 * <code>TYPE_CAT</code>, <code>TYPE_SCHEM</code>,
2998 * <code>TYPE_NAME</code> and <code>ORDINAL_POSITION</code>. This description
2999 * does not contain inherited attributes.
3000 * <P>
3001 * The <code>ResultSet</code> object that is returned has the following
3002 * columns:
3003 * <OL>
3004 * <LI><B>TYPE_CAT</B> String {@code =>} type catalog (may be <code>null</code>)
3005 * <LI><B>TYPE_SCHEM</B> String {@code =>} type schema (may be <code>null</code>)
3006 * <LI><B>TYPE_NAME</B> String {@code =>} type name
3007 * <LI><B>ATTR_NAME</B> String {@code =>} attribute name
3008 * <LI><B>DATA_TYPE</B> int {@code =>} attribute type SQL type from java.sql.Types
3009 * <LI><B>ATTR_TYPE_NAME</B> String {@code =>} Data source dependent type name.
3010 * For a UDT, the type name is fully qualified. For a REF, the type name is
3011 * fully qualified and represents the target type of the reference type.
3012 * <LI><B>ATTR_SIZE</B> int {@code =>} column size. For char or date
3013 * types this is the maximum number of characters; for numeric or
3014 * decimal types this is precision.
3015 * <LI><B>DECIMAL_DIGITS</B> int {@code =>} the number of fractional digits. Null is returned for data types where
3016 * DECIMAL_DIGITS is not applicable.
3017 * <LI><B>NUM_PREC_RADIX</B> int {@code =>} Radix (typically either 10 or 2)
3018 * <LI><B>NULLABLE</B> int {@code =>} whether NULL is allowed
3019 * <UL>
3020 * <LI> attributeNoNulls - might not allow NULL values
3021 * <LI> attributeNullable - definitely allows NULL values
3022 * <LI> attributeNullableUnknown - nullability unknown
3023 * </UL>
3024 * <LI><B>REMARKS</B> String {@code =>} comment describing column (may be <code>null</code>)
3025 * <LI><B>ATTR_DEF</B> String {@code =>} default value (may be <code>null</code>)
3026 * <LI><B>SQL_DATA_TYPE</B> int {@code =>} unused
3027 * <LI><B>SQL_DATETIME_SUB</B> int {@code =>} unused
3028 * <LI><B>CHAR_OCTET_LENGTH</B> int {@code =>} for char types the
3029 * maximum number of bytes in the column
3030 * <LI><B>ORDINAL_POSITION</B> int {@code =>} index of the attribute in the UDT
3031 * (starting at 1)
3032 * <LI><B>IS_NULLABLE</B> String {@code =>} ISO rules are used to determine
3033 * the nullability for a attribute.
3034 * <UL>
3035 * <LI> YES --- if the attribute can include NULLs
3036 * <LI> NO --- if the attribute cannot include NULLs
3037 * <LI> empty string --- if the nullability for the
3038 * attribute is unknown
3039 * </UL>
3040 * <LI><B>SCOPE_CATALOG</B> String {@code =>} catalog of table that is the
3041 * scope of a reference attribute (<code>null</code> if DATA_TYPE isn't REF)
3042 * <LI><B>SCOPE_SCHEMA</B> String {@code =>} schema of table that is the
3043 * scope of a reference attribute (<code>null</code> if DATA_TYPE isn't REF)
3044 * <LI><B>SCOPE_TABLE</B> String {@code =>} table name that is the scope of a
3045 * reference attribute (<code>null</code> if the DATA_TYPE isn't REF)
3046 * <LI><B>SOURCE_DATA_TYPE</B> short {@code =>} source type of a distinct type or user-generated
3047 * Ref type,SQL type from java.sql.Types (<code>null</code> if DATA_TYPE
3048 * isn't DISTINCT or user-generated REF)
3049 * </OL>
3050 * @param catalog a catalog name; must match the catalog name as it
3051 * is stored in the database; "" retrieves those without a catalog;
3052 * <code>null</code> means that the catalog name should not be used to narrow
3053 * the search
3054 * @param schemaPattern a schema name pattern; must match the schema name
3055 * as it is stored in the database; "" retrieves those without a schema;
3056 * <code>null</code> means that the schema name should not be used to narrow
3057 * the search
3058 * @param typeNamePattern a type name pattern; must match the
3059 * type name as it is stored in the database
3060 * @param attributeNamePattern an attribute name pattern; must match the attribute
3061 * name as it is declared in the database
3062 * @return a <code>ResultSet</code> object in which each row is an
3063 * attribute description
3064 * @exception SQLException if a database access error occurs
3065 * @see #getSearchStringEscape
3066 * @since 1.4
3067 */
3068 ResultSet getAttributes(String catalog, String schemaPattern,
3069 String typeNamePattern, String attributeNamePattern)
3070 throws SQLException;
3071
3072 /**
3073 * Retrieves whether this database supports the given result set holdability.
3074 *
3075 * @param holdability one of the following constants:
3076 * <code>ResultSet.HOLD_CURSORS_OVER_COMMIT</code> or
3077 * <code>ResultSet.CLOSE_CURSORS_AT_COMMIT</code>
3078 * @return <code>true</code> if so; <code>false</code> otherwise
3079 * @exception SQLException if a database access error occurs
3080 * @see Connection
3081 * @since 1.4
3082 */
3083 boolean supportsResultSetHoldability(int holdability) throws SQLException;
3084
3085 /**
3086 * Retrieves this database's default holdability for <code>ResultSet</code>
3087 * objects.
3088 *
3089 * @return the default holdability; either
3090 * <code>ResultSet.HOLD_CURSORS_OVER_COMMIT</code> or
3091 * <code>ResultSet.CLOSE_CURSORS_AT_COMMIT</code>
3092 * @exception SQLException if a database access error occurs
3093 * @since 1.4
3094 */
3095 int getResultSetHoldability() throws SQLException;
3096
3097 /**
3098 * Retrieves the major version number of the underlying database.
3099 *
3100 * @return the underlying database's major version
3101 * @exception SQLException if a database access error occurs
3102 * @since 1.4
3103 */
3104 int getDatabaseMajorVersion() throws SQLException;
3105
3106 /**
3107 * Retrieves the minor version number of the underlying database.
3108 *
3109 * @return underlying database's minor version
3110 * @exception SQLException if a database access error occurs
3111 * @since 1.4
3112 */
3113 int getDatabaseMinorVersion() throws SQLException;
3114
3115 /**
3116 * Retrieves the major JDBC version number for this
3117 * driver.
3118 *
3119 * @return JDBC version major number
3120 * @exception SQLException if a database access error occurs
3121 * @since 1.4
3122 */
3123 int getJDBCMajorVersion() throws SQLException;
3124
3125 /**
3126 * Retrieves the minor JDBC version number for this
3127 * driver.
3128 *
3129 * @return JDBC version minor number
3130 * @exception SQLException if a database access error occurs
3131 * @since 1.4
3132 */
3133 int getJDBCMinorVersion() throws SQLException;
3134
3135 /**
3136 * A possible return value for the method
3137 * <code>DatabaseMetaData.getSQLStateType</code> which is used to indicate
3138 * whether the value returned by the method
3139 * <code>SQLException.getSQLState</code> is an
3140 * X/Open (now know as Open Group) SQL CLI SQLSTATE value.
3141 *
3142 * @since 1.4
3143 */
3144 int sqlStateXOpen = 1;
3145
3146 /**
3147 * A possible return value for the method
3148 * <code>DatabaseMetaData.getSQLStateType</code> which is used to indicate
3149 * whether the value returned by the method
3150 * <code>SQLException.getSQLState</code> is an SQLSTATE value.
3151 *
3152 * @since 1.6
3153 */
3154 int sqlStateSQL = 2;
3155
3156 /**
3157 * A possible return value for the method
3158 * <code>DatabaseMetaData.getSQLStateType</code> which is used to indicate
3159 * whether the value returned by the method
3160 * <code>SQLException.getSQLState</code> is an SQL99 SQLSTATE value.
3161 * <P>
3162 * <b>Note:</b>This constant remains only for compatibility reasons. Developers
3163 * should use the constant <code>sqlStateSQL</code> instead.
3164 *
3165 * @since 1.4
3166 */
3167 int sqlStateSQL99 = sqlStateSQL;
3168
3169 /**
3170 * Indicates whether the SQLSTATE returned by <code>SQLException.getSQLState</code>
3171 * is X/Open (now known as Open Group) SQL CLI or SQL:2003.
3172 * @return the type of SQLSTATE; one of:
3173 * sqlStateXOpen or
3174 * sqlStateSQL
3175 * @throws SQLException if a database access error occurs
3176 * @since 1.4
3177 */
3178 int getSQLStateType() throws SQLException;
3179
3180 /**
3181 * Indicates whether updates made to a LOB are made on a copy or directly
3182 * to the LOB.
3183 * @return <code>true</code> if updates are made to a copy of the LOB;
3184 * <code>false</code> if updates are made directly to the LOB
3185 * @throws SQLException if a database access error occurs
3186 * @since 1.4
3187 */
3188 boolean locatorsUpdateCopy() throws SQLException;
3189
3190 /**
3191 * Retrieves whether this database supports statement pooling.
3192 *
3193 * @return <code>true</code> if so; <code>false</code> otherwise
3194 * @throws SQLException if a database access error occurs
3195 * @since 1.4
3196 */
3197 boolean supportsStatementPooling() throws SQLException;
3198
3199 //------------------------- JDBC 4.0 -----------------------------------
3200
3201 /**
3202 * Indicates whether this data source supports the SQL {@code ROWID} type,
3203 * and the lifetime for which a {@link RowId} object remains valid.
3204 *
3205 * @return the status indicating the lifetime of a {@code RowId}
3206 * @throws SQLException if a database access error occurs
3207 * @since 1.6
3208 */
3209 RowIdLifetime getRowIdLifetime() throws SQLException;
3210
3211 /**
3212 * Retrieves the schema names available in this database. The results
3213 * are ordered by <code>TABLE_CATALOG</code> and
3214 * <code>TABLE_SCHEM</code>.
3215 *
3216 * <P>The schema columns are:
3217 * <OL>
3218 * <LI><B>TABLE_SCHEM</B> String {@code =>} schema name
3219 * <LI><B>TABLE_CATALOG</B> String {@code =>} catalog name (may be <code>null</code>)
3220 * </OL>
3221 *
3222 *
3223 * @param catalog a catalog name; must match the catalog name as it is stored
3224 * in the database;"" retrieves those without a catalog; null means catalog
3225 * name should not be used to narrow down the search.
3226 * @param schemaPattern a schema name; must match the schema name as it is
3227 * stored in the database; null means
3228 * schema name should not be used to narrow down the search.
3229 * @return a <code>ResultSet</code> object in which each row is a
3230 * schema description
3231 * @exception SQLException if a database access error occurs
3232 * @see #getSearchStringEscape
3233 * @since 1.6
3234 */
3235 ResultSet getSchemas(String catalog, String schemaPattern) throws SQLException;
3236
3237 /**
3238 * Retrieves whether this database supports invoking user-defined or vendor functions
3239 * using the stored procedure escape syntax.
3240 *
3241 * @return <code>true</code> if so; <code>false</code> otherwise
3242 * @exception SQLException if a database access error occurs
3243 * @since 1.6
3244 */
3245 boolean supportsStoredFunctionsUsingCallSyntax() throws SQLException;
3246
3247 /**
3248 * Retrieves whether a <code>SQLException</code> while autoCommit is <code>true</code> indicates
3249 * that all open ResultSets are closed, even ones that are holdable. When a <code>SQLException</code> occurs while
3250 * autocommit is <code>true</code>, it is vendor specific whether the JDBC driver responds with a commit operation, a
3251 * rollback operation, or by doing neither a commit nor a rollback. A potential result of this difference
3252 * is in whether or not holdable ResultSets are closed.
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 */
3258 boolean autoCommitFailureClosesAllResultSets() throws SQLException;
3259 /**
3260 * Retrieves a list of the client info properties
3261 * that the driver supports. The result set contains the following columns
3262 *
3263 * <ol>
3264 * <li><b>NAME</b> String{@code =>} The name of the client info property<br>
3265 * <li><b>MAX_LEN</b> int{@code =>} The maximum length of the value for the property<br>
3266 * <li><b>DEFAULT_VALUE</b> String{@code =>} The default value of the property<br>
3267 * <li><b>DESCRIPTION</b> String{@code =>} A description of the property. This will typically
3268 * contain information as to where this property is
3269 * stored in the database.
3270 * </ol>
3271 * <p>
3272 * The <code>ResultSet</code> is sorted by the NAME column
3273 *
3274 * @return A <code>ResultSet</code> object; each row is a supported client info
3275 * property
3276 *
3277 * @exception SQLException if a database access error occurs
3278 *
3279 * @since 1.6
3280 */
3281 ResultSet getClientInfoProperties()
3282 throws SQLException;
3283
3284 /**
3285 * Retrieves a description of the system and user functions available
3286 * in the given catalog.
3287 * <P>
3288 * Only system and user function descriptions matching the schema and
3289 * function name criteria are returned. They are ordered by
3290 * <code>FUNCTION_CAT</code>, <code>FUNCTION_SCHEM</code>,
3291 * <code>FUNCTION_NAME</code> and
3292 * <code>SPECIFIC_ NAME</code>.
3293 *
3294 * <P>Each function description has the following columns:
3295 * <OL>
3296 * <LI><B>FUNCTION_CAT</B> String {@code =>} function catalog (may be <code>null</code>)
3297 * <LI><B>FUNCTION_SCHEM</B> String {@code =>} function schema (may be <code>null</code>)
3298 * <LI><B>FUNCTION_NAME</B> String {@code =>} function name. This is the name
3299 * used to invoke the function
3300 * <LI><B>REMARKS</B> String {@code =>} explanatory comment on the function
3301 * <LI><B>FUNCTION_TYPE</B> short {@code =>} kind of function:
3302 * <UL>
3303 * <LI>functionResultUnknown - Cannot determine if a return value
3304 * or table will be returned
3305 * <LI> functionNoTable- Does not return a table
3306 * <LI> functionReturnsTable - Returns a table
3307 * </UL>
3308 * <LI><B>SPECIFIC_NAME</B> String {@code =>} the name which uniquely identifies
3309 * this function within its schema. This is a user specified, or DBMS
3310 * generated, name that may be different then the <code>FUNCTION_NAME</code>
3311 * for example with overload functions
3312 * </OL>
3313 * <p>
3314 * A user may not have permission to execute any of the functions that are
3315 * returned by <code>getFunctions</code>
3316 *
3317 * @param catalog a catalog name; must match the catalog name as it
3318 * is stored in the database; "" retrieves those without a catalog;
3319 * <code>null</code> means that the catalog name should not be used to narrow
3320 * the search
3321 * @param schemaPattern a schema name pattern; must match the schema name
3322 * as it is stored in the database; "" retrieves those without a schema;
3323 * <code>null</code> means that the schema name should not be used to narrow
3324 * the search
3325 * @param functionNamePattern a function name pattern; must match the
3326 * function name as it is stored in the database
3327 * @return <code>ResultSet</code> - each row is a function description
3328 * @exception SQLException if a database access error occurs
3329 * @see #getSearchStringEscape
3330 * @since 1.6
3331 */
3332 ResultSet getFunctions(String catalog, String schemaPattern,
3333 String functionNamePattern) throws SQLException;
3334 /**
3335 * Retrieves a description of the given catalog's system or user
3336 * function parameters and return type.
3337 *
3338 * <P>Only descriptions matching the schema, function and
3339 * parameter name criteria are returned. They are ordered by
3340 * <code>FUNCTION_CAT</code>, <code>FUNCTION_SCHEM</code>,
3341 * <code>FUNCTION_NAME</code> and
3342 * <code>SPECIFIC_ NAME</code>. Within this, the return value,
3343 * if any, is first. Next are the parameter descriptions in call
3344 * order. The column descriptions follow in column number order.
3345 *
3346 * <P>Each row in the <code>ResultSet</code>
3347 * is a parameter description, column description or
3348 * return type description with the following fields:
3349 * <OL>
3350 * <LI><B>FUNCTION_CAT</B> String {@code =>} function catalog (may be <code>null</code>)
3351 * <LI><B>FUNCTION_SCHEM</B> String {@code =>} function schema (may be <code>null</code>)
3352 * <LI><B>FUNCTION_NAME</B> String {@code =>} function name. This is the name
3353 * used to invoke the function
3354 * <LI><B>COLUMN_NAME</B> String {@code =>} column/parameter name
3355 * <LI><B>COLUMN_TYPE</B> Short {@code =>} kind of column/parameter:
3356 * <UL>
3357 * <LI> functionColumnUnknown - nobody knows
3358 * <LI> functionColumnIn - IN parameter
3359 * <LI> functionColumnInOut - INOUT parameter
3360 * <LI> functionColumnOut - OUT parameter
3361 * <LI> functionColumnReturn - function return value
3362 * <LI> functionColumnResult - Indicates that the parameter or column
3363 * is a column in the <code>ResultSet</code>
3364 * </UL>
3365 * <LI><B>DATA_TYPE</B> int {@code =>} SQL type from java.sql.Types
3366 * <LI><B>TYPE_NAME</B> String {@code =>} SQL type name, for a UDT type the
3367 * type name is fully qualified
3368 * <LI><B>PRECISION</B> int {@code =>} precision
3369 * <LI><B>LENGTH</B> int {@code =>} length in bytes of data
3370 * <LI><B>SCALE</B> short {@code =>} scale - null is returned for data types where
3371 * SCALE is not applicable.
3372 * <LI><B>RADIX</B> short {@code =>} radix
3373 * <LI><B>NULLABLE</B> short {@code =>} can it contain NULL.
3374 * <UL>
3375 * <LI> functionNoNulls - does not allow NULL values
3376 * <LI> functionNullable - allows NULL values
3377 * <LI> functionNullableUnknown - nullability unknown
3378 * </UL>
3379 * <LI><B>REMARKS</B> String {@code =>} comment describing column/parameter
3380 * <LI><B>CHAR_OCTET_LENGTH</B> int {@code =>} the maximum length of binary
3381 * and character based parameters or columns. For any other datatype the returned value
3382 * is a NULL
3383 * <LI><B>ORDINAL_POSITION</B> int {@code =>} the ordinal position, starting
3384 * from 1, for the input and output parameters. A value of 0
3385 * is returned if this row describes the function's return value.
3386 * For result set columns, it is the
3387 * ordinal position of the column in the result set starting from 1.
3388 * <LI><B>IS_NULLABLE</B> String {@code =>} ISO rules are used to determine
3389 * the nullability for a parameter or column.
3390 * <UL>
3391 * <LI> YES --- if the parameter or column can include NULLs
3392 * <LI> NO --- if the parameter or column cannot include NULLs
3393 * <LI> empty string --- if the nullability for the
3394 * parameter or column is unknown
3395 * </UL>
3396 * <LI><B>SPECIFIC_NAME</B> String {@code =>} the name which uniquely identifies
3397 * this function within its schema. This is a user specified, or DBMS
3398 * generated, name that may be different then the <code>FUNCTION_NAME</code>
3399 * for example with overload functions
3400 * </OL>
3401 *
3402 * <p>The PRECISION column represents the specified column size for the given
3403 * parameter or column.
3404 * For numeric data, this is the maximum precision. For character data, this is the length in characters.
3405 * For datetime datatypes, this is the length in characters of the String representation (assuming the
3406 * maximum allowed precision of the fractional seconds component). For binary data, this is the length in bytes. For the ROWID datatype,
3407 * this is the length in bytes. Null is returned for data types where the
3408 * column size is not applicable.
3409 * @param catalog a catalog name; must match the catalog name as it
3410 * is stored in the database; "" retrieves those without a catalog;
3411 * <code>null</code> means that the catalog name should not be used to narrow
3412 * the search
3413 * @param schemaPattern a schema name pattern; must match the schema name
3414 * as it is stored in the database; "" retrieves those without a schema;
3415 * <code>null</code> means that the schema name should not be used to narrow
3416 * the search
3417 * @param functionNamePattern a procedure name pattern; must match the
3418 * function name as it is stored in the database
3419 * @param columnNamePattern a parameter name pattern; must match the
3420 * parameter or column name as it is stored in the database
3421 * @return <code>ResultSet</code> - each row describes a
3422 * user function parameter, column or return type
3423 *
3424 * @exception SQLException if a database access error occurs
3425 * @see #getSearchStringEscape
3426 * @since 1.6
3427 */
3428 ResultSet getFunctionColumns(String catalog,
3429 String schemaPattern,
3430 String functionNamePattern,
3431 String columnNamePattern) throws SQLException;
3432
3433
3434 /**
3435 * Indicates that type of the parameter or column is unknown.
3436 * <P>
3437 * A possible value for the column
3438 * <code>COLUMN_TYPE</code>
3439 * in the <code>ResultSet</code>
3440 * returned by the method <code>getFunctionColumns</code>.
3441 */
3442 int functionColumnUnknown = 0;
3443
3444 /**
3445 * Indicates that the parameter or column is an IN parameter.
3446 * <P>
3447 * A possible value for the column
3448 * <code>COLUMN_TYPE</code>
3449 * in the <code>ResultSet</code>
3450 * returned by the method <code>getFunctionColumns</code>.
3451 * @since 1.6
3452 */
3453 int functionColumnIn = 1;
3454
3455 /**
3456 * Indicates that the parameter or column is an INOUT parameter.
3457 * <P>
3458 * A possible value for the column
3459 * <code>COLUMN_TYPE</code>
3460 * in the <code>ResultSet</code>
3461 * returned by the method <code>getFunctionColumns</code>.
3462 * @since 1.6
3463 */
3464 int functionColumnInOut = 2;
3465
3466 /**
3467 * Indicates that the parameter or column is an OUT parameter.
3468 * <P>
3469 * A possible value for the column
3470 * <code>COLUMN_TYPE</code>
3471 * in the <code>ResultSet</code>
3472 * returned by the method <code>getFunctionColumns</code>.
3473 * @since 1.6
3474 */
3475 int functionColumnOut = 3;
3476 /**
3477 * Indicates that the parameter or column is a return value.
3478 * <P>
3479 * A possible value for the column
3480 * <code>COLUMN_TYPE</code>
3481 * in the <code>ResultSet</code>
3482 * returned by the method <code>getFunctionColumns</code>.
3483 * @since 1.6
3484 */
3485 int functionReturn = 4;
3486
3487 /**
3488 * Indicates that the parameter or column is a column in a result set.
3489 * <P>
3490 * A possible value for the column
3491 * <code>COLUMN_TYPE</code>
3492 * in the <code>ResultSet</code>
3493 * returned by the method <code>getFunctionColumns</code>.
3494 * @since 1.6
3495 */
3496 int functionColumnResult = 5;
3497
3498
3499 /**
3500 * Indicates that <code>NULL</code> values are not allowed.
3501 * <P>
3502 * A possible value for the column
3503 * <code>NULLABLE</code>
3504 * in the <code>ResultSet</code> object
3505 * returned by the method <code>getFunctionColumns</code>.
3506 * @since 1.6
3507 */
3508 int functionNoNulls = 0;
3509
3510 /**
3511 * Indicates that <code>NULL</code> values are allowed.
3512 * <P>
3513 * A possible value for the column
3514 * <code>NULLABLE</code>
3515 * in the <code>ResultSet</code> object
3516 * returned by the method <code>getFunctionColumns</code>.
3517 * @since 1.6
3518 */
3519 int functionNullable = 1;
3520
3521 /**
3522 * Indicates that whether <code>NULL</code> values are allowed
3523 * is unknown.
3524 * <P>
3525 * A possible value for the column
3526 * <code>NULLABLE</code>
3527 * in the <code>ResultSet</code> object
3528 * returned by the method <code>getFunctionColumns</code>.
3529 * @since 1.6
3530 */
3531 int functionNullableUnknown = 2;
3532
3533 /**
3534 * Indicates that it is not known whether the function returns
3535 * a result or a table.
3536 * <P>
3537 * A possible value for column <code>FUNCTION_TYPE</code> in the
3538 * <code>ResultSet</code> object returned by the method
3539 * <code>getFunctions</code>.
3540 * @since 1.6
3541 */
3542 int functionResultUnknown = 0;
3543
3544 /**
3545 * Indicates that the function does not return a table.
3546 * <P>
3547 * A possible value for column <code>FUNCTION_TYPE</code> in the
3548 * <code>ResultSet</code> object returned by the method
3549 * <code>getFunctions</code>.
3550 * @since 1.6
3551 */
3552 int functionNoTable = 1;
3553
3554 /**
3555 * Indicates that the function returns a table.
3556 * <P>
3557 * A possible value for column <code>FUNCTION_TYPE</code> in the
3558 * <code>ResultSet</code> object returned by the method
3559 * <code>getFunctions</code>.
3560 * @since 1.6
3561 */
3562 int functionReturnsTable = 2;
3563
3564 //--------------------------JDBC 4.1 -----------------------------
3565
3566 /**
3567 * Retrieves a description of the pseudo or hidden columns available
3568 * in a given table within the specified catalog and schema.
3569 * Pseudo or hidden columns may not always be stored within
3570 * a table and are not visible in a ResultSet unless they are
3571 * specified in the query's outermost SELECT list. Pseudo or hidden
3572 * columns may not necessarily be able to be modified. If there are
3573 * no pseudo or hidden columns, an empty ResultSet is returned.
3574 *
3575 * <P>Only column descriptions matching the catalog, schema, table
3576 * and column name criteria are returned. They are ordered by
3577 * <code>TABLE_CAT</code>,<code>TABLE_SCHEM</code>, <code>TABLE_NAME</code>
3578 * and <code>COLUMN_NAME</code>.
3579 *
3580 * <P>Each column description has the following columns:
3581 * <OL>
3582 * <LI><B>TABLE_CAT</B> String {@code =>} table catalog (may be <code>null</code>)
3583 * <LI><B>TABLE_SCHEM</B> String {@code =>} table schema (may be <code>null</code>)
3584 * <LI><B>TABLE_NAME</B> String {@code =>} table name
3585 * <LI><B>COLUMN_NAME</B> String {@code =>} column name
3586 * <LI><B>DATA_TYPE</B> int {@code =>} SQL type from java.sql.Types
3587 * <LI><B>COLUMN_SIZE</B> int {@code =>} column size.
3588 * <LI><B>DECIMAL_DIGITS</B> int {@code =>} the number of fractional digits. Null is returned for data types where
3589 * DECIMAL_DIGITS is not applicable.
3590 * <LI><B>NUM_PREC_RADIX</B> int {@code =>} Radix (typically either 10 or 2)
3591 * <LI><B>COLUMN_USAGE</B> String {@code =>} The allowed usage for the column. The
3592 * value returned will correspond to the enum name returned by {@link PseudoColumnUsage#name PseudoColumnUsage.name()}
3593 * <LI><B>REMARKS</B> String {@code =>} comment describing column (may be <code>null</code>)
3594 * <LI><B>CHAR_OCTET_LENGTH</B> int {@code =>} for char types the
3595 * maximum number of bytes in the column
3596 * <LI><B>IS_NULLABLE</B> String {@code =>} ISO rules are used to determine the nullability for a column.
3597 * <UL>
3598 * <LI> YES --- if the column can include NULLs
3599 * <LI> NO --- if the column cannot include NULLs
3600 * <LI> empty string --- if the nullability for the column is unknown
3601 * </UL>
3602 * </OL>
3603 *
3604 * <p>The COLUMN_SIZE column specifies the column size for the given column.
3605 * For numeric data, this is the maximum precision. For character data, this is the length in characters.
3606 * For datetime datatypes, this is the length in characters of the String representation (assuming the
3607 * maximum allowed precision of the fractional seconds component). For binary data, this is the length in bytes. For the ROWID datatype,
3608 * this is the length in bytes. Null is returned for data types where the
3609 * column size is not applicable.
3610 *
3611 * @param catalog a catalog name; must match the catalog name as it
3612 * is stored in the database; "" retrieves those without a catalog;
3613 * <code>null</code> means that the catalog name should not be used to narrow
3614 * the search
3615 * @param schemaPattern a schema name pattern; must match the schema name
3616 * as it is stored in the database; "" retrieves those without a schema;
3617 * <code>null</code> means that the schema name should not be used to narrow
3618 * the search
3619 * @param tableNamePattern a table name pattern; must match the
3620 * table name as it is stored in the database
3621 * @param columnNamePattern a column name pattern; must match the column
3622 * name as it is stored in the database
3623 * @return <code>ResultSet</code> - each row is a column description
3624 * @exception SQLException if a database access error occurs
3625 * @see PseudoColumnUsage
3626 * @since 1.7
3627 */
3628 ResultSet getPseudoColumns(String catalog, String schemaPattern,
3629 String tableNamePattern, String columnNamePattern)
3630 throws SQLException;
3631
3632 /**
3633 * Retrieves whether a generated key will always be returned if the column
3634 * name(s) or index(es) specified for the auto generated key column(s)
3635 * are valid and the statement succeeds. The key that is returned may or
3636 * may not be based on the column(s) for the auto generated key.
3637 * Consult your JDBC driver documentation for additional details.
3638 * @return <code>true</code> if so; <code>false</code> otherwise
3639 * @exception SQLException if a database access error occurs
3640 * @since 1.7
3641 */
3642 boolean generatedKeyAlwaysReturned() throws SQLException;
3643
3644 //--------------------------JDBC 4.2 -----------------------------
3645
3646 /**
3647 *
3648 * Retrieves the maximum number of bytes this database allows for
3649 * the logical size for a {@code LOB}.
3650 *<p>
3651 * The default implementation will return {@code 0}
3652 *
3653 * @return the maximum number of bytes allowed; a result of zero
3654 * means that there is no limit or the limit is not known
3655 * @exception SQLException if a database access error occurs
3656 * @since 1.8
3657 */
3658 default long getMaxLogicalLobSize() throws SQLException {
3659 return 0;
3660 }
3661
3662 /**
3663 * Retrieves whether this database supports REF CURSOR.
3664 *<p>
3665 * The default implementation will return {@code false}
3666 *
3667 * @return {@code true} if this database supports REF CURSOR;
3668 * {@code false} otherwise
3669 * @exception SQLException if a database access error occurs
3670 * @since 1.8
3671 */
3672 default boolean supportsRefCursors() throws SQLException{
3673 return false;
3674 }
3675
3676 // JDBC 4.3
3677
3678 /**
3679 * Retrieves whether this database supports sharding.
3680 * @implSpec
3681 * The default implementation will return {@code false}
3682 *
3683 * @return {@code true} if this database supports sharding;
3684 * {@code false} otherwise
3685 * @exception SQLException if a database access error occurs
3686 * @since 9
3687 */
3688 default boolean supportsSharding() throws SQLException {
3689 return false;
3690 }
3691 }