ResultSet characteristics

This topic discusses ResultSet characteristics such ResultSet types, concurrency, ability to close the ResultSet by committing the connection object, and specification of ResultSet characteristics.

By default, all created ResultSets have a type of forward only, a concurrency of read only, and cursors are held over commit boundaries. An exception to this is that WebSphere^® currently changes the cursor holdability default so that cursors are implicitly closed when committed. These characteristics are configurable through methods that are accessible on Statement, PreparedStatement, and CallableStatement objects.

ResultSet types

The ResultSet type specifies the following about the ResultSet:

Whether the ResultSet is scrollable.
The types of Java™ Database Connectivity (JDBC) ResultSets that are defined by constants on the ResultSet interface.

Definitions of these ResultSet types are as follows:

TYPE_FORWARD_ONLY: A cursor that can only be used to process from the beginning of a ResultSet to the end of it. This is the default type.

TYPE_SCROLL_INSENSITIVE: A cursor that can be used to scroll in various ways through a ResultSet. This type of cursor is insensitive to changes made to the database while it is open. It contains rows that satisfy the query when the query was processed or when data is fetched.

TYPE_SCROLL_SENSITIVE: A cursor that can be used to scroll in various ways through a ResultSet. This type of cursor is sensitive to changes made to the database while it is open. Changes to the database have a direct impact on the ResultSet data.

JDBC 1.0 ResultSets are always forward only. Scrollable cursors were added in JDBC 2.0.

Note: The blocking enabled and block size connection properties affect the degree of sensitivity of a TYPE_SCROLL_SENSITIVE cursor. Blocking enhances performance by caching data in the JDBC driver layer itself.

See Example: Sensitive and insensitive ResultSets that shows the difference between sensitive and insensitive ResultSets when rows are inserted into a table.

See Example: ResultSet sensitivity that shows how a change can affect a where clause of an SQL statement based on the sensitivity of the ResultSet.

Concurrency

Concurrency determines whether the ResultSet can be updated. The types are again defined by constants in the ResultSet interface. The available concurrency settings are as follows:

CONCUR_READ_ONLY: A ResultSet that can only be used for reading data out of the database. This is the default setting.

CONCUR_UPDATEABLE: A ResultSet that allows you to make changes to it. These changes can be placed into the underlying database. See Change ResultSets for more information.

JDBC 1.0 ResultSets are always forward only. Updateable ResultSets were added in JDBC 2.0.

Note: According to the JDBC specification, the JDBC driver is allowed to change the ResultSet type of the ResultSet concurrency setting if the values cannot be used together. In such cases, the JDBC driver places a warning on the Connection object.

There is one situation where the application specifies a TYPE_SCROLL_INSENSITIVE, CONCUR_UPDATEABLE ResultSet. Insensitivity is implemented in the database engine by making a copy of the data. You are then not allowed to make updates through that copy to the underlying database. If you specify this combination, the driver changes the sensitivity to TYPE_SCROLL_SENSITIVE and create the warning indicating that your request has been changed.

Holdability

The holdability characteristic determines whether calling commit on the Connection object closes the ResultSet. The JDBC API for working with the holdability characteristic is new in version 3.0. However, the native JDBC driver has provided a connection property for several releases that allows you to specify that default for all ResultSets created under the connection (see Connection properties and DataSource properties). The API support overrides any setting for the connection property. Values for the holdability characteristic are defined by ResultSet constants and are as follows:

HOLD_CURSOR_OVER_COMMIT: All open cursors remain open when the commit clause is called. This is the native JDBC default value.

CLOSE_CURSORS_ON_COMMIT: All open cursors are closed when commit clause is called.

Note: Calling rollback on a connection always closes all open cursors. This is a little known fact, but a common way for databases to handle cursors.

According to the JDBC specification, the default for cursor holdability is implementation-defined. Some platforms choose to use CLOSE_CURSORS_ON_COMMIT as the default. This does not usually become an issue for most applications, but you must be aware of what the driver you are working with does if you are working with cursors across commit boundaries. The IBM^® Toolbox for Java JDBC driver also uses the HOLD_CURSORS_ON_COMMIT default, but the JDBC driver for UDB for Windows NT^® has a default of CLOSE_CURSORS_ON_COMMIT.

Specify ResultSet characteristics

A ResultSet's characteristics do not change once the ResultSet object has been created. Therefore, the characteristics have be specified before creating the object. You can specify these characteristics through overloaded variations of the createStatement, prepareStatement, and prepareCall methods.

See the following topics to specify ResultSet characteristics:

Specify ResultSet characteristics for Statements
Specify ResultSet characteristics and automatically generated key support for PreparedStatement
Specify ResultSet characteristics and auto-generated key support for CallableStatements

Note: There are ResultSet methods to obtain the ResultSet type and the concurrency of the ResultSet, but there is no method to obtain the holdability of the ResultSet.