5
Overview of Supported JDBC 3.0 Features

This chapter provides an overview of the JDBC 3.0 features supported in the Oracle JDBC drivers, focusing in particular on any differences in support between the JDK 1.4 environment and previous JDK environments. The following topics are discussed:

• Introduction
• JDBC 3.0 Support: JDK 1.4 and Previous Releases
• Overview of Supported JDBC 3.0 Features
• Transaction Savepoints

Introduction

The Oracle JDBC drivers support the following JDBC 3.0 features:

• Using global and distributed transactions on the same connection (see "Oracle XA Packages" )
• Transaction savepoints (see "Transaction Savepoints" )
• Re-use of prepared statements by connection pools (also known as statement caching; see Chapter 14, "Statement Caching")
• Full support for JDK1.4 (see "JDBC 3.0 Support: JDK 1.4 and Previous Releases" in this chapter)

All of these features are provided in the package oracle.jdbc. This package supports all JDK releases from 1.1.x through 1.4; JDBC 3.0 features that depend on JDK1.4 are made available to earlier JDK versions through Oracle extensions.

JDBC 3.0 Support: JDK 1.4 and Previous Releases

This release adds or extends the following interfaces and classes.

Table 5-1 JDBC 3.0 Feature Support

New feature	JDK1.4 implementation	Pre-JDK1.4 implementation
Savepoints (new class)	java.sql.Savepoint	oracle.jdbc.OracleSavepoint
Savepoints (connection extensions)	java.sql.connection	oracle.jdbc. OracleConnection
Querying parameter capacities (new class)	java.sql.ParameterMetaData	oracle.jdbc. OracleParameterMetaData
Querying parameter capacities (interface change)	Not applicable	oracle.jdbc. OraclePreparedStatement

Overview of Supported JDBC 3.0 Features

Table 5-2 lists the JDBC 3.0 features supported at this release and gives references to a detailed discussion of each feature.

Table 5-2 Key Areas of JDBC 3.0 Functionality  

Feature	Comments and References
Transaction savepoints	See "Transaction Savepoints" for information.
Connection sharing	Re-use of prepared statements by connection pools (see Chapter 14, "Statement Caching".
Switching between local and global transactions	See "Switching Between Global and Local Transactions" for information.

Transaction Savepoints

The JDBC 3.0 specification supports savepoints, which offer finer demarcation within transactions. Applications can set a savepoint within a transaction and then roll back (but not commit) all work done after the savepoint. Savepoints relax the atomicity property of transactions. A transaction with a savepoint is atomic in the sense that it appears to be a single unit outside the context of the transaction, but code operating within the transaction can preserve partial states.

JDK1.4 specifies a standard savepoint API. Oracle JDBC provides two different savepoint interfaces: one (java.sql.Savepoint) for JDK1.4 and one (oracle.jdbc.OracleSavepoint) that works across all supported JDK versions. JDK1.4 adds savepoint-related APIs to java.sql.Connection; the Oracle JDK version-independent interface oracle.jdbc.OracleConnection provides equivalent functionality.

Creating a Savepoint

You create a savepoint using either Connection.setSavepoint(), which returns a java.sql.Savepoint instance, or OracleConnection.oracleSetSavepoint(), which returns an oracle.jdbc.OracleSavepoint instance.

A savepoint is either named or unnamed. You specify a savepoint's name by supplying a string to the setSavepoint() method; if you do not specify a name, the savepoint is assigned an integer ID. You retrieve a name using getSavepointName(); you retrieve an ID using getSavepointId().

Rolling back to a Savepoint

You roll back to a savepoint using Connection.rollback(Savepoint svpt) or OracleConnection.oracleRollback(OracleSavepoint svpt). If you try to roll back to a savepoint that has been released, SQLException is thrown.

Releasing a Savepoint

You remove a savepoint using Connection.releaseSavepoint(Savepoint svpt) or OracleConnection.oracleReleaseSavepoint(OracleSavepoint svpt).

Checking Savepoint Support

You find out whether savepoints are supported by your database by calling oracle.jdbc.OracleDatabaseMetaData.supportsSavepoints(), which returns True if savepoints are available.

Savepoint Notes

• After a savepoint has been released, attempting to reference it in a rollback operation will cause an SQLException to be thrown.
• When a transaction is committed or rolled back, all savepoints created in that transaction are automatically released and become invalid.
• Rolling a transaction back to a savepoint automatically releases and makes invalid any savepoints created after the savepoint in question.

Savepoint Interfaces

The following methods are used to get information from savepoints. These methods are defined within both the java.sql.Connection and oracle.jdbc.OracleSavepoint interfaces:

public int getSavepointId() throws SQLException;

public String getSavepointName() throws SQLException;

These methods are defined within the java.sql.Connection interface:

public Savepoint setSavepoint() throws SQLException;

publicSavepoint setSavepoint(String name) throws SQLException;

public void rollback(Savepoint savepoint) throws SQLException;

public void releaseSavepoint(Savepoint savepoint) throws SQLException;

Not supported at this release. Always throws SQLException.

Pre-JDK1.4 Savepoint Support

These methods are defined within the oracle.jdbc.OracleConnection interface; except for using OracleSavepoint in the signatures, they are identical to the methods above.

public OracleSavepoint oracleSetSavepoint() throws SQLException;

public OracleSavepoint oracleSetSavepoint(String name) throws SQLException;

public void oracleRollback(OracleSavepoint savepoint) throws SQLException;

public void oracleReleaseSavepoint(OracleSavepoint savepoint) throws SQLException;