Oracle JDBC Drivers release production (10g R2) README

What Is New In This Release ?

Support for J2SE 5.0
J2SE 5.0 (AKA J2SE 1.5 and Tiger) is fully supported. 5.0 supports
JDBC 3.0, the same as J2SE 1.4, so there are no additional
standard JDBC features. Prior to this release J2SE 5.0 was not
officially supported.

Duplicate copy of orai18n.jar has been removed.
In we replaced nls_charset12.jar with a new file
for providing National Character Set support, orai18n.jar.
This file was located in [ORACLE_HOME]/jdbc/lib/. Unfortunately
this was a duplicate of the same file located in
[ORACLE_HOME]/jlib/. Since orai18n.jar is used by other parts
of Oracle, not just JDBC, the jlib directory is the correct
location for this file. In this release we have removed the
unneeded duplicate in [ORACLE_HOME]/jdbc/lib. Please update
your classpaths to reference [ORACLE_HOME]/jlib/orai18n.jar
as needed.

Proxy Authentication
In Oracle 10g R1 we introduced a new API for proxy authentication
that was supported only by the Thin driver. In this release we
extend support of that API to the OCI driver as well. We strongly
recommend that you use the common API instead of the OCI specific

JDBC 3.0 Features
Complete support for all JDBC 3.0 features.
- Autogenerated Keys are now supported.
- Cursor Holdability methods now return the correct values rather
rather than throwing SQLException. There is no change in the
actual rdbms support for cursor holdability.
- Local/Global Transaction Switching

Runtime Connection Load Balancing
RCLB is an exciting new feature that works in cooperation with
RAC Load Balancer Advisory to dynamically allocate/reallocate
connections based on real-time load and performance information.

XA Connection Pooling
Oracle JDBC has long supported connection caching, but not
for XA connections. Oracle 10gR2 introduces the ability to
cache XA connections as well as local connections.

DML Returning
Can you believe it! After all these years of saying "next
release", DML returning is now supported in the Thin and OCI
drivers. DML returning is a SQL language feature that permits SQL
DMS statements (insert, update, delete) to return result
sets. This is especially advantageous to return columns modified
by triggers or autogenerated keys.

Rowsets (JSR 114)
JSR 114 defines substantial new functionality for RowSets. The
oracle.jdbc.rowset classes are updated to implement the new
functionality defined in JSR 114.

The ability to connect to the rdbms via Secure Socket Layer (SSL).

Driver Versions

These are the driver versions in the release:

- JDBC Thin Driver
100% Java client-side JDBC driver for use in client applications,
middle-tier servers and applets.

- JDBC OCI Driver
Client-side JDBC driver for use on a machine where OCI
is installed.

- JDBC Thin Server-side Driver
JDBC driver for use in Java program in the database to access
remote Oracle databases.

- JDBC Server-side Internal Driver
Server-side JDBC driver for use by Java Stored procedures. This
driver used to be called the "JDBC Kprb Driver".

For complete documentation, please refer to "JDBC Developer's Guide
and Reference".

Contents Of This Release

For all platforms:

[ORACLE_HOME]/jdbc/lib contains:

- classes12.jar
Classes for use with JDK 1.2 and JDK 1.3. It contains the
JDBC driver classes, except classes for NLS support in Oracle
Object and Collection types.

- classes12_g.jar
Same as classes12.jar, except that classes were compiled with
"javac -g" and contain some tracing information.

- classes12dms.jar
Same as classes12.jar, except that it contains additional code
to support Oracle Dynamic Monitoring Service. Can only be used
when dms.jar is in the classpath. dms.jar is provided as part of
recent Oracle Application Server releases.

- classes12dms_g.jar
Same as classes12dms.jar except that classes were compiled with
"javac -g" and contain some tracing information.

- ojdbc14.jar
Classes for use with JDK 1.4 and 5.0. It contains the JDBC driver
classes, except classes for NLS support in Oracle Object and
Collection types.

- ojdbc14_g.jar
Same as ojdbc14.jar, except that classes were compiled with
"javac -g" and contain some tracing information.

- ojdbc14dms.jar
Same as ojdbc14.jar, except that it contains additional code
to support Oracle Dynamic Monitoring Service. Can only be used
when dms.jar is in the classpath. dms.jar is provided as part of
recent Oracle Application Server releases.

