Return-Path: Delivered-To: apmail-harmony-commits-archive@www.apache.org Received: (qmail 21836 invoked from network); 30 Apr 2009 09:46:12 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (140.211.11.3) by minotaur.apache.org with SMTP; 30 Apr 2009 09:46:12 -0000 Received: (qmail 44260 invoked by uid 500); 30 Apr 2009 09:46:12 -0000 Delivered-To: apmail-harmony-commits-archive@harmony.apache.org Received: (qmail 44205 invoked by uid 500); 30 Apr 2009 09:46:11 -0000 Mailing-List: contact commits-help@harmony.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@harmony.apache.org Delivered-To: mailing list commits@harmony.apache.org Received: (qmail 44196 invoked by uid 99); 30 Apr 2009 09:46:11 -0000 Received: from nike.apache.org (HELO nike.apache.org) (192.87.106.230) by apache.org (qpsmtpd/0.29) with ESMTP; Thu, 30 Apr 2009 09:46:11 +0000 X-ASF-Spam-Status: No, hits=-2000.0 required=10.0 tests=ALL_TRUSTED X-Spam-Check-By: apache.org Received: from [140.211.11.4] (HELO eris.apache.org) (140.211.11.4) by apache.org (qpsmtpd/0.29) with ESMTP; Thu, 30 Apr 2009 09:46:05 +0000 Received: by eris.apache.org (Postfix, from userid 65534) id D7A122388BEF; Thu, 30 Apr 2009 09:45:43 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r770130 [4/10] - in /harmony/enhanced/classlib/trunk/modules/sql/src/main/java: java/sql/ javax/sql/ Date: Thu, 30 Apr 2009 09:45:42 -0000 To: commits@harmony.apache.org From: tellison@apache.org X-Mailer: svnmailer-1.0.8 Message-Id: <20090430094543.D7A122388BEF@eris.apache.org> X-Virus-Checked: Checked by ClamAV on apache.org Modified: harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/DatabaseMetaData.java URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/DatabaseMetaData.java?rev=770130&r1=770129&r2=770130&view=diff ============================================================================== --- harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/DatabaseMetaData.java (original) +++ harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/DatabaseMetaData.java Thu Apr 30 09:45:40 2009 @@ -18,34 +18,35 @@ package java.sql; /** - * An interface which provides comprehensive information about the database. + * An interface which provides comprehensive information about the database + * management system and its supported features. *

- * This interface is implemented by JDBC driver writers in order to provide - * information about the underlying Database capabilities and the JDBC driver - * capabilities taken together. + * This interface is implemented by JDBC driver vendors in order to provide + * information about the underlying database capabilities in association with + * the JDBC driver. *

- * Some of the methods in this interface take String parameters which are - * Patterns. Within these string Patterns, '%' and '_' characters have special - * meanings. '%' means "match any substring of 0 or more characters". '_' means - * "match any one character". Only metadata entries that match the pattern are - * returned. If such a search pattern string is set to null, - * that argument's criteria are dropped from the search. - * + * Some of the methods in this interface take string parameters which are + * patterns. Within these string patterns, {@code '%'} and {@code '_'} + * characters have special meanings. {@code '%'} means + * "match any substring of 0 or more characters". {@code '_'} means + * "match any character". Only metadata entries that match the pattern are + * returned. If such a search pattern string is set to {@code null}, that + * argument's criteria are dropped from the search. */ public interface DatabaseMetaData { /** - * States that it may not be permitted to store NULL values. + * States that it may not be permitted to store {@code NULL} values. */ public static final short attributeNoNulls = 0; /** - * States that NULL values are definitely permitted. + * States that {@code NULL} values are definitely permitted. */ public static final short attributeNullable = 1; /** - * States that whether NULL values are permitted is unknown. + * States that whether {@code NULL} values are permitted is unknown. */ public static final short attributeNullableUnknown = 2; @@ -83,12 +84,12 @@ public static final int bestRowUnknown = 0; /** - * States that the column might not allow NULL values. + * States that the column must not allow {@code NULL} values. */ public static final int columnNoNulls = 0; /** - * States that the column definitely allows NULL values. + * States that the column definitely allows {@code NULL} values. */ public static final int columnNullable = 1; @@ -98,69 +99,72 @@ public static final int columnNullableUnknown = 2; /** - * For the column UPDATE_RULE, States that when the primary key is updated, - * the foreign key (imported key) is changed to agree with it. + * For the column {@code UPDATE_RULE}, states that when the primary key is + * updated, the foreign key (imported key) is changed accordingly. */ public static final int importedKeyCascade = 0; /** - * States deferrability. + * States that the evaluation of foreign key constraints is deferred (delayed + * until commit). */ public static final int importedKeyInitiallyDeferred = 5; /** - * States defer-ability. + * States that the evaluation of foreign key constraint is {@code IMMEDIATE} + * . */ public static final int importedKeyInitiallyImmediate = 6; /** - * For the columns UPDATE_RULE and DELETE_RULE, States that if the primary - * key has been imported, it cannot be updated or deleted. + * For the columns {@code UPDATE_RULE} and {@code DELETE_RULE}, states that + * if the primary key has been imported, it cannot be updated or deleted. */ public static final int importedKeyNoAction = 3; /** - * States defer-ability. + * States that the evaluation of foreign key constraint must not be {@code + * DEFERRED}. */ public static final int importedKeyNotDeferrable = 7; /** * States that a primary key must not be updated when imported as a foreign - * key by some other table. Used for the column UPDATE_RULE. + * key by some other table. Used for the column {@code UPDATE_RULE}. */ public static final int importedKeyRestrict = 1; /** * States that when the primary key is modified (updated or deleted) the * foreign (imported) key is changed to its default value. Applies to the - * UPDATE_RULE and DELETE_RULE columns. + * {@code UPDATE_RULE} and {@code DELETE_RULE} columns. */ public static final int importedKeySetDefault = 4; /** * States that when the primary key is modified (updated or deleted) the - * foreign (imported) key is changed to NULL. Applies to the - * UPDATE_RULE and DELETE_RULE columns. + * foreign (imported) key is changed to {@code NULL}. Applies to the {@code + * UPDATE_RULE} and {@code DELETE_RULE} columns. */ public static final int importedKeySetNull = 2; /** - * States that this column stores IN type parameters. + * States that the column stores {@code IN} type parameters. */ public static final int procedureColumnIn = 1; /** - * States that this column stores INOUT type parameters. + * States that this column stores {@code INOUT} type parameters. */ public static final int procedureColumnInOut = 2; /** - * States that this column stores OUT type parameters. + * States that this column stores {@code OUT} type parameters. */ public static final int procedureColumnOut = 4; /** - * States that the column stores results + * States that the column stores results. */ public static final int procedureColumnResult = 3; @@ -175,7 +179,7 @@ public static final int procedureColumnUnknown = 0; /** - * States that NULL values are not permitted. + * States that {@code NULL} values are not permitted. */ public static final int procedureNoNulls = 0; @@ -185,12 +189,12 @@ public static final int procedureNoResult = 1; /** - * States that NULL values are permitted. + * States that {@code NULL} values are permitted. */ public static final int procedureNullable = 1; /** - * States that whether NULL values are permitted is unknown. + * States that it is unknown whether {@code NULL} values are permitted. */ public static final int procedureNullableUnknown = 2; @@ -205,13 +209,13 @@ public static final int procedureReturnsResult = 2; /** - * States that the value is an SQL99 SQLSTATE value. + * States that the value is an SQL99 {@code SQLSTATE} value. */ public static final int sqlStateSQL99 = 2; /** - * States that the value is an SQL CLI SQLSTATE value as defined by X/Open - * (who are now know as Open Group) . + * States that the value is an SQL {@code CLI SQLSTATE} value as defined by + * the X/Open standard. */ public static final int sqlStateXOpen = 1; @@ -238,41 +242,41 @@ public static final short tableIndexStatistic = 0; /** - * States that a NULL value is NOT permitted for + * States that a {@code NULL} value is NOT permitted for * this data type. */ public static final int typeNoNulls = 0; /** - * States that a NULL value is permitted for this data type. + * States that a {@code NULL} value is permitted for this data type. */ public static final int typeNullable = 1; /** - * States that it is unknown if a NULL value is permitted for + * States that it is unknown if a {@code NULL} value is permitted for * this data type. */ public static final int typeNullableUnknown = 2; /** - * States that one can base all WHERE search clauses except WHERE . + * States that this column shall not be used for {@code WHERE} statements + * with a {@code LIKE} clause. */ public static final int typePredBasic = 2; /** - * States that WHERE is the only WHERE search clause that may - * be based on this type. + * States that this column can only be used in a {@code WHERE...LIKE} + * statement. */ public static final int typePredChar = 1; /** - * States that this type does not support WHERE search - * clauses. + * States that this column does not support searches. */ public static final int typePredNone = 0; /** - * States that all WHERE search clauses may be based on this type. + * States that the column is searchable. */ public static final int typeSearchable = 3; @@ -292,668 +296,659 @@ public static final int versionColumnUnknown = 0; /** - * Answers whether all procedures returned by getProcedures - * can be called by the current user. + * Returns whether all procedures returned by {@link #getProcedures} can be + * called by the current user. * - * @return true if all procedures can be called by the - * current user, false otherwise. + * @return {@code true} if all procedures can be called by the current user, + * {@code false} otherwise. * @throws SQLException - * if there is a database error + * if there is a database error. */ public boolean allProceduresAreCallable() throws SQLException; /** - * Answers whether all the tables returned by getTables can - * be used by the current user in a SELECT statement. + * Returns whether all the tables returned by {@code getTables} can be used + * by the current user in a {@code SELECT} statement. * - * @return true if all the tables can be used,false - * otherwise + * @return {@code true} if all the tables can be used,{@code false} + * otherwise. * @throws SQLException - * if there is a database error + * if there is a database error. */ public boolean allTablesAreSelectable() throws SQLException; /** - * Answers if a data definition statement in a transaction forces a commit - * of the transaction. + * Returns whether a data definition statement in a transaction forces a {@code + * commit} of the transaction. * - * @return true if the statement forces a commit, - * false otherwise + * @return {@code true} if the statement forces a commit, {@code false} + * otherwise. * @throws SQLException - * if there is a database error + * if there is a database error. */ public boolean dataDefinitionCausesTransactionCommit() throws SQLException; /** - * Answers whether the database ignores data definition statements within a + * Returns whether the database ignores data definition statements within a * transaction. * - * @return true if the database ignores a data definition - * statement, false otherwise + * @return {@code true} if the database ignores a data definition statement, + * {@code false} otherwise. * @throws SQLException - * if there is a database error + * if there is a database error. */ public boolean dataDefinitionIgnoredInTransactions() throws SQLException; /** - * Answers whether a visible row delete can be detected by calling - * ResultSet.rowDeleted. + * Returns whether a visible row delete can be detected by calling + * {@link ResultSet#rowDeleted}. * * @param type - * the type of the ResultSet involved: - * ResultSet.TYPE_FORWARD_ONLY, - * ResultSet.TYPE_SCROLL_INSENSITIVE, or - * ResultSet.TYPE_SCROLL_SENSITIVE - * @return true if the visible row delete can be detected, - * false otherwise + * the type of the {@code ResultSet} involved: {@code + * ResultSet.TYPE_FORWARD_ONLY}, {@code + * ResultSet.TYPE_SCROLL_INSENSITIVE}, or {@code + * ResultSet.TYPE_SCROLL_SENSITIVE} + * @return {@code true} if the visible row delete can be detected, {@code + * false} otherwise. * @throws SQLException - * if there is a database error + * if there is a database error. */ public boolean deletesAreDetected(int type) throws SQLException; /** - * Answers whether the return value of getMaxRowSize includes - * the SQL data types LONGVARCHAR and - * LONGVARBINARY. - * - * @return true if the return value includes - * LONGVARBINARY and LONGVARCHAR, - * otherwise false. + * Returns whether the return value of {@code getMaxRowSize} includes the + * SQL data types {@code LONGVARCHAR} and {@code LONGVARBINARY}. + * + * @return {@code true} if the return value includes {@code LONGVARBINARY} + * and {@code LONGVARCHAR}, otherwise {@code false}. * @throws SQLException - * if there is a database error + * if there is a database error. */ public boolean doesMaxRowSizeIncludeBlobs() throws SQLException; /** - * Answers a description of the specified attribute of the specified type - * for an SQL User Defined Type (UDT) for a specified schema and catalog. - * The descriptions returned are ordered by TYPE_SCHEM, - * TYPE_NAME and ORDINAL_POSITION. The descriptions do not - * contain inherited attributes. + * Returns a {@code ResultSet} describing a subset of the attributes of a + * specified SQL User Defined Type (UDT) for a specified schema and catalog. + * The subset is determined by restricting to those attributes whose + * name matches the {@code attributeNamePattern} and whose type name + * matches the {@code typeNamePattern}. Each row of the {@code ResultSet} + * describes one attribute, and the rows are ordered by the columns {@code TYPE_SCHEM}, + * {@code TYPE_NAME} and {@code ORDINAL_POSITION}. Inherited attributes + * are not included. *

- * The returned ResultSet object has rows with the following column names - * and meanings: + * The columns of the returned {@code ResultSet} object have the following + * names and meanings: *

    - *
  1. TYPE_CAT - String - the Type Catalog name (possibly - * null)
    2. - *
  2. TYPE_SCHEM - String - the Type Schema name (possibly - * null)
    3. - *
  3. TYPE_NAME - String - the Type name
    4. - *
  4. ATTR_NAME - String - the Attribute name
    5. - *
  5. DATA_TYPE - int - the Attribute type as defined in - * java.sql.Types
    6. - *
  6. ATTR_TYPE_NAME - String - the Attribute type name. - * This depends on the data source. For a UDT the name is - * fully qualified. For a REF it is both fully qualified and - * represents the target type of the reference.
    7. - *
  7. ATTR_SIZE - int - the Column size. When referring to - * char and date types this value is the maximum number of characters. When - * referring to numeric types is is the precision.
    8. - *
  8. DECIMAL_DIGITS - int - how many fractional digits are + *
  9. {@code TYPE_CAT} - String - the type catalog name (possibly {@code + * null})
    10. + *
  10. {@code TYPE_SCHEM} - String - the type schema name (possibly {@code + * null})
    11. + *
  11. {@code TYPE_NAME} - String - the type name
    12. + *
  12. {@code ATTR_NAME} - String - the attribute name
    13. + *
  13. {@code DATA_TYPE} - int - the attribute type as defined in {@code + * java.sql.Types}
    14. + *
  14. {@code ATTR_TYPE_NAME} - String - the attribute type name. This + * depends on the data source. For a {@code UDT} the name is fully + * qualified. For a {@code REF} it is both fully qualified and represents + * the target type of the reference.
    15. + *
  15. {@code ATTR_SIZE} - int - the column size. When referring to char and + * date types this value is the maximum number of characters. When referring + * to numeric types is is the precision.
    16. + *
  16. {@code DECIMAL_DIGITS} - int - how many fractional digits are * supported
    17. - *
  17. NUM_PREC_RADIX - int - numeric values radix
    18. - *
  18. NULLABLE - int - whether NULL is - * permitted: + *
  19. {@code NUM_PREC_RADIX} - int - numeric values radix
    20. + *
  20. {@code NULLABLE} - int - whether {@code NULL} is permitted: *
      - *
    • DatabaseMetaData.attributeNoNulls - might not allow - * NULLs
      • - *
    • DatabaseMetaData.attributeNullable - NULLs - * definitely permitted
      • + *
    • DatabaseMetaData.attributeNoNulls - {@code NULL} values not permitted
      • + *
    • DatabaseMetaData.attributeNullable - {@code NULL} values definitely + * permitted
      • *
    • DatabaseMetaData.attributeNullableUnknown - unknown
      • *
    *
    21. - *
  21. REMARKS - String - A comment describing the attribute - * (possibly null)
    22. - *
  22. ATTR_DEF - String - Default value for the attribute (possibly - * null)
    23. - *
  23. SQL_DATA_TYPE - int - not used
    24. + *
  24. {@code REMARKS} - String - a comment describing the attribute + * (possibly {@code null})
    25. + *
  25. ATTR_DEF - String - Default value for the attribute (possibly {@code + * null})
    26. + *
  26. {@code SQL_DATA_TYPE} - int - not used
    27. *
  27. SQL_DATETIME_SUB - int - not used
    28. - *
  28. CHAR_OCTET_LENGTH - int - For CHAR types, the max - * number of bytes in the column
    29. - *
  29. ORDINAL_POSITION - int - The Index of the column in the Table (based - * on 1)
    30. - *
  30. IS_NULLABLE - String - "NO" = column does not allow - * NULLs, "YES" = column allows NULLs "" = - * NULL status unknown
    31. - *
  31. SCOPE_CATALOG - String - Catalog for table, - * SCOPE of Reference attribute. NULL if - * DATA_TYPE is not REF.
    32. - *
  32. SCOPE_SCHEMA - String - Schema for table, - * SCOPE of Reference attribute. NULL if - * DATA_TYPE is not REF.
    33. - *
  33. SCOPE_TABLE - String - Table name for - * SCOPE of Reference attribute. NULL if - * DATA_TYPE is not REF.
    34. - *
  34. SOURCE_DATA_TYPE - String - The source type for user - * generated REF type or for a Distinct type. (NULL if - * DATA_TYPE is not DISTINCT or user generated REF)
    35. + *
  35. CHAR_OCTET_LENGTH - int - for {@code CHAR} types, the max number of + * bytes in the column
    36. + *
  36. ORDINAL_POSITION - int - The index of the column in the table (where + * the count starts from 1, not 0)
    37. + *
  37. IS_NULLABLE - String - {@code "NO"} = the column does not allow {@code + * NULL}s, {@code "YES"} = the column allows {@code NULL}s, "" = status unknown
    38. + *
  38. {@code SCOPE_CATALOG} - String - if the {@code DATA_TYPE} is {@code REF}, + * this gives the catalog of the table corresponding to the attribute's scope. + * NULL if the {@code DATA_TYPE} is not REF.
    39. + *
  39. {@code SCOPE_SCHEMA} - String - if the {@code DATA_TYPE} is {@code REF}, + * this gives the schema of the table corresponding to the attribute's scope. + * NULL if the {@code DATA_TYPE} is not REF.
    40. + *
  40. {@code SCOPE_TABLE} - String - if the {@code DATA_TYPE} is {@code REF}, + * this gives the name of the table corresponding to the attribute's scope. + * NULL if the {@code DATA_TYPE} is not REF.
    41. + *
  41. {@code SOURCE_DATA_TYPE} - String - The source type for a user + * generated REF type or for a Distinct type. ({@code NULL} if {@code + * DATA_TYPE} is not DISTINCT or a user generated REF)
    42. *
- * + * * @param catalog - * a Catalog Name. null is used to imply no - * narrowing of the search using Catalog Name. Otherwise, the - * name must match a Catalog Name held in the database, with "" - * used to retrieve those without a Catalog Name. + * a catalog name. {@code null} is used to imply no narrowing of + * the search by catalog name. Otherwise, the name must match a + * catalog name held in the database, with "" used to retrieve + * those without a catalog name. * @param schemaPattern - * a Schema Name Pattern. null is used to imply no - * narrowing of the search using Schema Name. Otherwise, the name - * must match a Schema name in the database, with "" used to - * retrieve those without a Schema name. + * a schema name pattern. {@code null} is used to imply no + * narrowing of the search by a schema name. Otherwise, the name + * must match a schema name in the database, with "" used to + * retrieve those without a schema name. * @param typeNamePattern - * a Type name. This pattern must match the type name stored in + * a type name. This pattern must match the type name stored in * the database. * @param attributeNamePattern - * an Attribute name. Must match the attribute name as stored in + * an Attribute name. This pattern must match the attribute name as stored in * the database. - * @return a ResultSet, where each Row is an attribute description + * @return a {@code ResultSet}, where each row is an attribute description. * @throws SQLException - * if there is a database error + * if there is a database error. */ public ResultSet getAttributes(String catalog, String schemaPattern, String typeNamePattern, String attributeNamePattern) throws SQLException; /** - * Answers a list of a table's optimal set of columns that uniquely - * identifies a row. The results are ordered by SCOPE (see - * below). + * Returns a list of a table's optimal set of columns that uniquely + * identify the rows. The results are ordered by {@code SCOPE} (see below). *

* The results are returned as a table, with one entry for each column, as * follows: *

    - *
  1. SCOPE - short - the SCOPE of the - * result, as follows: + *
  2. {@code SCOPE} - short - the {@code SCOPE} of the result, as follows: *
      - *
    • DatabaseMetaData.bestRowTemporary - very temporary, while using row - *
      • - *
    • DatabaseMetaData.bestRowTransaction - good for remainder of current - * transaction
      • - *
    • DatabaseMetaData.bestRowSession - good for remainder of database - * session
      • + *
    • {@code DatabaseMetaData.bestRowTemporary} - the result is very temporary, + * only valid while on the current row
      • + *
    • {@code DatabaseMetaData.bestRowTransaction} - the result is good for remainder of + * current transaction
      • + *
    • {@code DatabaseMetaData.bestRowSession} - the result is good for remainder of + * database session
      • *
    *
    3. - *
  3. COLUMN_NAME - String - the column name
    4. - *
  4. DATA_TYPE - int - the Type of the data, as defined in - * java.sql.Types
    5. - *
  5. TYPE_NAME - String - Name of the type - database - * dependent. For UDT types the name is fully qualified
    6. - *
  6. COLUMN_SIZE - int - The precision of the data in the - * column
    7. - *
  7. BUFFER_LENGTH - int - not used
    8. - *
  8. DECIMAL_DIGITS - short - number of fractional digits - *
    9. - *
  9. PSEUDO_COLUMN - short - whether this is a pseudo - * column eg. and Oracle ROWID: + *
  10. {@code COLUMN_NAME} - String - the column name
    11. + *
  11. {@code DATA_TYPE} - int - the Type of the data, as defined in {@code + * java.sql.Types}
    12. + *
  12. {@code TYPE_NAME} - String - the Name of the type - database dependent. + * For UDT types the name is fully qualified
    13. + *
  13. {@code COLUMN_SIZE} - int - the precision of the data in the column
    14. + *
  14. {@code BUFFER_LENGTH} - int - not used
    15. + *
  15. {@code DECIMAL_DIGITS} - short - number of fractional digits
    16. + *
  16. {@code PSEUDO_COLUMN} - short - whether this is a pseudo column (e.g. + * an Oracle {@code ROWID}): *
      - *
    • DatabaseMetaData.bestRowUnknown - don't know whether this is a - * pseudo column
      • - *
    • DatabaseMetaData.bestRowNotPseudo - column is not pseudo
      • - *
    • DatabaseMetaData.bestRowPseudo - column is a pseudo column
      • + *
    • {@code DatabaseMetaData.bestRowUnknown} - it is not known whether this is + * a pseudo column
      • + *
    • {@code DatabaseMetaData.bestRowNotPseudo} - the column is not pseudo
      • + *
    • {@code DatabaseMetaData.bestRowPseudo} - the column is a pseudo column
      • *
    *
    17. *
- * + * * @param catalog - * a Catalog Name. null is used to imply no - * narrowing of the search using Catalog Name. Otherwise, the - * name must match a Catalog Name held in the database, with "" - * used to retrieve those without a Catalog Name. + * a catalog name. {@code null} is used to imply no narrowing of + * the search by catalog name. Otherwise, the name must match a + * catalog name held in the database, with "" used to retrieve + * those without a catalog name. * @param schema - * a Schema Name Pattern. null is used to imply no - * narrowing of the search using Schema Name. Otherwise, the name - * must match a Schema name in the database, with "" used to - * retrieve those without a Schema name. + * a schema name pattern. {@code null} is used to imply no + * narrowing of the search by schema name. Otherwise, the name + * must match a schema name in the database, with "" used to + * retrieve those without a schema name. * @param table * the table name. This must match the name of the table as * declared in the database. * @param scope - * the SCOPE of interest, values as defined above + * the {@code SCOPE} of interest, values as defined above. * @param nullable - * true = include columns that are nullable, - * false = do not include - * @return a ResultSet where each row is a description of a column and the - * complete set of rows is the optimal set for this table. + * {@code true} = include columns that are nullable, {@code + * false} = do not include nullable columns. + * @return a {@code ResultSet} where each row is a description of a column + * and the complete set of rows is the optimal set for this table. * @throws SQLException - * if there is a database error + * if there is a database error. */ public ResultSet getBestRowIdentifier(String catalog, String schema, String table, int scope, boolean nullable) throws SQLException; /** - * Answers the set of catalog names available in this database. The set is + * Returns the set of catalog names available in this database. The set is * returned ordered by catalog name. * - * @return a ResultSet containing the Catalog names, with each row - * containing one Catalog name contained as a String in the single - * column named TABLE_CAT. + * @return a {@code ResultSet} containing the catalog names, with each row + * containing one catalog name (as a {@code String}) in the + * single column named {@code TABLE_CAT}. * @throws SQLException - * if there is a database error + * if there is a database error. */ public ResultSet getCatalogs() throws SQLException; /** - * Answers the separator that this database uses between a catalog name and + * Returns the separator that this database uses between a catalog name and * table name. * - * @return a String containing the separator + * @return a String containing the separator. * @throws SQLException - * if there is a database error + * if there is a database error. */ public String getCatalogSeparator() throws SQLException; /** - * Answers the term that the database vendor prefers term for "catalog". + * Returns the term that the database vendor prefers term for "catalog". * - * @return a String with the vendor's term for "catalog" + * @return a String with the vendor's term for "catalog". * @throws SQLException - * if there is a database error + * if there is a database error. */ public String getCatalogTerm() throws SQLException; /** - * Answers a description of access rights for a table's columns. Only access + * Returns a description of access rights for a table's columns. Only access * rights matching the criteria for the column name are returned. *

- * The description is returned as a ResultSet with rows of data for each - * access right, with columns as follows: + * The description is returned as a {@code ResultSet} with rows of data for + * each access right, with columns as follows: *

    - *
  1. TABLE_CAT - String - Catalog name (possibly - * null)
    2. - *
  2. TABLE_SCHEM - String - Schema name (possibly - * null)
    3. - *
  3. TABLE_NAME - String - The Table name
    4. - *
  4. COLUMN_NAME - String - The Column name
    5. - *
  5. GRANTOR - String - The grantor of access (possibly - * null)
    6. - *
  6. PRIVILEGE - String - Access right - one of SELECT, - * INSERT, UPDATE, REFERENCES,...
    7. - *
  7. IS_GRANTABLE - String - "YES" implies that the - * receiver can grant access to others, "NO" if the receiver cannot grant - * access to others, null if unknown.
    8. + *
  8. {@code TABLE_CAT} - String - the catalog name (possibly {@code null})
    9. + *
  9. {@code TABLE_SCHEM} - String - the schema name (possibly {@code null})
    10. + *
  10. {@code TABLE_NAME} - String - the table name
    11. + *
  11. {@code COLUMN_NAME} - String - the Column name
    12. + *
  12. {@code GRANTOR} - String - the grantor of access (possibly {@code + * null})
    13. + *
  13. {@code PRIVILEGE} - String - Access right - one of SELECT, INSERT, + * UPDATE, REFERENCES,...
    14. + *
  14. {@code IS_GRANTABLE} - String - {@code "YES"} implies that the + * receiver can grant access to others, {@code "NO"} if the receiver cannot + * grant access to others, {@code null} if unknown.
    15. *
- * + * * @param catalog - * a Catalog Name. null is used to imply no - * narrowing of the search using Catalog Name. Otherwise, the - * name must match a Catalog Name held in the database, with "" - * used to retrieve those without a Catalog Name. + * a catalog name. {@code null} is used to imply no narrowing of + * the search by catalog name. Otherwise, the name must match a + * catalog name held in the database, with "" used to retrieve + * those without a catalog name. * @param schema - * a Schema Name Pattern. null is used to imply no - * narrowing of the search using Schema Name. Otherwise, the name - * must match a Schema name in the database, with "" used to - * retrieve those without a Schema name. + * a schema name pattern. {@code null} is used to imply no + * narrowing of the search by schema name. Otherwise, the name + * must match a schema name in the database, with "" used to + * retrieve those without a schema name. * @param table * the table name. This must match the name of the table as * declared in the database. * @param columnNamePattern * the column name. This must match the name of a column in the * table in the database. - * @return a ResultSet containing the access rights, one row for each - * privilege description + * @return a {@code ResultSet} containing the access rights, one row for + * each privilege description. * @throws SQLException - * if there is a database error + * if there is a database error. */ public ResultSet getColumnPrivileges(String catalog, String schema, String table, String columnNamePattern) throws SQLException; /** - * Answers a description of table columns available in a specified catalog. - * Only descriptions meeting the specified Catalog, Schema, Table and Column + * Returns a description of table columns available in a specified catalog. + * Only descriptions meeting the specified catalog, schema, table, and column * names are returned. *

- * The descriptions are returned as a ResultSet conforming to the following - * data layout, with one row per table column: + * The descriptions are returned as a {@code ResultSet} conforming to the + * following data layout, with one row per table column: *

    - *
  1. TABLE_CAT - String - Catalog name (possibly - * null)
    2. - *
  2. TABLE_SCHEM - String - Schema name (possibly - * null)
    3. - *
  3. TABLE_NAME - String - The Table name
    4. - *
  4. COLUMN_NAME - String - The Column name
    5. - *
  5. DATA_TYPE - int - The SQL type as specified in - * java.sql.Types
    6. - *
  6. TYPE_NAME - String - Name for the data type, depends - * on database, UDT names are fully qualified
    7. - *
  7. COLUMN_SIZE - int - Column size - the precision for - * numeric types, max characters for char and date types
    8. - *
  8. BUFFER_LENGTH - int - Not used
    9. - *
  9. DECIMAL_DIGITS - int - maximum number of fractional - * digits
    10. - *
  10. NUM_PREC_RADIX - int - the Radix
    11. - *
  11. NULLABLE - int - does the column allow - * nulls: + *
  12. {@code TABLE_CAT} - String - the catalog name (possibly {@code null})
    13. + *
  13. {@code TABLE_SCHEM} - String - the schema name (possibly {@code null})
    14. + *
  14. {@code TABLE_NAME} - String - the table name
    15. + *
  15. {@code COLUMN_NAME} - String - the column name
    16. + *
  16. {@code DATA_TYPE} - int - the SQL type as specified in {@code + * java.sql.Types}
    17. + *
  17. {@code TYPE_NAME} - String - the name of the data type, (database-dependent, + * UDT names are fully qualified)
    18. + *
  18. {@code COLUMN_SIZE} - int - the column size (the precision for numeric + * types, max characters for {@code char} and {@code date} types)
    19. + *
  19. {@code BUFFER_LENGTH} - int - Not used
    20. + *
  20. {@code DECIMAL_DIGITS} - int - maximum number of fractional digits
    21. + *
  21. {@code NUM_PREC_RADIX} - int - the radix for numerical types
    22. + *
  22. {@code NULLABLE} - int - whether the column allows {@code null}s: *
      - *
    • DatabaseMetaData.columnNoNulls = may not allow NULLs
      • - *
    • DatabaseMetaData.columnNullable = does allow NULLs
      • - *
    • DatabaseMetaData.columnNullableUnknown = unknown NULL - * status
      • + *
    • DatabaseMetaData.columnNoNulls = may not allow {@code NULL}s
      • + *
    • DatabaseMetaData.columnNullable = does allow {@code NULL}s
      • + *
    • DatabaseMetaData.columnNullableUnknown = unknown {@code NULL} status
      • *
    *
    23. - *
  23. REMARKS - String - A description of the column - * (possibly null)
    24. - *
  24. COLUMN_DEF - String - Default value for the column - * (possibly null)
    25. - *
  25. SQL_DATA_TYPE - int - not used
    26. - *
  26. SQL_DATETIME_SUB - int - not used
    27. - *
  27. CHAR_OCTET_LENGTH - int - maximum number of bytes in - * the char type columns
    28. - *
  28. ORDINAL_POSITION - int - Column index in the table (1 - * based)
    29. - *
  29. IS_NULLABLE - String - "NO" = column does not allow - * NULLs, "YES" = column allows NULLs "" = NULL status + *
  30. {@code REMARKS} - String - A description of the column (possibly + * {@code null})
    31. + *
  31. {@code COLUMN_DEF} - String - Default value for the column (possibly + * {@code null})
    32. + *
  32. {@code SQL_DATA_TYPE} - int - not used
    33. + *
  33. {@code SQL_DATETIME_SUB} - int - not used
    34. + *
  34. {@code CHAR_OCTET_LENGTH} - int - maximum number of bytes in the + * {@code char} type columns
    35. + *
  35. {@code ORDINAL_POSITION} - int - the column index in the table (1 based)
    36. + *
  36. {@code IS_NULLABLE} - String - {@code "NO"} = column does not allow + * NULLs, {@code "YES"} = column allows NULLs, "" = {@code NULL} status * unknown
    37. - *
  37. SCOPE_CATALOG - String - Catalog for table, - * SCOPE of Reference attribute. NULL if - * DATA_TYPE is not REF.
    38. - *
  38. SCOPE_SCHEMA - String - Schema for table, scope of - * Reference attribute. NULL if DATA_TYPE is - * not REF.
    39. - *
  39. SCOPE_TABLE - String - Table name for scope of - * Reference attribute. NULL if DATA_TYPE is - * not REF.
    40. - *
  40. SOURCE_DATA_TYPE - String - The source type for user - * generated REF type or for a Distinct type. (NULL if - * DATA_TYPE is not DISTINCT or user generated REF)
    41. + *
  41. {@code SCOPE_CATALOG} - String - if the {@code DATA_TYPE} is {@code REF}, + * this gives the catalog of the table corresponding to the attribute's scope. + * NULL if the {@code DATA_TYPE} is not REF.
    42. + *
  42. {@code SCOPE_SCHEMA} - String - if the {@code DATA_TYPE} is {@code REF}, + * this gives the schema of the table corresponding to the attribute's scope. + * NULL if the {@code DATA_TYPE} is not REF.
    43. + *
  43. {@code SCOPE_TABLE} - String - if the {@code DATA_TYPE} is {@code REF}, + * this gives the name of the table corresponding to the attribute's scope. + * NULL if the {@code DATA_TYPE} is not REF.
    44. + *
  44. {@code SOURCE_DATA_TYPE} - String - The source type for a user + * generated REF type or for a Distinct type. ({@code NULL} if {@code + * DATA_TYPE} is not DISTINCT or a user generated REF)
    45. *
- * + * * @param catalog - * a Catalog Name. null is used to imply no - * narrowing of the search using Catalog Name. Otherwise, the - * name must match a Catalog Name held in the database, with "" - * used to retrieve those without a Catalog Name. + * a catalog name. {@code null} is used to imply no narrowing of + * the search by catalog name. Otherwise, the name must match a + * catalog name held in the database, with "" used to retrieve + * those without a catalog name. * @param schemaPattern - * a Schema Name Pattern. null is used to imply no - * narrowing of the search using Schema Name. Otherwise, the name - * must match a Schema name in the database, with "" used to - * retrieve those without a Schema name. + * a schema name pattern. {@code null} is used to imply no + * narrowing of the search by schema name. Otherwise, the name + * must match a schema name in the database, with "" used to + * retrieve those without a schema name. * @param tableNamePattern * the table name. This must match the name of the table as * declared in the database. * @param columnNamePattern * the column name. This must match the name of a column in the * table in the database. - * @return the descriptions as a ResultSet with rows in the form defined - * above + * @return the descriptions as a {@code ResultSet} with rows in the form + * defined above. * @throws SQLException - * if there is a database error + * if there is a database error. */ public ResultSet getColumns(String catalog, String schemaPattern, String tableNamePattern, String columnNamePattern) throws SQLException; /** - * Answers the database connection that created this metadata. + * Returns the database connection that created this metadata. * - * @return the connection + * @return the connection to the database. * @throws SQLException - * if there is a database error + * if there is a database error. */ public Connection getConnection() throws SQLException; /** - * Answers a list of foreign key columns in a given foreign key table that + * Returns a list of foreign key columns in a given foreign key table that * reference the primary key columns of a supplied primary key table. This * describes how one table imports the key of another table. It would be * expected to return a single foreign key - primary key pair in most cases. *

- * The descriptions are returned as a ResultSet with one row for each - * Foreign key, with the following layout: + * The descriptions are returned as a {@code ResultSet} with one row for + * each foreign key, with the following layout: *

    - *
  1. PKTABLE_CAT - String - from the primary key table : - * Catalog (possibly null)
    2. - *
  2. PKTABLE_SCHEM - String - from the primary key table : - * Schema (possibly null)
    3. - *
  3. PKTABLE_NAME - String - primary key table : name - *
    4. - *
  4. PKCOLUMN_NAME - String - primary key column : name
    5. - *
  5. FKTABLE_CAT - String - from the foreign key table : - * the catalog name being exported (possibly null)
    6. - *
  6. FKTABLE_SCHEM - String - foreign key table : Schema - * name being exported (possibly null)
    7. - *
  7. FKTABLE_NAME - String - foreign key table : the name - * being exported
    8. - *
  8. FKCOLUMN_NAME - String - foreign key column : the - * name being exported
    9. - *
  9. KEY_SEQ - short - sequence number (in the foreign - * key)
    10. - *
  10. UPDATE_RULE - short - how to treat foreign key when - * primary key is updated: + *
  11. {@code PKTABLE_CAT} - String - from the primary key table : Catalog + * (possibly {@code null})
    12. + *
  12. {@code PKTABLE_SCHEM} - String - from the primary key table : Schema + * (possibly {@code null})
    13. + *
  13. {@code PKTABLE_NAME} - String - from the primary key table : name
    14. + *
  14. {@code PKCOLUMN_NAME} - String - from the primary key column : name
    15. + *
  15. {@code FKTABLE_CAT} - String - from the foreign key table : the + * catalog name being exported (possibly {@code null})
    16. + *
  16. {@code FKTABLE_SCHEM} - String - from the foreign key table : the schema name + * being exported (possibly {@code null})
    17. + *
  17. {@code FKTABLE_NAME} - String - from the foreign key table : the name being + * exported
    18. + *
  18. {@code FKCOLUMN_NAME} - String - from the foreign key column : the name being + * exported
    19. + *
  19. {@code KEY_SEQ} - short - the sequence number (in the foreign key)
    20. + *
  20. {@code UPDATE_RULE} - short - a value giving the rule for how to treat the corresponding foreign key when a primary + * key is updated: *
      - *
    • DatabaseMetaData.importedKeyNoAction - don't allow update of primary - * key if imported
      • - *
    • DatabaseMetaData.importedKeyCascade - change imported key to match - * the primary key update
      • - *
    • DatabaseMetaData.importedKeySetNull - set the imported key to - * null
      • - *
    • DatabaseMetaData.importedKeySetDefault - set the imported key to - * default values
      • - *
    • DatabaseMetaData.importedKeyRestrict - same as importedKeyNoAction
      • + *
    • {@code DatabaseMetaData.importedKeyNoAction} - don't allow the + * primary key to be updated if it is imported as a foreign key
      • + *
    • {@code DatabaseMetaData.importedKeyCascade} - change the imported key to + * match the updated primary key
      • + *
    • {@code DatabaseMetaData.importedKeySetNull} - set the imported key to + * {@code null}
      • + *
    • {@code DatabaseMetaData.importedKeySetDefault} - set the imported key + * to its default value
      • + *
    • {@code DatabaseMetaData.importedKeyRestrict} - same as {@code + * importedKeyNoAction}
      • *
    *
    21. - *
  21. DELETE_RULE - short - how to treat foreign key when - * primary key is deleted: + *
  22. {@code DELETE_RULE} - short - a value giving the rule for how to treat the foreign key when the corresponding primary + * key is deleted: *
      - *
    • DatabaseMetaData.importedKeyNoAction - don't allow delete of primary - * key if imported
      • - *
    • DatabaseMetaData.importedKeyCascade - delete those rows that import - * a deleted key
      • - *
    • DatabaseMetaData.importedKeySetNull - set the imported key to - * null
      • - *
    • DatabaseMetaData.importedKeySetDefault - set the imported key to - * default values
      • - *
    • DatabaseMetaData.importedKeyRestrict - same as importedKeyNoAction
      • + *
    • {@code DatabaseMetaData.importedKeyNoAction} - don't allow the + * primary key to be deleted if it is imported as a foreign key
      • + *
    • {@code DatabaseMetaData.importedKeyCascade} - delete those rows that + * import a deleted key
      • + *
    • {@code DatabaseMetaData.importedKeySetNull} - set the imported key to + * {@code null}
      • + *
    • {@code DatabaseMetaData.importedKeySetDefault} - set the imported key + * to its default value
      • + *
    • {@code DatabaseMetaData.importedKeyRestrict} - same as + * importedKeyNoAction
      • *
    *
    23. - *
  23. FK_NAME - String - foreign key name (possibly null)
    24. - *
  24. PK_NAME - String - primary key name (possibly null)
    25. - *
  25. DEFERRABILITY - short - can foreign key constraints be deferred - * until commit (see SQL92 specification for definitions)?: + *
  26. {@code FK_NAME} - String - the foreign key name (possibly {@code null})
    27. + *
  27. {@code PK_NAME} - String - the primary key name (possibly {@code null})
    28. + *
  28. {@code DEFERRABILITY} - short - whether foreign key constraints can be + * deferred until commit (see the SQL92 specification for definitions): *
      - *
    • DatabaseMetaData.importedKeyInitiallyDeferred
      • - *
    • DatabaseMetaData.importedKeyInitiallyImmediate
      • - *
    • DatabaseMetaData.importedKeyNotDeferrable
      • + *
    • {@code DatabaseMetaData.importedKeyInitiallyDeferred}
      • + *
    • {@code DatabaseMetaData.importedKeyInitiallyImmediate}
      • + *
    • {@code DatabaseMetaData.importedKeyNotDeferrable}
      • *
    *
    29. *
- * + * * @param primaryCatalog - * a Catalog Name. null is used to imply no - * narrowing of the search using Catalog Name. Otherwise, the - * name must match a Catalog Name held in the database, with "" - * used to retrieve those without a Catalog Name. + * a catalog name for the primary key table. {@code null} is used to imply no narrowing of + * the search by catalog name. Otherwise, the name must match a + * catalog name held in the database, with "" used to retrieve + * those without a catalog name. * @param primarySchema - * a Schema Name. null is used to imply no - * narrowing of the search using Schema Name. Otherwise, the name - * must match a Schema name in the database, with "" used to - * retrieve those without a Schema name. + * a schema name for the primary key table. {@code null} is used to imply no narrowing of + * the search by schema name. Otherwise, the name must match a + * schema name in the database, with "" used to retrieve those + * without a schema name. * @param primaryTable * the name of the table which exports the key. It must match the - * name of the table in the database + * name of the table in the database. * @param foreignCatalog - * a Catalog Name. null is used to imply no - * narrowing of the search using Catalog Name. Otherwise, the - * name must match a Catalog Name held in the database, with "" - * used to retrieve those without a Catalog Name. + * a catalog name for the foreign key table. {@code null} is used to imply no narrowing of + * the search by catalog name. Otherwise, the name must match a + * catalog name held in the database, with "" used to retrieve + * those without a catalog name. * @param foreignSchema - * a Schema Name. null is used to imply no - * narrowing of the search using Schema Name. Otherwise, the name - * must match a Schema name in the database, with "" used to - * retrieve those without a Schema name. + * a schema name for the foreign key table. {@code null} is used to imply no narrowing of + * the search by schema name. Otherwise, the name must match a + * schema name in the database, with "" used to retrieve those + * without a schema name. * @param foreignTable * the name of the table importing the key. It must match the - * name of the table in the database - * @return a ResultSet containing rows with the descriptions of the foreign - * keys laid out according to the format defined above. + * name of the table in the database. + * @return a {@code ResultSet} containing rows with the descriptions of the + * foreign keys laid out according to the format defined above. * @throws SQLException - * if there is a database error + * if there is a database error. */ public ResultSet getCrossReference(String primaryCatalog, String primarySchema, String primaryTable, String foreignCatalog, String foreignSchema, String foreignTable) throws SQLException; /** - * Answers the major version number of the database software. + * Returns the major version number of the database software. * - * @return the Major version number of the database software. + * @return the major version number of the database software. * @throws SQLException - * a database error occurred + * a database error occurred. */ public int getDatabaseMajorVersion() throws SQLException; /** - * Answers the minor version number of the database software. + * Returns the minor version number of the database software. * - * @return the Minor version number of the database software. + * @return the minor version number of the database software. * @throws SQLException - * a database error occurred + * a database error occurred. */ public int getDatabaseMinorVersion() throws SQLException; /** - * Answers the name of the database software. + * Returns the name of the database software. * - * @return a String with the name of the database software. + * @return a {@code String} with the name of the database software. * @throws SQLException - * a database error occurred + * a database error occurred. */ public String getDatabaseProductName() throws SQLException; /** - * Answers the version number of this database software. + * Returns the version number of this database software. * - * @return a String with the version number of the database software. + * @return a {@code String} with the version number of the database + * software. * @throws SQLException - * a database error occurred + * a database error occurred. */ public String getDatabaseProductVersion() throws SQLException; /** - * Answers the default transaction isolation level for this database. + * Returns the default transaction isolation level for this database. * - * @return the default transaction isolation level. One of - * TRANSACTION_NONE, - * TRANSACTION_READ_COMMITTED, - * TRANSACTION_READ_UNCOMMITTED, - * TRANSACTION_REPEATABLE_READ or - * TRANSACTION_SERIALIZABLE. + * @return the default transaction isolation level. One of the following values: + *
    + *
  • {@code TRANSACTION_NONE}
    • + *
  • {@code TRANSACTION_READ_COMMITTED}
    • + *
  • {@code TRANSACTION_READ_UNCOMMITTED}
    • + *
  • {@code TRANSACTION_REPEATABLE_READ}
    • + *
  • {@code TRANSACTION_SERIALIZABLE}
    • + *
* @throws SQLException - * a database error occurred + * a database error occurred. */ public int getDefaultTransactionIsolation() throws SQLException; /** - * Answers the JDBC driver's major version number. + * Returns the JDBC driver's major version number. * - * @return the driver's major version number + * @return the driver's major version number. */ public int getDriverMajorVersion(); /** - * Answers the JDBC driver's minor version number. + * Returns the JDBC driver's minor version number. * - * @return the driver's minor version number + * @return the driver's minor version number. */ public int getDriverMinorVersion(); /** - * Answers the name of this JDBC driver. + * Returns the name of this JDBC driver. * - * @return a String containing the name of the JDBC driver + * @return a {@code String} containing the name of the JDBC driver * @throws SQLException - * a database error occurred + * a database error occurred. */ public String getDriverName() throws SQLException; /** - * Answers the version number of this JDBC driver. + * Returns the version number of this JDBC driver. * - * @return a String containing the complete version number of the JDBC - * driver + * @return a {@code String} containing the complete version number of the + * JDBC driver. * @throws SQLException - * a database error occurred + * a database error occurred. */ public String getDriverVersion() throws SQLException; /** - * Answers a list of the foreign key columns that reference the primary key + * Returns a list of the foreign key columns that reference the primary key * columns of a specified table (the foreign keys exported by a table). *

- * The list is returned as a ResultSet with a row for each of the foreign - * key columns, ordered by FKTABLE_CAT, - * FKTABLE_SCHEM, FKTABLE_NAME, and - * KEY_SEQ, with the format for each row being: + * The list is returned as a {@code ResultSet} with a row for each of the + * foreign key columns, ordered by {@code FKTABLE_CAT}, {@code + * FKTABLE_SCHEM}, {@code FKTABLE_NAME}, and {@code KEY_SEQ}, with the + * format for each row being: *

    - *
  1. PKTABLE_CAT - String - primary key table : Catalog - * (possibly null)
    2. - *
  2. PKTABLE_SCHEM - String - primary key table : Schema - * (possibly null)
    3. - *
  3. PKTABLE_NAME - String - primary key table : name - *
    4. - *
  4. PKCOLUMN_NAME - String - primary key column : name
    5. - *
  5. FKTABLE_CAT - String - foreign key table : Catalog - * name being exported (possibly null)
    6. - *
  6. FKTABLE_SCHEM - String - foreign key table : Schema - * name being exported (possibly null)
    7. - *
  7. FKTABLE_NAME - String - foreign key table : name - * being exported
    8. - *
  8. FKCOLUMN_NAME - String - foreign key column : name - * being exported
    9. - *
  9. KEY_SEQ - short - sequence number in the foreign key
    10. - *
  10. UPDATE_RULE - short - how to treat foreign key when primary key is - * updated: + *
  11. {@code PKTABLE_CAT} - String - from the primary key table : the catalog (possibly + * {@code null})
    12. + *
  12. {@code PKTABLE_SCHEM} - String - from the primary key table : the schema (possibly + * {@code null})
    13. + *
  13. {@code PKTABLE_NAME} - String - from the primary key table : the name
    14. + *
  14. {@code PKCOLUMN_NAME} - String - from the primary key column : the name
    15. + *
  15. {@code FKTABLE_CAT} - String - from the foreign key table : the catalog name being + * exported (possibly {@code null})
    16. + *
  16. {@code FKTABLE_SCHEM} - String - from the foreign key table : the schema name + * being exported (possibly {@code null})
    17. + *
  17. {@code FKTABLE_NAME} - String - from the foreign key table : the name being + * exported
    18. + *
  18. {@code FKCOLUMN_NAME} - String - from the foreign key column : the name being + * exported
    19. + *
  19. {@code KEY_SEQ} - short - the sequence number (in the foreign key)
    20. + *
  20. {@code UPDATE_RULE} - short - a value giving the rule for how to treat the foreign key when the corresponding primary + * key is updated: *
      - *
    • DatabaseMetaData.importedKeyNoAction - don't allow update of primary - * key if imported
      • - *
    • DatabaseMetaData.importedKeyCascade - change imported key to match - * the primary key update
      • - *
    • DatabaseMetaData.importedKeySetNull - set the imported key to - * null
      • - *
    • DatabaseMetaData.importedKeySetDefault - set the imported key to - * default values
      • - *
    • DatabaseMetaData.importedKeyRestrict - same as importedKeyNoAction
      • + *
    • {@code DatabaseMetaData.importedKeyNoAction} - don't allow the + * primary key to be updated if it is imported as a foreign key
      • + *
    • {@code DatabaseMetaData.importedKeyCascade} - change the imported key to + * match the primary key update
      • + *
    • {@code DatabaseMetaData.importedKeySetNull} - set the imported key to + * {@code null}
      • + *
    • {@code DatabaseMetaData.importedKeySetDefault} - set the imported key + * to its default value
      • + *
    • {@code DatabaseMetaData.importedKeyRestrict} - same as + * importedKeyNoAction
      • *
    *
    21. - *
  21. DELETE_RULE - short - how to treat foreign key when primary key is - * deleted: + *
  22. {@code DELETE_RULE} - short - how to treat the foreign key when the corresponding primary + * key is deleted: *
      - *
    • DatabaseMetaData.importedKeyNoAction - don't allow delete of primary - * key if imported
      • - *
    • DatabaseMetaData.importedKeyCascade - the deletion should also - * delete rows that import a deleted key
      • - *
    • DatabaseMetaData.importedKeySetNull - it should set the imported key - * to null
      • - *
    • DatabaseMetaData.importedKeySetDefault - deletion sets the imported - * key to default values
      • - *
    • DatabaseMetaData.importedKeyRestrict - same as importedKeyNoAction
      • + *
    • {@code DatabaseMetaData.importedKeyNoAction} - don't allow the + * primary key to be deleted if it is imported as a foreign key
      • + *
    • {@code DatabaseMetaData.importedKeyCascade} - the deletion should + * also delete rows that import a deleted key
      • + *
    • {@code DatabaseMetaData.importedKeySetNull} - the deletion sets the + * imported key to {@code null}
      • + *
    • {@code DatabaseMetaData.importedKeySetDefault} - the deletion sets the + * imported key to its default value
      • + *
    • {@code DatabaseMetaData.importedKeyRestrict} - same as + * importedKeyNoAction
      • *
    *
    23. - *
  23. FK_NAME - String - foreign key name (possibly null)
    24. - *
  24. PK_NAME - String - primary key name (possibly null)
    25. - *
  25. DEFERRABILITY - short - defines whether foreign key constraints can - * be deferred until commit (see SQL92 specification for definitions): + *
  26. {@code FK_NAME} - String - the foreign key name (possibly {@code null})
    27. + *
  27. {@code PK_NAME} - String - the primary key name (possibly {@code null})
    28. + *
  28. {@code DEFERRABILITY} - short - defines whether the foreign key + * constraints can be deferred until commit (see the SQL92 specification for + * definitions): *
      - *
    • DatabaseMetaData.importedKeyInitiallyDeferred
      • - *
    • DatabaseMetaData.importedKeyInitiallyImmediate
      • - *
    • DatabaseMetaData.importedKeyNotDeferrable
      • + *
    • {@code DatabaseMetaData.importedKeyInitiallyDeferred}
      • + *
    • {@code DatabaseMetaData.importedKeyInitiallyImmediate}
      • + *
    • {@code DatabaseMetaData.importedKeyNotDeferrable}
      • *
    *
    29. *
- * + * * @param catalog - * a Catalog Name. null is used to imply no - * narrowing of the search using Catalog Name. Otherwise, the - * name must match a Catalog Name held in the database, with "" - * used to retrieve those without a Catalog Name. + * a catalog name. {@code null} is used to imply no narrowing of + * the search by catalog name. Otherwise, the name must match a + * catalog name held in the database, with "" used to retrieve + * those without a catalog name. * @param schema - * a Schema Name. null is used to imply no - * narrowing of the search using Schema Name. Otherwise, the name - * must match a Schema name in the database, with "" used to - * retrieve those without a Schema name. + * a schema name. {@code null} is used to imply no narrowing of + * the search by schema name. Otherwise, the name must match a + * schema name in the database, with "" used to retrieve those + * without a schema name. * @param table * a table name, which must match the name of a table in the * database - * @return a ResultSet containing a row for each of the foreign key columns, - * as defined above + * @return a {@code ResultSet} containing a row for each of the foreign key + * columns, as defined above * @throws SQLException * a database error occurred */ @@ -961,197 +956,201 @@ throws SQLException; /** - * Answers a string of characters that may be used in unquoted identifier - * names. The characters a-z, A-Z, 0-9 and _ are always permitted. + * Returns a string of characters that may be used in unquoted identifier + * names. The characters {@code a-z}, {@code A-Z}, {@code 0-9} and {@code _} + * are always permitted. * - * @return a String containing all the extra characters + * @return a String containing all the additional permitted characters. * @throws SQLException - * a database error occurred + * a database error occurred. */ public String getExtraNameCharacters() throws SQLException; /** - * Answers the string used to quote SQL identifiers. Returns " " (space) if + * Returns the string used to quote SQL identifiers. Returns " " (space) if * identifier quoting not supported. * * @return the String used to quote SQL identifiers. * @throws SQLException - * a database error occurred + * a database error occurred. */ public String getIdentifierQuoteString() throws SQLException; /** - * Answers a list columns in a table that are both primary keys and + * Returns a list columns in a table that are both primary keys and * referenced by the table's foreign key columns (that is, the primary keys * imported by a table). *

- * The list returned is a ResultSet with a row entry for each - * primary key column, ordered by PKTABLE_CAT, - * PKTABLE_SCHEM, PKTABLE_NAME, and - * KEY_SEQ, with the following format: + * The list returned is a {@code ResultSet} with a row entry for each + * primary key column, ordered by {@code PKTABLE_CAT}, {@code PKTABLE_SCHEM}, + * {@code PKTABLE_NAME}, and {@code KEY_SEQ}, with the following format: *

    - *
  1. PKTABLE_CAT - String - primary key Catalog name being - * imported (possibly null)
    2. - *
  2. PKTABLE_SCHEM - String - primary key Schema name - * being imported (possibly null)
    3. - *
  3. PKTABLE_NAME - String - primary key Table name being - * imported
    4. - *
  4. PKCOLUMN_NAME - String - primary key column name - * being imported
    5. - *
  5. FKTABLE_CAT - String - foreign key table catalog name - * (possibly null)
    6. - *
  6. FKTABLE_SCHEM - String - foreign key table Schema - * name (possibly null)
    7. - *
  7. FKTABLE_NAME - String - foreign key table name
    8. - *
  8. FKCOLUMN_NAME - String - foreign key column name
    9. - *
  9. KEY_SEQ - short - sequence number in the foreign key
    10. - *
  10. UPDATE_RULE - short - how to treat foreign key when primary key is - * updated: + *
  11. {@code PKTABLE_CAT} - String - primary key catalog name being + * imported (possibly {@code null})
    12. + *
  12. {@code PKTABLE_SCHEM} - String - primary key schema name being + * imported (possibly {@code null})
    13. + *
  13. {@code PKTABLE_NAME} - String - primary key table name being imported + *
    14. + *
  14. {@code PKCOLUMN_NAME} - String - primary key column name being + * imported
    15. + *
  15. {@code FKTABLE_CAT} - String - foreign key table catalog name + * (possibly {@code null})
    16. + *
  16. {@code FKTABLE_SCHEM} - String - foreign key table schema name + * (possibly {@code null})
    17. + *
  17. {@code FKTABLE_NAME} - String - foreign key table name
    18. + *
  18. {@code FKCOLUMN_NAME} - String - foreign key column name
    19. + *
  19. {@code KEY_SEQ} - short - sequence number (in the foreign key)
    20. + *
  20. {@code UPDATE_RULE} - short - how to treat the foreign key when the corresponding primary + * key is updated: *
      - *
    • DatabaseMetaData.importedKeyNoAction - don't allow update of primary - * key if imported
      • - *
    • DatabaseMetaData.importedKeyCascade - change imported key to match - * the primary key update
      • - *
    • DatabaseMetaData.importedKeySetNull - set the imported key to - * null
      • - *
    • DatabaseMetaData.importedKeySetDefault - set the imported key to - * default values
      • - *
    • DatabaseMetaData.importedKeyRestrict - same as importedKeyNoAction
      • + *
    • {@code DatabaseMetaData.importedKeyNoAction} - don't allow any update of + * the primary key if it is imported as a foreign key
      • + *
    • {@code DatabaseMetaData.importedKeyCascade} - change imported key to + * match the primary key update
      • + *
    • {@code DatabaseMetaData.importedKeySetNull} - set the imported key to + * {@code null}
      • + *
    • {@code DatabaseMetaData.importedKeySetDefault} - set the imported key + * to its default value
      • + *
    • {@code DatabaseMetaData.importedKeyRestrict} - same as + * importedKeyNoAction
      • *
    *
    21. - *
  21. DELETE_RULE - short - how to treat foreign key when primary key is - * deleted: + *
  22. {@code DELETE_RULE} - short - how to treat the foreign key when the corresponding primary + * key is deleted: *
      - *
    • DatabaseMetaData.importedKeyNoAction - don't allow delete of primary - * key if imported
      • - *
    • DatabaseMetaData.importedKeyCascade - delete those rows that import - * a deleted key
      • - *
    • DatabaseMetaData.importedKeySetNull - set the imported key to - * null
      • - *
    • DatabaseMetaData.importedKeySetDefault - set the imported key to - * default values
      • - *
    • DatabaseMetaData.importedKeyRestrict - same as importedKeyNoAction
      • + *
    • {@code DatabaseMetaData.importedKeyNoAction} - don't allow the primary key to be deleted + * if it is imported as a foreign key
      • + *
    • {@code DatabaseMetaData.importedKeyCascade} - delete those rows that + * import a deleted key
      • + *
    • {@code DatabaseMetaData.importedKeySetNull} - set the imported key to + * {@code null}
      • + *
    • {@code DatabaseMetaData.importedKeySetDefault} - set the imported key + * to its default value
      • + *
    • {@code DatabaseMetaData.importedKeyRestrict} - same as {@code + * importedKeyNoAction}
      • *
    *
    23. - *
  23. FK_NAME - String - foreign key name (possibly null)
    24. - *
  24. PK_NAME - String - primary key name (possibly null)
    25. - *
  25. DEFERRABILITY - short - defines whether foreign key constraints can - * be deferred until commit (see SQL92 specification for definitions): + *
  26. {@code FK_NAME} - String - foreign key name (possibly {@code null})
    27. + *
  27. {@code PK_NAME} - String - primary key name (possibly {@code null})
    28. + *
  28. {@code DEFERRABILITY} - short - defines whether foreign key + * constraints can be deferred until commit (see SQL92 specification for + * definitions): *
      - *
    • DatabaseMetaData.importedKeyInitiallyDeferred
      • - *
    • DatabaseMetaData.importedKeyInitiallyImmediate
      • - *
    • DatabaseMetaData.importedKeyNotDeferrable
      • + *
    • {@code DatabaseMetaData.importedKeyInitiallyDeferred}
      • + *
    • {@code DatabaseMetaData.importedKeyInitiallyImmediate}
      • + *
    • {@code DatabaseMetaData.importedKeyNotDeferrable}
      • *
    *
    29. *
- * + * * @param catalog - * a Catalog Name. null is used to imply no - * narrowing of the search using Catalog Name. Otherwise, the - * name must match a Catalog Name held in the database, with "" - * used to retrieve those without a Catalog Name. + * a catalog name. {@code null} is used to imply no narrowing of + * the search by catalog name. Otherwise, the name must match a + * catalog name held in the database, with "" used to retrieve + * those without a catalog name. * @param schema - * a Schema Name. null is used to imply no - * narrowing of the search using Schema Name. Otherwise, the name - * must match a Schema name in the database, with "" used to - * retrieve those without a Schema name. + * a schema name. {@code null} is used to imply no narrowing of + * the search by schema name. Otherwise, the name must match a + * schema name in the database, with "" used to retrieve those + * without a schema name. * @param table * a table name, which must match the name of a table in the - * database - * @return a ResultSet containing the list of primary key columns as rows in - * the format defined above. + * database. + * @return a {@code ResultSet} containing the list of primary key columns as + * rows in the format defined above. * @throws SQLException - * a database error occurred + * a database error occurred. */ public ResultSet getImportedKeys(String catalog, String schema, String table) throws SQLException; /** - * Answers a list of indices and statistics for a specified table. + * Returns a list of indices and statistics for a specified table. *

- * The list is returned as a ResultSet, with one row for each index or - * statistic. The list is ordered by NON_UNIQUE, TYPE, INDEX_NAME, and - * ORDINAL_POSITION. Each row has the following format: + * The list is returned as a {@code ResultSet}, with one row for each index + * or statistic. The list is ordered by {@code NON_UNIQUE}, {@code TYPE}, + * {@code INDEX_NAME}, and {@code ORDINAL_POSITION}. Each row has the + * following format: *

    - *
  1. TABLE_CAT - String - table catalog name (possibly - * null)
    2. - *
  2. TABLE_SCHEM - String - Table Schema name (possibly - * null)
    3. - *
  3. TABLE_NAME - String - The Table name
    4. - *
  4. NON_UNIQUE - boolean - true when index - * values can be non-unique. Must be false when TYPE is - * tableIndexStatistic
    5. - *
  5. INDEX_QUALIFIER - String : index catalog name. - * null when TYPE is 'tableIndexStatistic'
    6. - *
  6. INDEX_NAME - String : index name. null - * when TYPE is 'tableIndexStatistic'
    7. - *
  7. TYPE - short - the index type. One of: + *
  8. {@code TABLE_CAT} - String - table catalog name (possibly {@code + * null})
    9. + *
  9. {@code TABLE_SCHEM} - String - table schema name (possibly {@code + * null})
    10. + *
  10. {@code TABLE_NAME} - String - The table name
    11. + *
  11. {@code NON_UNIQUE} - boolean - {@code true} when index values can be + * non-unique. Must be {@code false} when the TYPE is tableIndexStatistic
    12. + *
  12. {@code INDEX_QUALIFIER} - String : index catalog name. {@code null} + * when the TYPE is 'tableIndexStatistic'
    13. + *
  13. {@code INDEX_NAME} - String : index name. {@code null} when TYPE is + * 'tableIndexStatistic'
    14. + *
  14. {@code TYPE} - short - the index type. One of: *
      - *
    • DatabaseMetaData.tableIndexStatistic - table statistics returned - * with Index descriptions
      • - *
    • DatabaseMetaData.tableIndexClustered - a clustered Index
      • - *
    • DatabaseMetaData.tableIndexHashed - a hashed Index
      • - *
    • DatabaseMetaData.tableIndexOther - other style of Index
      • + *
    • {@code DatabaseMetaData.tableIndexStatistic} - table statistics + * returned with Index descriptions
      • + *
    • {@code DatabaseMetaData.tableIndexClustered} - a clustered Index
      • + *
    • {@code DatabaseMetaData.tableIndexHashed} - a hashed Index
      • + *
    • {@code DatabaseMetaData.tableIndexOther} - other style of Index
      • *
    *
    15. - *
  15. ORDINAL_POSITION - short - column sequence within Index. 0 when TYPE - * is tableIndexStatistic
    16. - *
  16. COLUMN_NAME - String - the column name. - * null when TYPE is tableIndexStatistic
    17. - *
  17. ASC_OR_DESC - String - column sort sequence. null if + *
  18. {@code ORDINAL_POSITION} - short - column sequence within Index. 0 + * when TYPE is tableIndexStatistic
    19. + *
  19. {@code COLUMN_NAME} - String - the column name. {@code null} when + * TYPE is tableIndexStatistic
    20. + *
  20. {@code ASC_OR_DESC} - String - column sort sequence. {@code null} if * sequencing not supported or TYPE is tableIndexStatistic; otherwise "A" - * means sort ascending and "D" means sort descending.
    21. - *
  21. CARDINALITY - int - Number of unique values in the Index. If TYPE is - * tableIndexStatistic, this is number of rows in the table.
    22. - *
  22. PAGES - int - Number of pages for current Index. If TYPE is + * means sort ascending and "D" means sort descending.
    23. + *
  23. {@code CARDINALITY} - int - Number of unique values in the Index. If + * TYPE is tableIndexStatistic, this is number of rows in the table.
    24. + *
  24. {@code PAGES} - int - Number of pages for current Index. If TYPE is * tableIndexStatistic, this is number of pages used for the table.
    25. - *
  25. FILTER_CONDITION - String - Filter condition. (possibly null)
    26. + *
  26. {@code FILTER_CONDITION} - String - Filter condition. (possibly null) + *
    27. *
- * + * * @param catalog - * a Catalog Name. null is used to imply no narrowing of the - * search using Catalog Name. Otherwise, the name must match a - * Catalog Name held in the database, with "" used to retrieve - * those without a Catalog Name. + * a catalog name. {@code null} is used to imply no narrowing of + * the search by catalog name. Otherwise, the name must match a + * catalog name held in the database, with "" used to retrieve + * those without a catalog name. * @param schema - * a Schema Name. null is used to imply no narrowing of the - * search using Schema Name. Otherwise, the name must match a - * Schema name in the database, with "" used to retrieve those - * without a Schema name. + * a schema name. {@code null} is used to imply no narrowing of + * the search by schema name. Otherwise, the name must match a + * schema name in the database, with "" used to retrieve those + * without a schema name. * @param table * a table name, which must match the name of a table in the - * database + * database. * @param unique - * true means only return indices for unique - * values, false implies that they can be returned - * even if not unique. + * {@code true} means only return indices for unique values, + * {@code false} implies that they can be returned even if not + * unique. * @param approximate - * true implies that the list can contain - * approximate or "out of data" values, false - * implies that all values must be precisely accurate - * @return a ResultSet containing the list of indices and statistics for the - * table, in the format defined above. + * {@code true} implies that the list can contain approximate or + * "out of data" values, {@code false} implies that all values + * must be precisely accurate + * @return a {@code ResultSet} containing the list of indices and statistics + * for the table, in the format defined above. * @throws SQLException - * a database error occurred + * a database error occurred. */ public ResultSet getIndexInfo(String catalog, String schema, String table, boolean unique, boolean approximate) throws SQLException; /** - * Answers this driver's major JDBC version number. + * Returns this driver's major JDBC version number. * - * @return the major JDBC version number + * @return the major JDBC version number. * @throws SQLException - * a database error occurred + * a database error occurred. */ public int getJDBCMajorVersion() throws SQLException; /** - * Answers the minor JDBC version number for this driver. + * Returns the minor JDBC version number for this driver. * - * @return the Minor JDBC Version Number + * @return the Minor JDBC Version Number. * @throws SQLException - * a database error occurred + * a database error occurred. */ public int getJDBCMinorVersion() throws SQLException; @@ -1162,166 +1161,171 @@ * @return the maximum number of hex characters in an in-line binary * literal. If the number is unlimited then the result is zero. * @throws SQLException - * a database error occurred + * a database error occurred. */ public int getMaxBinaryLiteralLength() throws SQLException; /** - * Answers the maximum size of a Catalog name in this database. + * Returns the maximum size of a catalog name in this database. * - * @return the maximum size in characters for a Catalog name. If the limit + * @return the maximum size in characters for a catalog name. If the limit * is unknown, or the value is unlimited, then the result is zero. * @throws SQLException - * a database error occurred + * a database error occurred. */ public int getMaxCatalogNameLength() throws SQLException; /** - * Answers the maximum size for a character literal in this database. + * Returns the maximum size for a character literal in this database. * * @return the maximum size in characters for a character literal. If the * limit is unknown, or the value is unlimited, then the result is * zero. * @throws SQLException - * a database error occurred + * a database error occurred. */ public int getMaxCharLiteralLength() throws SQLException; /** - * Answers the maximum size for a Column name for this database. + * Returns the maximum size for a Column name for this database. * * @return the maximum number of characters for a Column name. If the limit * is unknown, or the value is unlimited, then the result is zero. * @throws SQLException - * a database error occurred + * a database error occurred. */ public int getMaxColumnNameLength() throws SQLException; /** - * Get the maximum number of columns in a GROUP BY clause for this database. + * Get the maximum number of columns in a {@code GROUP BY} clause for this + * database. * - * @return the maximum number of columns in a GROUP BY clause. If the limit - * is unknown, or the value is unlimited, then the result is zero. + * @return the maximum number of columns in a {@code GROUP BY} clause. If + * the limit is unknown, or the value is unlimited, then the result + * is zero. * @throws SQLException - * a database error occurred + * a database error occurred. */ public int getMaxColumnsInGroupBy() throws SQLException; /** - * Answers the maximum number of columns in an Index for this database. + * Returns the maximum number of columns in an Index for this database. * * @return the maximum number of columns in an Index. If the limit is * unknown, or the value is unlimited, then the result is zero. * @throws SQLException - * a database error occurred + * a database error occurred. */ public int getMaxColumnsInIndex() throws SQLException; /** - * Answers the maximum number of columns in an ORDER BY clause for this - * database. + * Returns the maximum number of columns in an {@code ORDER BY} clause for + * this database. * - * @return the maximum number of columns in an ORDER BY clause. If the limit - * is unknown, or the value is unlimited, then the result is zero. + * @return the maximum number of columns in an {@code ORDER BY} clause. If + * the limit is unknown, or the value is unlimited, then the result + * is zero. * @throws SQLException - * a database error occurred + * a database error occurred. */ public int getMaxColumnsInOrderBy() throws SQLException; /** - * Answers the maximum number of columns in a SELECT list for this database. + * Returns the maximum number of columns in a {@code SELECT} list for this + * database. * - * @return the maximum number of columns in a SELECT list. If the limit is - * unknown, or the value is unlimited, then the result is zero. + * @return the maximum number of columns in a {@code SELECT} list. If the + * limit is unknown, or the value is unlimited, then the result is + * zero. [... 2708 lines stripped ...]