Generated by
JDiff

java.sql Documentation Differences

This file contains all the changes in documentation in the package java.sql as colored differences. Deletions are shown like this, and additions are shown like this.
If no deletions or additions are shown in an entry, the HTML tags will be what has changed. The new HTML tags are shown in the differences. If no documentation existed, and then some was added in a later version, this change is noted in the appropriate class pages of differences, but the change is not shown on this page. Only changes in existing text are shown here. Similarly, documentation which was inherited from another class or interface is not shown here.
Note that an HTML error in the new documentation may cause the display of other documentation changes to be presented incorrectly. For instance, failure to close a <code> tag will cause all subsequent paragraphs to be displayed differently.

Class CallableStatement, void setNull(String, int, String)

Sets the designated parameter to SQL NULL. This version of the method setNull should be used for user-defined types and REF type parameters. Examples of user-defined types include: STRUCT DISTINCT JAVA_OBJECT and named array types.

Note: To be portable applications must give the SQL type code and the fully-qualified SQL type name when specifying a NULL user-defined or REF parameter. In the case of a user-defined type the name is the type name of the parameter itself. For a REF parameter the name is the type name of the referenced type. If a JDBC driver does not need the type code or type name information it may ignore it. Although it is intended for user-defined and Ref parameters this method may be used to set a null parameter of any JDBC type. If the parameter does not have a user-defined or REF type the given typeName is ignored. @param paramNameparameterName the name of the parameter @param sqlType a value from java.sql.Types @param typeName the fully-qualified name of an SQL user-defined type; ignored if the parameter is not a user-defined type or SQL REF value @exception SQLException if a database access error occurs @since 1.4


Class Connection, PreparedStatement prepareStatement(String, int)

Creates a default PreparedStatement object that has the capability to retrieve auto-generated keys. The given constant tells the driver whether it should make auto-generated keys available for retrieval. This parameter is ignored if the SQL statement is not an INSERT statement.

Note: This method is optimized for handling parametric SQL statements that benefit from precompilation. If the driver supports precompilation the method prepareStatement will send the statement to the database for precompilation. Some drivers may not support precompilation. In this case the statement may not be sent to the database until the PreparedStatement object is executed. This has no direct effect on users; however it does affect which methods throw certain SQLExceptions.

Result sets created using the returned PreparedStatement object will by default be type TYPE_FORWARD_ONLY and have a concurrency level of CONCUR_READ_ONLY. @param sql an SQL statement that may contain one or more ' ' IN parameter placeholders @param autoGeneratedKeys a flag indicating whether auto-generated keys should be returned; one of the following Statement constants: @param autoGeneratedKeys a flag indicating that auto-generated keys should be returned one of Statement.RETURN_GENERATED_KEYS or Statement.NO_GENERATED_KEYS. @return a new PreparedStatement object containing the pre-compiled SQL statement that will have the capability of returning auto-generated keys @exception SQLException if a database access error occurs or the given parameter is not a Statement constant indicating whether auto-generated keys should be returned @since 1.4


Class DatabaseMetaData, ResultSet getAttributes(String, String, String, String)

Retrieves a description of the given attribute of the given type for a user-defined type (UDT) that is available in the given schema and catalog.

Descriptions are returned only for attributes of UDTs matching the catalog schema type and attribute name criteria. They are ordered by TYPE_SCHEM TYPE_NAME and ORDINAL_POSITION. This description does not contain inherited attributes.