- ojdbc14dms_g.jar
Same as ojdbc14dms.jar except that classes were compiled with
"javac -g" and contain some tracing information.

[ORACLE_HOME]/jdbc/doc/javadoc.tar contains the JDBC Javadoc
for the public API of the public classes of Oracle JDBC.

[ORACLE_HOME]/jdbc/demo/demo.tar contains sample JDBC programs.

NLS classes for use with JDK 1.2, 1.3, 1.4, and 5.0. It contains
classes for NLS support in Oracle Object and Collection types.
This jar file replaces the old nls_charset jar/zip files. In
Oracle 10g R1 it was duplicated in [ORACLE_HOME]/jdbc/lib. We
have removed the duplicate copy and you should now get it from
its proper location.

For the Windows platform:

[ORACLE_HOME]\bin directory contains ocijdbc10.dll and
heteroxa10.dll, which are the libraries used by the JDBC OCI

For non-Windows platforms:

[ORACLE_HOME]/lib directory contains,, and, which
are the shared libraries used by the JDBC OCI driver.

NLS Extension Jar File (for client-side only)

The JDBC Server-side Internal Driver provides complete NLS support.
It does not require any NLS extension jar file. Discussions in this
section only apply to the Oracle JDBC Thin and JDBC OCI drivers.

The basic jar files (classes12.jar and ojdbc14.jar) contain all the
necessary classes to provide complete NLS support for:

- Oracle Character sets for CHAR/VARCHAR/LONGVARCHAR/CLOB type data
that is not retrieved or inserted as a data member of an Oracle
Object or Collection type.

- NLS support for CHAR/VARCHAR data members of Objects and
Collections for a few commonly used character sets. These
character sets are: US7ASCII, WE8DEC, WE8ISO8859P1, WE8MSWIN1252,
and UTF8.

Users must include the NLS extension jar file
([ORACLE_HOME]/jlib/orai18n.jar) in their CLASSPATH if utilization of
other character sets in CHAR/VARCHAR data members of
Objects/Collections is desired. The new orai18n.jar replaces the
nls_charset*.* files in the 9i and older releases.

The file orai18n.jar contains many important character-related files.
Most of these files are essential to globalization support. Instead
of extracting only the character-set files your application uses, it
is safest to follow this three-step process: 1. Unpack orai18n.jar
into a temporary directory. 2. Delete the character-set files that
your application does not use. Do not delete any territory, collation
sequence, or mapping files. 3. Create a new orai18n.jar file from
the temporary directory and add the altered file to your CLASSPATH.
See the JDBC Developers Guide for more information.

In addition, users can also include internationalized Jdbc error
message files selectively. The message files are included in the
oracle/jdbc/driver/Messages_*.properties files in classes12*.jar
and ojdbc14*.jar.



Please do not try to put multiple versions of the Oracle JDBC drivers
in your CLASSPATH. The Oracle installer installs the JDBC Drivers in
the [ORACLE_HOME]/jdbc directory.

Setting Up Your Environment

On Windows platforms:
- Add [ORACLE_HOME]\jdbc\lib\classes12.jar to your CLASSPATH if you
use JDK 1.2 or 1.3. Add [ORACLE_HOME]\jdbc\lib\ojdbc14.jar to
your CLASSPATH if you use JDK 1.4.
- Add [ORACLE_HOME]\jlib\orai18n.jar to your CLASSPATH if needed.
- Add [ORACLE_HOME]\bin to your PATH if you are using the JDBC OCI

On Solaris/Digital Unix:
- Add [ORACLE_HOME]/jdbc/lib/classes12.jar to your CLASSPATH if you
use JDK 1.2 or 1.3. Add [ORACLE_HOME]/jdbc/lib/ojdbc14.jar to
your CLASSPATH if you use JDK 1.4.
- Add [ORACLE_HOME]/jlib/orai18n.jar to your CLASSPATH if needed.
- Add [ORACLE_HOME]/jdbc/lib to your LD_LIBRARY_PATH if you use
the JDBC OCI driver.

- Add [ORACLE_HOME]/jdbc/lib/classes12.jar to your CLASSPATH if you
use JDK 1.2 or 1.3. Add [ORACLE_HOME]/jdbc/lib/ojdbc14.jar to
your CLASSPATH if you use JDK 1.4.
- Add [ORACLE_HOME]/jlib/orai18n.jar to your CLASSPATH if needed.
- Add [ORACLE_HOME]/jdbc/lib to your SHLIB_PATH and LD_LIBRARY_PATH
if you use the JDBC OCI driver.

