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