5 JDBC Standards Support

Datatype Support

Oracle JDBC fully supports JDK 1.2.x, which includes standard JDBC 2.0 functionality through implementation of interfaces in the standard java.sql package. These interfaces are implemented as appropriate by classes in the oracle.sql and oracle.jdbc packages.

Standard Feature Support

In a JDK 1.2.x environment (using the JDBC classes in classes12.jar), JDBC 2.0 features such as scrollable result sets, updatable result sets, and update batching are supported through methods specified by standard JDBC 2.0 interfaces.

Extended Feature Support

Features of the JDBC 2.0 Optional Package (also known as the Standard Extension API), including datasources, connection pooling, and distributed transactions, are supported in a JDK 1.2.x or later environment.

The standard javax.sql package and classes that implement its interfaces are included in the JDBC classes12.jar file.

Standard versus Oracle Performance Enhancement APIs

There are two performance enhancements available under JDBC 2.0, which had previously been available as Oracle extensions:

• update batching

• fetch size / row prefetching

In each case, you have the option of using the standard model or the Oracle model. Do not, however, try to mix usage of the standard model and Oracle model within a single application for either of these features.

For more information, see the following sections:

• "Update Batching"

• "Fetch Size"

• "Oracle Row Prefetching"

Migration from JDK 1.1.x

The only migration requirements in upgrading from JDK 1.1.x are as follows:

• Remove your imports of the oracle.jdbc2 package

• Replace any direct references to oracle.jdbc2.* interfaces with references to the standard java.sql.* interfaces.

• Type map objects (for mapping SQL structured objects to Java types), which must extend the java.util.Dictionary class under JDK 1.1.x, must implement the java.util.Map interface under JDK 1.2.x. Note, however, that the class java.util.Hashtable satisfies either requirement. If you used Hashtable objects for your type maps under JDK 1.1.x, then no change is necessary. For more information, see "Creating a Type Map Object and Defining Mappings for a SQLData Implementation".

If these points do not apply to your code, then you do not need to make any code changes or recompile to run under JDK 1.2 and higher releases.

Unsupported JDBC 3.0 Features

The following JDBC 3.0 features are not supported at this release:

• Retrieval of auto-generated keys

• ResultSet holdability

• Multiple open ResultSets

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 query whether savepoints are supported by your database by calling oracle.jdbc.OracleDatabaseMetaData.supportsSavepoints(), which returns true if savepoints are available, false otherwise.

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;

Return the savepoint ID for an unnamed savepoint.

Exceptions:

• SQLException: Thrown if self is a named savepoint.

public String getSavepointName() throws SQLException;

Return the name of a named savepoint.

Exceptions:

• SQLException: Thrown if self is an unnamed savepoint.

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

public Savepoint setSavepoint() throws SQLException;

Create an unnamed savepoint.

Exceptions:

• SQLException: Thrown on database error, or if Connection is in auto-commit mode or participating in a global transaction.

publicSavepoint setSavepoint(String name) throws SQLException;

Create a named savepoint. If a Savepoint by this name already exists, this instance replaces it.

Exceptions:

• SQLException: Thrown on database error or if Connection is in auto-commit mode or participating in a global transaction.

public void rollback(Savepoint savepoint) throws SQLException;

Remove specified Savepoint from current transaction. Any references to the savepoint after it is removed cause an SQLException to be thrown.

Exceptions:

• SQLException: Thrown on database error or if Connection is in auto-commit mode or participating in a global transaction.

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;