- Add [ORACLE_HOME]/jdbc/lib/classes12.jar to your CLASSPATH if you
use JDK 1.2 or 1.3. Add [ORACLE_HOME]/jdbc/lib/ojdbc14.jar to
your CLASSPATH if you use JDK 1.4.
- Add [ORACLE_HOME]/jlib/orai18n.jar to your CLASSPATH if needed.
- Add [ORACLE_HOME]/jdbc/lib to your LIBPATH and LD_LIBRARY_PATH
if you use the JDBC OCI driver.

Some Useful Hints In Using the JDBC Drivers


Please refer to "JDBC Developer's Guide and Reference" for details
regarding usage of Oracle's JDBC Drivers. This section only offers
useful hints. These hints are not meant to be exhaustive.

These are a few simple things that you should do in your JDBC program:

1. Import the necessary JDBC classes in your programs that use JDBC.
For example:

import java.sql.*;
import java.math.*; // if needed

To use OracleDataSource, you need to do:
import oracle.jdbc.pool.OracleDataSource;

2. Create an OracleDataSource instance.

OracleDataSource ods = new OracleDataSource();

3. set the desired properties if you don't want to use the
default properties. Different connection URLs should be
used for different JDBC drivers.


For the JDBC OCI Driver:
To make a bequeath connection, set URL as:

To make a remote connection, set URL as:

where <database> is either a TNSEntryName
or a SQL*net name-value pair defined in tnsnames.ora.

For the JDBC Thin Driver, or Server-side Thin Driver:

where <database> is either a string of the form
//<host>:<port>/<service_name>, or a SQL*net name-value pair,
or a TNSEntryName.

For the JDBC Server-side Internal Driver:

Note that the trailing ':' is necessary. When you use the
Server-side Internal Driver, you always connect to the
database you are executing in. You can also do this:

Connection conn =
new oracle.jdbc.OracleDriver().defaultConnection();

4. Open a connection to the database with getConnection()
methods defined in OracleDataSource class.

Connection conn = ods.getConnection();


The Old oracle.jdbc.driver Package Will Go Away !!!

Beginning in Oracle 9i, Oracle extensions to JDBC are captured in
the package oracle.jdbc. This package contains classes and
interfaces that specify the Oracle extensions in a manner similar
to the way the classes and interfaces in java.sql specify the
public JDBC API.

The use of the package oracle.jdbc.driver has been deprecated
since the initial version of 9i. Your code should use the package
oracle.jdbc instead. New features since Oracle 9i are incompatible
with use of the package oracle.jdbc.driver. Although we continue
to support the old package oracle.jdbc.driver in this release to
provide backwards compatibility, the package will definitely be
removed in the next major release. If you still have existing
applications that use the old oracle.jdbc.driver package, now is the
time to convert your code.

All that is required to covert your code is to replace
"oracle.jdbc.driver" with "oracle.jdbc" in the source and recompile.
This cannot be done piecewise. You must convert all classes
and interfaces that are referenced by an application.

Java Stored Procedures

Examples for callins and instance methods using Oracle Object Types
can be found in:


After you unzip the file, you will find the examples under:


Known Problems/Limitations Fixed in This Release

JDBC XA produces DB trace file output even when there is no need.

Object type attribute metadata not found for a synonym of an
object type. If a JDBC StructDescriptor was created using a synonym
for an object type, the names and types of the attributes of the
object type were not detected. The workaround was to either not use
the metatdata, or to use the actual type name rather than a

JDBC erroneously decided that an XA connection is participating
in a local transaction and threw a SQLException when attempting
to start a global transaction. One workaround was to set
auto-commit to true. The other workaround was to call commit before
attempting to start the global transaction.

ORA-1732 when inserting into a scrollable result set created with
an order by clause. This is only supported in 10g database.

Problem when executing a CALL block using a PreparedStatement. If
the CALL block contains an out parameter and that out parameter is
not registered then an execution error occurs. The workaround is
to execute CALL blocks with CallableStatements and to register out

Java thread deadlocks while using OracleOCIConnectionPool with
threads sharing connections.