The ResultSet object that is returned has the following columns:

  1. TYPE_CAT String => type catalog (may be null)
  2. TYPE_SCHEM String => type schema (may be null)
  3. TYPE_NAME String => type name
  4. ATTR_NAME String => attribute name
  5. DATA_TYPE shortint => attribute type SQL type from java.sql.Types
  6. ATTR_TYPE_NAME String => Data source dependent type name. For a UDT the type name is fully qualified. For a REF the type name is fully qualified and represents the target type of the reference type.
  7. ATTR_SIZE int => column size. For char or date types this is the maximum number of characters; for numeric or decimal types this is precision.
  8. DECIMAL_DIGITS int => the number of fractional digits
  9. NUM_PREC_RADIX int => Radix (typically either 10 or 2)
  10. NULLABLE int => whether NULL is allowed
    • attributeNoNulls - might not allow NULL values
    • attributeNullable - definitely allows NULL values
    • attributeNullableUnknown - nullability unknown
  11. REMARKS String => comment describing column (may be null)
  12. ATTR_DEF String => default value (may be null)
  13. SQL_DATA_TYPE int => unused
  14. SQL_DATETIME_SUB int => unused
  15. CHAR_OCTET_LENGTH int => for char types the maximum number of bytes in the column
  16. ORDINAL_POSITION int => index of column in table (starting at 1)
  17. IS_NULLABLE String => "NO" means column definitely does not allow NULL values; "YES" means the column might allow NULL values. An empty string means unknown.
  18. SCOPE_CATALOG String => catalog of table that is the scope of a reference attribute (null if DATA_TYPE isn't REF)
  19. SCOPE_SCHEMA String => schema of table that is the scope of a reference attribute (null if DATA_TYPE isn't REF)
  20. SCOPE_TABLE String => table name that is the scope of a reference attribute (null if the DATA_TYPE isn't REF)
  21. SOURCE_DATA_TYPE short => source type of a distinct type or user-generated Ref type SQL type from java.sql.Types (null if DATA_TYPE isn't DISTINCT or user-generated REF)
@param catalog a catalog name; must match the catalog name as it is stored in the database; "" retrieves those without a catalog; null means that the catalog name should not be used to narrow the search @param schemaPattern a schema name pattern; must match the schema name as it is stored in the database; "" retrieves those without a schema; null means that the schema name should not be used to narrow the search @param typeNamePattern a type name pattern; must match the type name as it is stored in the database @param attributeNamePattern an attribute name pattern; must match the attribute name as it is declared in the database @return a ResultSet object in which each row is an attribute description @exception SQLException if a database access error occurs @since 1.4
Class DatabaseMetaData, ResultSet getBestRowIdentifier(String, String, String, int, boolean)

Retrieves a description of a table's optimal set of columns that uniquely identifies a row. They are ordered by SCOPE.

Each column description has the following columns:

  1. SCOPE short => actual scope of result
    • bestRowTemporary - very temporary while using row
    • bestRowTransaction - valid for remainder of current transaction
    • bestRowSession - valid for remainder of current session
  2. COLUMN_NAME String => column name
  3. DATA_TYPE shortint => SQL data type from java.sql.Types
  4. TYPE_NAME String => Data source dependent type name for a UDT the type name is fully qualified
  5. COLUMN_SIZE int => precision
  6. BUFFER_LENGTH int => not used
  7. DECIMAL_DIGITS short => scale
  8. PSEUDO_COLUMN short => is this a pseudo column like an Oracle ROWID
    • bestRowUnknown - may or may not be pseudo column
    • bestRowNotPseudo - is NOT a pseudo column
    • bestRowPseudo - is a pseudo column
@param catalog a catalog name; must match the catalog name as it is stored in the database; "" retrieves those without a catalog; null means that the catalog name should not be used to narrow the search @param schema a schema name; must match the schema name as it is stored in the database; "" retrieves those without a schema; null means that the schema name should not be used to narrow the search @param table a table name; must match the table name as it is stored in the database @param scope the scope of interest; use same values as SCOPE @param nullable include columns that are nullable. @return ResultSet - each row is a column description @exception SQLException if a database access error occurs
Class DatabaseMetaData, ResultSet getColumns(String, String, String, String)

Retrieves a description of table columns available in the specified catalog.

Only column descriptions matching the catalog schema table and column name criteria are returned. They are ordered by TABLE_SCHEM TABLE_NAME and ORDINAL_POSITION.

Each column description has the following columns:

  1. TABLE_CAT String => table catalog (may be null)
  2. TABLE_SCHEM String => table schema (may be null)
  3. TABLE_NAME String => table name
  4. COLUMN_NAME String => column name
  5. DATA_TYPE shortint => SQL type from java.sql.Types
  6. TYPE_NAME String => Data source dependent type name for a UDT the type name is fully qualified
  7. COLUMN_SIZE int => column size. For char or date types this is the maximum number of characters for numeric or decimal types this is precision.
  8. BUFFER_LENGTH is not used.
  9. DECIMAL_DIGITS int => the number of fractional digits
  10. NUM_PREC_RADIX int => Radix (typically either 10 or 2)
  11. NULLABLE int => is NULL allowed.
    • columnNoNulls - might not allow NULL values
    • columnNullable - definitely allows NULL values
    • columnNullableUnknown - nullability unknown
  12. REMARKS String => comment describing column (may be null)
  13. COLUMN_DEF String => default value (may be null)
  14. SQL_DATA_TYPE int => unused
  15. SQL_DATETIME_SUB int => unused
  16. CHAR_OCTET_LENGTH int => for char types the maximum number of bytes in the column
  17. ORDINAL_POSITION int => index of column in table (starting at 1)
  18. IS_NULLABLE String => "NO" means column definitely does not allow NULL values; "YES" means the column might allow NULL values. An empty string means nobody knows.
  19. SCOPE_CATLOG String => catalog of table that is the scope of a reference attribute (null if DATA_TYPE isn't REF)
  20. SCOPE_SCHEMA String => schema of table that is the scope of a reference attribute (null if the DATA_TYPE isn't REF)
  21. SCOPE_TABLE String => table name that this the scope of a reference attribure (null if the DATA_TYPE isn't REF)
  22. SOURCE_DATA_TYPE short => source type of a distinct type or user-generated Ref type SQL type from java.sql.Types (null if DATA_TYPE isn't DISTINCT or user-generated REF)
@param catalog a catalog name; must match the catalog name as it is stored in the database; "" retrieves those without a catalog; null means that the catalog name should not be used to narrow the search @param schemaPattern a schema name pattern; must match the schema name as it is stored in the database; "" retrieves those without a schema; null means that the schema name should not be used to narrow the search @param tableNamePattern a table name pattern; must match the table name as it is stored in the database @param columnNamePattern a column name pattern; must match the column name as it is stored in the database @return ResultSet - each row is a column description @exception SQLException if a database access error occurs @see #getSearchStringEscape
Class DatabaseMetaData, ResultSet getProcedureColumns(String, String, String, String)

Retrieves a description of the given catalog's stored procedure parameter and result columns.

Only descriptions matching the schema procedure and parameter name criteria are returned. They are ordered by PROCEDURE_SCHEM and PROCEDURE_NAME. Within this the return value if any is first. Next are the parameter descriptions in call order. The column descriptions follow in column number order.

Each row in the ResultSet is a parameter description or column description with the following fields:

  1. PROCEDURE_CAT String => procedure catalog (may be null)
  2. PROCEDURE_SCHEM String => procedure schema (may be null)
  3. PROCEDURE_NAME String => procedure name
  4. COLUMN_NAME String => column/parameter name
  5. COLUMN_TYPE Short => kind of column/parameter:
    • procedureColumnUnknown - nobody knows
    • procedureColumnIn - IN parameter
    • procedureColumnInOut - INOUT parameter
    • procedureColumnOut - OUT parameter
    • procedureColumnReturn - procedure return value
    • procedureColumnResult - result column in ResultSet
  6. DATA_TYPE shortint => SQL type from java.sql.Types
  7. TYPE_NAME String => SQL type name for a UDT type the type name is fully qualified
  8. PRECISION int => precision
  9. LENGTH int => length in bytes of data
  10. SCALE short => scale
  11. RADIX short => radix
  12. NULLABLE short => can it contain NULL.
    • procedureNoNulls - does not allow NULL values
    • procedureNullable - allows NULL values
    • procedureNullableUnknown - nullability unknown
  13. REMARKS String => comment describing parameter/column

Note: Some databases may not return the column descriptions for a procedure. Additional columns beyond REMARKS can be defined by the database. @param catalog a catalog name; must match the catalog name as it is stored in the database; "" retrieves those without a catalog; null means that the catalog name should not be used to narrow the search @param schemaPattern a schema name pattern; must match the schema name as it is stored in the database; "" retrieves those without a schema; null means that the schema name should not be used to narrow the search @param procedureNamePattern a procedure name pattern; must match the procedure name as it is stored in the database @param columnNamePattern a column name pattern; must match the column name as it is stored in the database @return ResultSet - each row describes a stored procedure parameter or column @exception SQLException if a database access error occurs @see #getSearchStringEscape

Class DatabaseMetaData, int getSQLStateType()

Indicates whether the SQLSTATEsSQLSTATE returned by SQLException.getSQLState is X/Open (now known as Open Group) SQL CLI or SQL99. @return the type of SQLSTATEsSQLSTATE; one of: sqlStateXOpen or sqlStateSQL99 @throws SQLException if a database access error occurs @since 1.4
Class DatabaseMetaData, ResultSet getTypeInfo()

Retrieves a description of all the standard SQL types supported by this database. They are ordered by DATA_TYPE and then by how closely the data type maps to the corresponding JDBC SQL type.

Each type description has the following columns:

  1. TYPE_NAME String => Type name
  2. DATA_TYPE shortint => SQL data type from java.sql.Types
  3. PRECISION int => maximum precision
  4. LITERAL_PREFIX String => prefix used to quote a literal (may be null)
  5. LITERAL_SUFFIX String => suffix used to quote a literal (may be null)
  6. CREATE_PARAMS String => parameters used in creating the type (may be null)
  7. NULLABLE short => can you use NULL for this type.
    • typeNoNulls - does not allow NULL values
    • typeNullable - allows NULL values
    • typeNullableUnknown - nullability unknown
  8. CASE_SENSITIVE boolean=> is it case sensitive.
  9. SEARCHABLE short => can you use "WHERE" based on this type:
    • typePredNone - No support
    • typePredChar - Only supported with WHERE .. LIKE
    • typePredBasic - Supported except for WHERE .. LIKE
    • typeSearchable - Supported for all WHERE ..
  10. UNSIGNED_ATTRIBUTE boolean => is it unsigned.
  11. FIXED_PREC_SCALE boolean => can it be a money value.
  12. AUTO_INCREMENT boolean => can it be used for an auto-increment value.
  13. LOCAL_TYPE_NAME String => localized version of type name (may be null)
  14. MINIMUM_SCALE short => minimum scale supported
  15. MAXIMUM_SCALE short => maximum scale supported
  16. SQL_DATA_TYPE int => unused
  17. SQL_DATETIME_SUB int => unused
  18. NUM_PREC_RADIX int => usually 2 or 10
@return a ResultSet object in which each row is an SQL type description @exception SQLException if a database access error occurs
Class DatabaseMetaData, ResultSet getUDTs(String, String, String, int[])

Retrieves a description of the user-defined types (UDTs) defined in a particular schema. Schema-specific UDTs may have type JAVA_OBJECT STRUCT or DISTINCT.

Only types matching the catalog schema type name and type criteria are returned. They are ordered by DATA_TYPE TYPE_SCHEM and TYPE_NAME. The type name parameter may be a fully-qualified name. In this case the catalog and schemaPattern parameters are ignored.

Each type description has the following columns:

  1. TYPE_CAT String => the type's catalog (may be null)
  2. TYPE_SCHEM String => type's schema (may be null)
  3. TYPE_NAME String => type name
  4. CLASS_NAME String => Java class name
  5. DATA_TYPE Stringint => type value defined in java.sql.Types. One of JAVA_OBJECT STRUCT or DISTINCT
  6. REMARKS String => explanatory comment on the type
  7. BASE_TYPE short => type code of the source type of a DISTINCT type or the type that implements the user-generated reference type of the SELF_REFERENCING_COLUMN of a structured type as defined in java.sql.Types (null if DATA_TYPE is not DISTINCT or not STRUCT with REFERENCE_GENERATION = USER_DEFINED)

Note: If the driver does not support UDTs an empty result set is returned. @param catalog a catalog name; must match the catalog name as it is stored in the database; "" retrieves those without a catalog; null means that the catalog name should not be used to narrow the search @param schemaPattern a schema pattern name; must match the schema name as it is stored in the database; "" retrieves those without a schema; null means that the schema name should not be used to narrow the search @param typeNamePattern a type name pattern; must match the type name as it is stored in the database; may be a fully qualified name @param types a list of user-defined types (JAVA_OBJECT STRUCT or DISTINCT) to include; null returns all types @return ResultSet object in which each row describes a UDT @exception SQLException if a database access error occurs @since 1.2

Class DatabaseMetaData, ResultSet getVersionColumns(String, String, String)

Retrieves a description of a table's columns that are automatically updated when any value in a row is updated. They are unordered.

Each column description has the following columns:

  1. SCOPE short => is not used
  2. COLUMN_NAME String => column name
  3. DATA_TYPE shortint => SQL data type from java.sql.Types
  4. TYPE_NAME String => Data source-dependent type name
  5. COLUMN_SIZE int => precision
  6. BUFFER_LENGTH int => length of column value in bytes
  7. DECIMAL_DIGITS short => scale
  8. PSEUDO_COLUMN short => whether this is pseudo column like an Oracle ROWID
    • versionColumnUnknown - may or may not be pseudo column
    • versionColumnNotPseudo - is NOT a pseudo column
    • versionColumnPseudo - is a pseudo column
@param catalog a catalog name; must match the catalog name as it is stored in the database; "" retrieves those without a catalog; null means that the catalog name should not be used to narrow the search @param schema a schema name; must match the schema name as it is stored in the database; "" retrieves those without a schema; null means that the schema name should not be used to narrow the search @param table a table name; must match the table name as it is stored in the database @return a ResultSet object in which each row is a column description @exception SQLException if a database access error occurs
Class DatabaseMetaData, boolean supportsStatementPooling()

Retrieves weatherwhether this database supports statement pooling. @return true isif so; false otherwise @throws SQLExcpetion if a database access error occurs @since 1.4

Class PreparedStatement, void setDate(int, Date, Calendar)

Sets the designated parameter to the given java.sql.Date value using the given Calendar object. The driver uses the Calendar object to construct an SQL DATE value which the driver then sends to the database. With a a Calendar object the driver can calculate the date taking into account a custom timezone. If no Calendar object is specified the driver uses the default timezone which is that of the virtual machine running the application. @param parameterIndex the first parameter is 1 the second is 2 ... @param x the parameter value @param cal the Calendar object the driver will use to construct the date @exception SQLException if a database access error occurs @since 1.2
Class PreparedStatement, void setTime(int, Time, Calendar)

Sets the designated parameter to the given java.sql.Time value using the given Calendar object. The driver uses the Calendar object to construct an SQL TIME value which the driver then sends to the database. With a a Calendar object the driver can calculate the time taking into account a custom timezone. If no Calendar object is specified the driver uses the default timezone which is that of the virtual machine running the application. @param parameterIndex the first parameter is 1 the second is 2 ... @param x the parameter value @param cal the Calendar object the driver will use to construct the time @exception SQLException if a database access error occurs @since 1.2

Class ResultSet, Object getObject(String)

Gets the value of the designated column in the current row of this ResultSet object as an Object in the Java programming language.

This method will return the value of the given column as a Java object. The type of the Java object will be the default Java object type corresponding to the column's SQL type following the mapping for built-in types specified in the JDBC specification. If the value is an SQL NULL the driver returns a Java null.

This method may also be used to read datatabasedatabase-specific abstract data types.

In the JDBC 2.0 API the behavior of the method getObject is extended to materialize data of SQL user-defined types. When a column contains a structured or distinct value the behavior of this method is as if it were a call to: getObject(columnIndex this.getStatement().getConnection().getTypeMap()). @param columnName the SQL name of the column @return a java.lang.Object holding the column value @exception SQLException if a database access error occurs

Class ResultSet, Object getObject(int)

Gets the value of the designated column in the current row of this ResultSet object as an Object in the Java programming language.

This method will return the value of the given column as a Java object. The type of the Java object will be the default Java object type corresponding to the column's SQL type following the mapping for built-in types specified in the JDBC specification. If the value is an SQL NULL the driver returns a Java null.

This method may also be used to read datatabasedatabase-specific abstract data types. In the JDBC 2.0 API the behavior of method getObject is extended to materialize data of SQL user-defined types. When a column contains a structured or distinct value the behavior of this method is as if it were a call to: getObject(columnIndex this.getStatement().getConnection().getTypeMap()). @param columnIndex the first column is 1 the second is 2 ... @return a java.lang.Object holding the column value @exception SQLException if a database access error occurs

Class ResultSet, void setFetchSize(int)

Gives the JDBC driver a hint as to the number of rows that should be fetched from the database when more rows are needed for this ResultSet object. If the fetch size specified is zero the JDBC driver ignores the value and is free to make its own best guess as to what the fetch size should be. The default value is set by the Statement object that created the result set. The fetch size may be changed at any time. @param rows the number of rows to fetch @exception SQLException if a database access error occurs or the condition 0 < rows < thisStatement.getMaxRows() is not satisfied @since 1.2 @see #getFetchSize

Class Timestamp, int compareTo(Object)

Compares this Timestamp object to anotherthe given Object which must be a Timestamp object. If the Objectargument is a Datenot thisa functionTimestamp behaves likeobject this compareTo(Timestamp).method Otherwise itthrows a throwsClassCastException aClassCastExceptionobject. (asTimestamp Timestampsobjects are comparable only to other TimestampsTimestamp objects.) @param o the objectObject to be compared which must be a Timestamp object @return the value 0 if thethis argumentTimestamp is a Timestamp equal to this Timestampobject and the given object are equal; a value less than 0 if thethis argumentTimestamp is a Timestamp after this Timestampobject is before the given argument; and a value greater than 0 if thethis argumentTimestamp is a Timestamp before this Timestampobject is after the given argument. @exception ClassCastException if the argument is not a Timestamp. object
Class Timestamp, int compareTo(Timestamp)

Compares twothis Timestamp object to the Timestampsgiven forTimestamp orderingobject. @param ts the Timestamp object to be compared. to this Timestamp object @return the value 0 if the argumenttwo Timestamp is equal to this Timestampobjects are equal; a value less than 0 if this Timestamp object is before the Dategiven argument; and a value greater than 0 if this Timestamp object is after the Timestampgiven argument. @since 1.2
Class Timestamp, String toString()

Formats a timestamp in JDBC timestamp escape format. yyyy-mm-dd hh:mm:ss.fffffffff where ffffffffff indicates nanoseconds.

NOTE: To specify a timestamp for the class java.text.SimpleDateFormat use "yyyy.MM.dd" rather than "yyyy-mm-dd". In the context of java.text.SimpleDateFormat "mm" indicates minutes rather than the month. Note that java.text.SimpleDateFormat does not allow for the nanoseconds component of a Timestamp object. For Example:

 Format Pattern Result -------------- ------ "yyyy.MM.dd G 'at' hh:mm:ss z" --> 2002.07.10 AD at 15:08:56 PDT 
@return a String object in yyyy-mm-dd hh:mm:ss.fffffffff format @overrides toString in class java.util.Date