JDBC^TM Guide: Getting Started

11 Clarifications

We have gotten several requests to clarify some aspects of the JDBC API. This chapter contains additional explanation of some features.

11.1 Connection.isClosed()

The Connection.isClosed() method is only guaranteed to return true after

Connection.closed()

has been called. Connection.isClosed() cannot be called, in general, to determine if a database connection is valid or invalid. A typical client can determine that a connection is invalid by catching the exception that is thrown when an operation is attempted.

11.2 Statement.setCursorName()

The Statement.setCursorName() method provides a way for an application to specify a cursor name for the cursor associated with the next result set produced by a statement. A result set's cursor name can be retrieved by calling ResultSet.getCursorName(). If Statement.setCursorName() is called prior to creating a result set, then ResultSet.getCursorName() should always return the value specified in

 Statement.setCursorName().

We note that calling Statement.setCursorName() prior to creating a result set does not mean that the result set is updatable, in other words, positioned update or delete may not be allowed on a result set even if Statement.setCursorName() was called. By default , a result set is read-only.

The only use for a cursor name is to embed it in a SQL statement of the form

UPDATE ... WHERE CURRENT OF <cursor>

The cursor name provides a way to do a positioned update or delete. To enable positioned update and delete on a result set, a select query of the form

SELECT FOR UPDATE ... FROM ... WHERE ...

should be used to create the result set. If Statement.setCursorName() is not called to specify a cursor name, then the JDBC driver or underlying DBMS must generate a cursor name when a SELECT FOR UPDATE statement is executed, if positioned update/delete is supported. ResultSet.getCursorName()should return null if the result set is read-only and Statement.setCursorName() was not called to specify a cursor name.

11.3 Character conversion

JDBC driver implementations are expected to automatically convert the Java programming language unicode encoding of strings and characters to and from the character encoding of the database being accessed. The JDBC API does not define how to override the character encoding of a database. For example, the API does not define how to store unicode characters in an ASCII database.

11.4 Streams as input parameters

When an application passes a stream as an input value via a setXXX() or updateXXX() method, the application is responsible for maintaining the stream in a readable state until one of the following methods is called: PreparedStatement.execute(), executeQuery(), executeUpdate(), or executeBatch(), and ResultSet.insertRow() or updateRow(). A JDBC driver is not required to wait until one of these methods is called to read the stream value.

11.5 Result sets not created by a Statement

A ResultSet object that is created by a metadata operation is only required to be forward-only. Scrollability is not required for result sets produced by DatabaseMetaData operations.

Contents | Prev | Next

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