Incorrect handling of the SQL92 function {fn LOCATE()}.

The method OracleDataSource.getConnection calls a synchronized
method and as a result can lock the connection cache for long
periods. This is primarily a problem when a connection attempt

SQLException: Fail to convert to internal representation when
calling getInt on a VARCHAR column in a cached row set.

Expiration of query timeout or calling Statement.cancel causes the
Thin driver to hang.

Calling OracleXAConnection.getConnection() after starting a
global transaction (XA start) throws SQLException. A workaround
is to obtain the Connection before global transaction starts.

Statement.clearWarnings doesn't clear all warnings.

When using the old connection cache, OracleConnectionCacheImpl,
Statement.getConnection returns the physical connection instead of
the logical connection.

Java VM deadlocks when closing a ScrollableResult set.

ORA-01461 when binding large strings when using Japanese character

StackOverflowError when attempting to bind a stream to a prepared
statement that will generate a scrollable result set.

Driver rounds timestamps to to seconds when the
ResultSet.getTimestamp method is used with the Calendar argument.

Wrong data inserted when setString followed by setXXX of non
character data at same parameter position.

Converting UTF8 string to a Java String could result in a
NullPointerException instead of a SQLException.

When using the SQLData interface and nested subtypes, if a deeply
nested subtype is NULL, in some cases a higher level type will be
set to NULL when pased to a stored procedure.

Problem with referencing object types named by private
synonyms. Results in ORA-01406 or ORA-01436.

When using 10g JDBC Drivers to insert CLOB/BLOB data more than 32K
using new feature setStringForClob() along with
setExecuteBatch()/sendBatch() produces following error:
java.sql.SQLException: ORA-00600: internal error code.

When the v8compatibility flag is set, Timestamp values are
supposed to be bound as Dates. setNull(Timestamp) binds a NULL
Timestamp value rather than a NULL Date value.

NullPointerException when calling executeBatch on a closed
statement. Workaround is to check isClosed before using

NullPointerException when calling executeBatch after previous call
on same statement resulted in an error. This problem occurs
occasionally when using statement caching and Fast Connection
Failover. A workaround is to call clearBatch in a catch block
wrapped around the call to executeBatch.

Known Problems/Limitations In This Release

The following is a list of known problems/limitations:

* Calling getSTRUCT() on ADT data in a ScrollableResultSet may
result in a NullpointerException.

* Binding more than 8000 bytes data to a table containing LONG
columns in one call of PreparedStatement.executeUpdate() may
result in an ORA-22295 error.

* Some memory Leak when using PreparedStatement with tables
containing large char or varchar column. The problem can be
worked around by enabling statement caching.

* Programs can fail to open 16 or more connections using our
client-side drivers at any one time. This is not a limitation
caused by the JDBC drivers. It is most likely that the limit of
per-process file descriptors is exceeded. The solution is to
increase the limit.

* The Server-side Internal Driver has the following limitation:
- LONG and LONG RAW types are limited 32512 bytes for parameters
of PL/SQL procedures.
- In a chain of SQLExceptions, only the first one in the chain
will have a getSQLState value.
- Batch updates with Oracle 8 Object, REF and Collection data
types are not supported.

* The JDBC OCI driver on an SSL connection hangs when the Java
Virtual Machine is running in green threads mode. A work-around
is to run the Java Virtual Machine in native threads mode.

* Date-time format, currency symbol and decimal symbols are always
presented in American convention.

Note: Most reasonable conversions work, but not all. In particular,
any conversion which would create a new lob will not work.If you
find a conversion that you think is reasonable, but that does not
work, please submit a TAR to Oracle Support.

* The utility dbms_java.set_output or dbms_java.set_stream that is
used for redirecting the System.out.println() in JSPs to stdout
SHOULD NOT be used when JDBC tracing is turned on. This is
because the current implementation of dbms_java.set_output and
set_stream uses JDBC to write the output to stdout. The result
would be an infinite loop.

* The JDBC OCI and Thin drivers do not read CHAR data via binary
streams correctly. In other word, using getBinaryStream() to
retrieve CHAR data may yield incorrect results. A work-around is
to use either getCHAR() or getAsciiStream() instead. The other
alternative is to use getUnicodeStream() although the method is

* There is a limitation for Triggers implemented in Java and Object
Types. Triggers implemented as Java methods cannot have OUT
arguments of Oracle 8 Object or Collection type. This means the
Java methods used to implement triggers cannot have arguments
of the following types:

