4
Overview of JDBC 2.0 Support

A key aspect of Oracle JDBC is JDBC 2.0 functionality, both new functionality that was not previously supported, and the standardization of functionality that was previously supported through Oracle extensions.

This chapter provides an overview of JDBC 2.0 support in the Oracle JDBC drivers, focusing in particular on any differences in support between the JDK 1.2.x and JDK 1.1.x environments. The following topics are discussed:

Introduction

The Oracle JDBC drivers are compliant with the JDBC 2.0 specification. JDBC 2.0 functionality previously implemented through Oracle extensions in the oracle.jdbc2 package--such as structured objects, object references, arrays, and LOBs--is now implemented through the standard java.sql package in JDK 1.2.

In a JDK 1.1.x environment, you can continue to use the oracle.jdbc2 package. You can also use JDBC 2.0 features in connection objects, statement objects, result set objects, and database meta data objects under JDK 1.1.x by casting your objects to the Oracle types.

Furthermore, you can use features of the JDBC 2.0 Optional Package (also known as the JDBC 2.0 Standard Extension API) under either JDK 1.2.x or JDK 1.1.x. These features, including connection pooling and distributed transactions, are supported through the standard javax.sql package. This package and the classes that implement its interfaces are now included with the JDBC classes ZIP file for either JDK 1.2.x or JDK 1.1.x.

JDBC 2.0 Support: JDK 1.2.x versus JDK 1.1.x

Support for standard JDBC 2.0 features differs depending on whether you are using JDK 1.2.x or JDK 1.1.x. There are three areas to consider:

datatype support--such as for objects, arrays, and LOBs--which is handled through the standard java.sql package under JDK 1.2.x and through the Oracle extension oracle.jdbc2 package under JDK 1.1.x
standard feature support--such as result set enhancements and update batching--which is handled through standard objects such as Connection, ResultSet, and PreparedStatement under JDK 1.2.x, but requires Oracle-specific functionality under JDK 1.1.x
extended feature support--features of the JDBC 2.0 Optional Package (also known as the Standard Extension API), including data sources, connection pooling, and distributed transactions--which has the same support and functionality in either JDK 1.2.x or JDK 1.1.x

This section also discusses performance enhancements available under JDBC 2.0--update batching and fetch size--that are also still available as Oracle extensions, then concludes with a brief discussion about migration from JDK 1.1.x to JDK 1.2.x.

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.

For JDBC 2.0 functionality under JDK 1.2.x, where you are using classes12.zip, no special imports are required. The following imports, both of which you will likely need even if you are not using JDBC 2.0 features, will suffice:

import java.sql.*;
import oracle.sql.*;

JDBC 2.0 features are not supported by JDK 1.1.x; however, Oracle provides extensions that allow you to use a significant subset of JDBC 2.0 datatypes under JDK 1.1.x, where you are using classes111.zip. These extensions support database objects, object references, arrays, and LOBs.

The package oracle.jdbc2 is included in classes111.zip. This package provides interfaces that mimic JDBC 2.0-related interfaces that became standard with JDK 1.2.x for SQL3 and advanced datatypes. The interfaces in oracle.jdbc2 are implemented as appropriate by classes in the oracle.sql package for a JDK 1.1.x environment.

The following imports are required for JDBC 2.0 datatypes under JDK 1.1.x:

import java.sql.*;
import oracle.jdbc2.*;
import oracle.sql.*;

Standard Feature Support

In a JDK 1.2.x environment (using the JDBC classes in classes12.zip), 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. Therefore, under JDK 1.2.x, you can use standard objects such as Connection, DatabaseMetaData, ResultSetMetaData, Statement, PreparedStatement, CallableStatement, and ResultSet to use these features.

In a JDK 1.1.x environment (using the JDBC classes in classes111.zip), Oracle JDBC provides support for these JDBC 2.0 features as Oracle extensions. To use this functionality, you must cast your objects to the Oracle types:

OracleConnection
OracleDatabaseMetaData
OracleResultSetMetaData
OracleStatement
OraclePreparedStatement
OracleCallableStatement
OracleResultSet

For example, to use JDBC 2.0 result set enhancements, you must do the following:

Explicitly type or cast scrollable or updatable result sets as type OracleResultSet.
Explicitly type or cast connection objects as type OracleConnection whenever the connection object will be required to produce a statement object that will in turn produce a scrollable or updatable result set.

In addition, you might have to cast statement objects to OracleStatement, OraclePreparedStatement, or OracleCallableStatement, and cast database meta data objects to OracleDatabaseMetaData. This would be if you want to use JDBC 2.0 statement or database meta data methods described under "Summary of New Methods for Result Set Enhancements".

Extended Feature Support

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

The standard javax.sql package and classes that implement its interfaces are included in the JDBC classes ZIP file for either environment.

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:

Migration from JDK 1.1.x to JDK 1.2.x

The only migration requirements in going from JDK 1.1.x to JDK 1.2.x are as follows:

Remove your imports of the oracle.jdbc2 package, as discussed above under "Datatype Support".
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.x.

Overview of JDBC 2.0 Features

Table 4-1 lists key areas of JDBC 2.0 functionality and points to where you can go in this manual for more information about Oracle support.

Table 4-1 Key Areas of JDBC 2.0 Functionality

Feature	Comments and References
update batching	Also available previously as an Oracle extension. Under either JDK 1.2.x or JDK 1.1.x you can use either the standard update batching model or the Oracle model. See "Update Batching" for information.
result set enhancements (scrollable and updatable result sets)	This is also available under JDK 1.1.x as an Oracle extension. See Chapter 11, "Result Set Enhancements" for information.
fetch size / row prefetching	The JDBC 2.0 fetch size feature is also available under JDK 1.1.x as an Oracle extension. Under either JDK 1.2.x or JDK 1.1.x, you can also use Oracle row prefetching, which is largely equivalent to the JDBC 2.0 fetch size feature but predates JDBC 2.0. See "Fetch Size" and "Oracle Row Prefetching" for information.
use of JNDI (Java Naming and Directory Interface) to specify and obtain database connections	This requires data sources, which are part of the JDBC 2.0 Optional Package (JDBC 2.0 Standard Extension API) in the javax.sql package. This is available under either JDK 1.2.x or JDK 1.1.x. See "A Brief Overview of Oracle Data Source Support for JNDI" and "Creating a Data Source Instance, Registering with JNDI, and Connecting" for information.
connection pooling (framework for connection caching)	This requires the JDBC 2.0 Optional Package (JDBC 2.0 Standard Extension API) in the javax.sql package. This is available under either JDK 1.2.x or 1.1.x. See "Connection Pooling" for information.
connection caching (sample Oracle implementation)	This requires the JDBC 2.0 Optional Package (JDBC 2.0 Standard Extension API) in the javax.sql package. This is available under either JDK 1.2.x or 1.1.x. See "Connection Caching" for information.
distributed transactions / XA functionality	This requires the JDBC 2.0 Optional Package (JDBC 2.0 Standard Extension API) in the javax.sql package. This is available under either JDK 1.2.x or 1.1.x. See Chapter 15, "Distributed Transactions" for information.
miscellaneous getXXX() methods	See "Other getXXX() Methods" for information about which getXXX() methods are Oracle extensions under JDK 1.2.x and 1.1.x, and about any differences in functionality with JDBC 2.0.
miscellaneous setXXX() methods	See "Other setXXX() Methods" for information about which setXXX() methods are Oracle extensions under JDK 1.2.x and 1.1.x, and about any differences in functionality with JDBC 2.0.

Note:

The Oracle JDBC drivers do not support the Calendar datatype because it is not yet feasible to support java.sql.Date timezone information. Calendar input to setXXX() or getXXX() method calls for Date, Time, and Timestamp is ignored. The Calendar type will be supported in a future Oracle release.

4 Overview of JDBC 2.0 Support