10 Other New Features and Changes

This chapter describes additional changes that have been made in the JDBC API.

10.1 Changes to java.sql.ResultSet

A version of the ResultSet.getBigDecimal() method that returns full precision has been added.

10.2 Changes to java.sql.ResultSetMetaData

The ResultSetMetaData.getColumnType() method may now return the new SQL type codes: STRUCT, DISTINCT, BLOB, etc. The STRUCT and DISTINCT type codes are always returned for structured and distinct values, independent of whether the default or a custom type mapping is being used.

The ResultSetMetaData.getColumnTypeName() method should return the following for the new SQL types.

Column Type Column Type Name
JAVA_OBJECT the SQL name of the Java type
DISTINCT the SQL name of the distinct type
STRUCT the SQL name of the structured type
ARRAY data source dependent type name
BLOB data source dependent type name
CLOB data source dependent type name
REF data source dependent type name

A ResultSetMetaData.getColumnClassName() method has been added to return the fully qualified name of the Java class whose instances are manufactured if ResultSet.getObject() is called to retrieve a value from the column. See the separate API documentation for details.

The ResultSetMetaData.getColumnTypeName() method returns a fully qualified SQL type name when the type code is STRUCT, DISTINCT, or JAVA_OBJECT.

10.3 Changes to DatabaseMetaData

The DatabaseMetaData.getColumns() method may now return DATA_TYPE values of the new SQL99 types: BLOB, CLOB, etc. The

DatabaseMetaData.getColumns()

method returns the same type names as those listed in Section 10.2 for the SQL99 data types.

Added method DatabasemetaData.getConnection() to return the Connection object that produced the metadata object.

Added method DatabasemetaData.getUDTs(). See the separate API documentation for details.

Added methods to support the new ResultSet and batch update functionality: supportsResultSetConcurrency(), supportsBatchUpdates(), etc. See the separate API documentation for details.

10.4 Changes to java.sql.DriverManager

A DriverManager.setLogWriter() method that takes a java.io.PrintWriter object as input has been added. A new DriverManager.getLogWriter() method returns a PrintWriter object. The set/getLogStream() methods have been deprecated.

10.5 Date, Time, and Timestamp

The JDBC API follows the Java platform's approach of representing dates and times as a millisecond value relative to January 1, 1970 00:00:00 GMT. Since most databases don't support the notion of a time zone, the JDBC 2.1 core API adds new methods to allow a JDBC driver to get/set Date, Time, and Timestamp values for a particular time zone using a Calendar. For example,

ResultSet rs;
...
Date date1 = rs.getDate(1);

returns a Date object that wraps a millisecond value which denotes a particular date, like January 3, 1999, and a normalized time 00:00:00 in the default time zone. The time component of the Date is set to zero in the default time zone since SQL DATE values don't have a time component. Since a Calendar was not supplied explicitly to

getDate()

, the default time zone (really the default Calendar) is used by the JDBC driver internally to create the appropriate millisecond value assuming that the underlying database doesn't store time zone information.

The following example retrieves a date value in GMT-Greenwich Mean Time.

ResultSet rs;
...

TimeZone.setDefault(TimeZone.getTimeZone("GMT"));
Calendar cal = Calendar.getInstance();
Date date2 = rs.getDate(1, cal);

In the example above, a Calendar is passed explicitly to getDate() to inform the JDBC driver how to calculate the appropriate millisecond value. Note that the same result could have been achieved by simply changing the default time zone, and not passing the Calendar explicitly since the JDBC driver will use the default time zone by default.

Note that the two Date objects created above will not compare as equal assuming that the default time zone is not GMT, even if they represent the `same' date.

if (date1.equals(date2))
	//never get here

This is because each Java language Date object really just wraps a normalized millisecond time value and these millisecond values will differ across time zones. If an application wishes to compare dates in different time zones it should first convert them to a Calendar.

An application should create a Date object using a Calendar. The application is responsible for specifying the time as 00:00:00 on the desired date when using the Calendar since the JDBC API uses this convention. In addition when creating a Time value the application must specify a date of January 1, 1970 to the Calendar used to create the millisecond value for the Time as this is the convention specified for time.

10.6 Refinement to the Drop Table requirement

The JDBC 1.0 API specification required that JDBC 1.0 compliant drivers provide full support for the SQL92, Transitional Level, DROP TABLE command, including full support for the CASCADE and RESTRICT options of DROP TABLE. Because some popular databases currently do not fully support DROP TABLE as it is defined in the SQL92 specification, this requirement has been relaxed in the JDBC API specification.

A JDBC compliant driver is required to support the DROP TABLE command as specified by SQL92, Transitional Level. However, support for the CASCADE and RESTRICT options of DROP TABLE is optional for a JDBC compliant driver. In addition, the behavior of DROP TABLE is implementation defined when there are views or integrity constraints defined that reference a table that is being dropped.

Contents | Prev | Next

jdbc@eng.sun.com or jdbc-business@eng.sun.com