- java.sql.Struct
- java.sql.Array
- oracle.sql.STRUCT
- oracle.sql.ARRAY
- oracle.jdbc2.Struct
- oracle.jdbc2.Array
- any class implementing oracle.jdbc2.SQLData or

* The scrollable result set implementation has the following

- setFetchDirection() on ScrollableResultSet does not do anything.
- refreshRow() on ScrollableResultSet does not support all
combinations of sensitivity and concurrency. The following
table depicts the supported combinations.

Support Type Concurrency

* AIX customers who want to use OID over SSL need to patch classes12.jar
by running the script under [ORACLE_HOME]/jdbc/bin/.
The script is part of the fix for Network bug #3882238.

* Limitation on using PreparedStatements to create triggers. Since
:foo is recognized by the drivers as a SQL parameter, it is not
possible to use :in and :out in SQL that defines a trigger when
using a PreparedStatement. The workaround is to use a Statement

BUG-2144602 (since 8.1.7)
JDBC drivers do not support the ZHT16DBT database character set.
There no database character mapping from ZHT16DBT to any other
charset, including Unicode. All non-ASCII characters will be
replaced with the replacement character. The only workaround is
to alter database character set to a Unicode character set such
as AL32UTF8.

BUG-2148328 (since 9.2.0)
On Linux, SJIS data in table names are returned as replacement
characters with some JDKs with both the Thin and OCI
drivers. This is due to a bug in the JDKs. The workaround is to
use JDK 1.3.1_09-b03 is known to work. JDK 1.4.2_02-b03 is known
to have this problem.

The insertRow method on an updateable result set inserts the row
into the database, but does not insert it into the result set

JDBC type2 (OCI driver) does not work in a multi-threaded
environment when using OracleXADataSource with nativeXA set to
true. The OCI driver uses Oracle's C/XA library to support
distributed transactions, which requires that an XAConnection
be obtained per thread before resuming a global transaction.

JDBC OCI Driver's TAF functionality will not work, when used
in conjunction with JDBC Fast Connection Failover. The problem is
that when TAF is enabled, JDBC Fast Connection Failover
will likely remove connections, that were actually detected
and failed over by TAF. There is no work-around. Users cannot
use TAF and Fast Connection Failover together.

JDBC connections not explicitly closed with close() method are
not implicitly closed after a timeout is reached when using a
datasource based on OracleConnectionCacheImpl. The workaround is
to use the new implicit connection cache.

KPRB driver gets extra characters from database LONG column when
only 1M byte is expected. Problem occur with
OraclePreparedStatement.getCharacterStream() when database
character set is UTF8.

Certain APIs on the OracleDataSource are relevant only on a cache
enabled DataSource. An OracleDataSource is cache enabled only
after setConnectionCachingEnabled API is called on it.

KPRB driver insert 32766 or more characters using
OraclePreparedStatement.setString() into a database LONG column.
Data truncation occur when database character set is ZHT32TRIS.

JDBC Implicit connection cache does not honor minLimit under HA
conditions. When an instance dies, FCF DOWN event processing
removes affected connections and may cause the connection cache
minimum limit to drop below the set value. This is expected, and
the number of connections would ramp up as the application demand
for connections reaches steady state.

THIN driver throw NullPointerExceoption for
OracleResultSet.getString() of invalid characters in AL32UTF8

This is an issue with the JDBC Implicit Connection Cache. The
Connection Cache Manager supports an API refreshCache, which
supports two modes. When REFRESH_ALL_CONNECTIONS mode is
specified, the expected behavior should be to refresh all
connections, including checked out connections. Currently only
available connections in the cache are closed and recreated.

JDBC Implicit connection cache does not trigger any connection
Load Balancing when an instance is started after a DOWN. The
impact is that there may not be any new connections created right
away on the instance that was re-started. There are two parts to
UP event load balancing;
(a) UP event LB upon instance join
(b) UP event LB after an instance DOWN.
This issue impacts the UP event Load Balancing behavior for
scenario (b). Please check OTN for a patch for this bug.

KPRB driver throws ORA-01461 for
OraclePreparedStatement.setCharacterStream() of 1MB or
more data into database LONG and 4k byte into Varchar2 columns in
one statement.