Skip Headers

Oracle9i JDBC Developer's Guide and Reference
Release 2 (9.2)

Part Number A96654-01
Go To Documentation Library
Home
Go To Product List
Book List
Go To Table Of Contents
Contents
Go To Index
Index

Master Index

Feedback

Go to previous page Go to next page

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

The Oracle JDBC drivers support the following JDBC 3.0 features:

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.


Note:

Savepoints are supported for local transactions only. Specifying a savepoint within a global transaction causes SQLException to be thrown.


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().


Note:

Attempting to retrieve a name from an unnamed savepoint or attempting to retrieve an ID from a named savepoint throws an SQLException.


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).


Note:

As of Release 2 (9.2), releaseSavepoint() and oracleReleaseSavepoint() are not supported; if you invoke either message, SQLException is thrown with the message "Unsupported feature".


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

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:

public String getSavepointName() throws SQLException;

Return the name of a named savepoint.

Exceptions:

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

public Savepoint setSavepoint() throws SQLException;

Create an unnamed savepoint.

Exceptions:

publicSavepoint setSavepoint(String name) throws SQLException;

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

Exceptions:

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:

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;


Go to previous page Go to next page
Oracle
Copyright © 1999, 2002 Oracle Corporation.

All Rights Reserved.
Go To Documentation Library
Home
Go To Product List
Book List
Go To Table Of Contents
Contents
Go To Index
Index

Master Index

Feedback