Oracle JDBC Drivers release - Production README

What Is New In This Release ?

Support for Java Standard Edition 6 (JSE6) and JDBC 4.0
JSE 6 (AKA Mustang) is supported by the Thin and OCI drivers
including support for the new JDBC spec, JDBC 4.0. The new
java.sql.SQLXML type is not supported in this release. JSE 6 is
supported by the new Oracle JDBC jar files: ojdbc6.jar,
ojdbc6_g.jar, ojdbc6dms.jar, and ojdbc6dms_g.jar. This
release conforms with the JSE 6 production release.

J2SE 5.0 and JDBC 3.0 are fully supported by the other jars
contained in this release. The Server Internal Driver and Thin in
the Server driver support J2SE 5/ JDK 1.5 only.

Desupport of oracle.jdbc.driver
In the initial release of the Oracle JDBC drivers customers were
advised to use the classes defined in the package
oracle.jdbc.driver. This has caused problems for customers and for
Oracle. In Oracle JDBC release 9.0.1 customer use of the classes
in that package was deprecated. A new package, oracle.jdbc, was
introduced and customers were advised to begin using the
interfaces and classes defined in oracle.jdbc. In every release
since 9.0.1 we have encouraged customers to switch to oracle.jdbc
and stated that oracle.jdbc.driver would be desupported. The time
has come. Customer code that references oracle.jdbc.driver will
not compile and will not execute in this and future releases of
the Oracle JDBC drivers. Please use oracle.jdbc instead.

If you are using a class in oracle.jdbc.driver which does
not have an equivalently named type in oracle.jdbc, then customer
use of that class was never supported and you will need to find
another solution. The only exception is
oracle.jdbc.driver.OracleLog. Customers can still reference that
class for debugging purposes. Even in that case Oracle reccommends
that you use the Oracle JDBC Diagnosability MBean instead. See the
Oracle JDBC Developer's Guide for details.

J2SE 1.2, 1.3, and 1.4 Desupported
Oracle 11R1 does not support J2SE 1.2, 1.3, and 1.4. The .zip and .jar
files that support those versions of J2SE are not included in
Oracle JDBC 11R1. If you are still using J2SE 1.2, 1.3, or 1.4 you can
continue to use Oracle JDBC with those versions of
Java. 10gR2 is still fully supported for use with those versions
of Java. If you want to use Oracle JDBC 11R1 you must use J2SE 5.0
or later.

Support of additional security features in the Thin driver
Oracle JDBC 11R1 Thin driver supports the AES encryption
algorithm, SHA1 hash algorithm, and RADIUS, KERBEROS and SSL
authentication mechanisms. TLS_RSA_WITH_AES_128_CBC_SHA and
TLS_RSA_WITH_AES_256_CBC_SHA ciphers can now be used with the JDCB
Thin driver.

Support for the SQL ANYDATA, and ANYTYPE types
The ANYDATA, and ANYTYPE SQL types were introduce in
Oracle 9i. Prior to Oracle JDBC 11R1 Java programmers could
manipulate these types only via PL/SQL. Oracle JDBC 11R1 provides
a Java interface for using these types. See the Oracle JDBC 11R1
Developer's Guide for more info.

Advanced AQ support for Thin
Oracle JDBC 11R1 provides a new high performance interface for
accessing AQ, Oracle Advanced Queueing. This new interface is
faster and more capable than the existing PL/SQL based interface
and leverages the new support for the ANYDATA, ANYTYPE,

Support for Database Change Notification
Oracle Database 9i introduced Database Change Notification, the
capability to identify tables or queries of interest and receive
notification whenever one of them changes. Oracle JDBC 11R1
provides native Java support for this powerful feature. Every
developer who has a data cache should get the Oracle JDBC 11R1
Developer's Guide and learn how Database Change notification
works. If you don't have a data cache because the cost of stale
data was too high, DCN may make a cache possible.

Database startup and shutdow -- Thin and OCI
Oracle JDBC 11R1 provides methods for starting and shutting down
an Oracle Database.

New Factory Methods
The JDBC 4.0 spec for java.sql.Connection includes factory methods
for creating instances of the standard JDBC types, Array, Blob,
Clob, etc. Building on this concept Oracle JDBC 11R1
oracle.jdbc.OracleConnection provides factory methods for creating
instances of the Oracle specific types. Best practice is to use
the standard JDBC types and the new factory methods. When it is
necessary to use the Oracle specific types best practice is to
create them via the new factory methods. Direct customer access to
the the constructors for these types will be deprecated and later
desupported. The supported types are all those in oracle.sql,

Reduced Memory Footprint
In 10gR1 we rearchitected the drivers to improve performance at
the cost of increasing memory footprint, especially when using the
(highly recommended!) statement cache. We achieved our goal of
improving performance, but the increase in memory footprint has
sometimes proved problematic. The 11R1 release retains all of the
performance improvements while dramatically reducing memory
footprint when using the statement cache. Best practice is to
close statements when not in use. The cost of returning a
statement to the cache and retrieving it from the cache is
minimal. Each open statement does have a substantial memory
footprint. The footprint of closed statements is minimal. Our
testing has shown that closing unused statements when using the
statement cache actually improves performance due to the reduced
memory footprint.

Driver Versions

These are the driver versions in the 11R1 release:

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

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

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

- JDBC Server-side Internal Driver 11R1
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:

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

- ojdbc5_g.jar
Same as ojdbc5.jar, except that classes were compiled with
"javac -g" and contain tracing code.

- ojdbc5dms.jar
Same as ojdbc5.jar, except that it contains instrumentation to
support DMS and limited java.util.logging calls.

- ojdbc5dms_g.jar
Same as ojdbc5_g.jar, except that it contains instrumentation to
support DMS.

- ojdbc6.jar
Classes for use with JDK 1.6. It contains the JDBC driver classes
except classes for NLS support in Oracle Object and Collection

- ojdbc6_g.jar
Same as ojdbc6.jar except compiled with "javac -g" and contains
tracing code.

- ojdbc6dms.jar
Same as ojdbc6.jar, except that it contains instrumentation to
support DMS and limited java.util.logging calls.

- ojdbc6dms_g.jar
Same as ojdbc6_g.jar except that it contains instrumentation to
support DMS.

Note: The dms versions of the jar files are the same as
standard jar files, except that they contain additional code
to support Oracle Dynamic Monitoring Service. They contain a
limited amount of tracing code. These can only be used
when dms.jar is in the classpath. dms.jar is provided as part of
Oracle Application Server releases. As a result the dms versions
of the jar files can only be used in an Oracle Application Server

[ORACLE_HOME]/jdbc/doc/javadoc.tar contains the JDBC Javadoc
for the public API of the public classes of Oracle JDBC. This
JavaDoc is the primary reference for Oracle JDBC API extensions. The
Oracle JDBC Development Guide contains high level discussion of
Oracle extensions. The details are in this JavaDoc. The JavaDoc is
every bit as authorative as the Dev Guide.

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

NLS classes for use with JDK 1.5, and 1.6. 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 ocijdbc11.dll and
heteroxa11.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 (ojdbc5.jar and ojdbc6.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 ojdbc5*.jar and



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\ojdbc5.jar to
your CLASSPATH if you use JDK 1.5 or
[ORACLE_HOME]\jdbc\lib\ojdbc6.jar if you use JDK 1.6.
- 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/ojdbc5.jar to your CLASSPATH if you
use JDK 1.5 or [ORACLE_HOME]/jdbc/lib/ojdbc6.jar if you use JDK 1.6
- 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/ojdbc5.jar to your CLASSPATH if you
use JDK 1.5 or [ORACLE_HOME]/jdbc/lib/ojdbc6.jar if you use JDK 1.6
- 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/ojdbc5.jar to your CLASSPATH if you
use JDK 1.5 or [ORACLE_HOME]/jdbc/lib/ojdbc6.jar if you use JDK 1.6
- 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 Development Guide and Reference" and the Oracle
JDBC JavaDoc contained in demo/doc/javadoc.tar 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 Is GONE!

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 continued
to support the old package oracle.jdbc.driver in previous releases to
provide backwards compatibility, the package has been removed in
Oracle JDBC 11R1, as we have been promising. If you still have existing
applications that use the old oracle.jdbc.driver package, you must
convert them to use Oracle JDBC 11R1.

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. If your
application references a class or method in oracle.jdbc.driver that
does not have a type of the same name in oracle.jdbc, then that type
or method was never intended for customer use and you will have to
find a different solution.

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

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

Proxy authentication fails with thin driver when the password is
specified seperately.

getUpdateCount returns wrong values with batching.

Convertion from AL16UTF16 to UTF16 is surrogate character

Behavioural difference in isBeforeFirst between thin and oci when fetched as

Jdbc thin does not close the socket on a IOException.

Null inserted through CachedRowset cannot be deleted without

Binding a Time value to the database in an insert used to set the Date
component as 01-Jan-1900 in 9i since, the method java.sql.Time().getTime()
does not trim the date component.
However, during re-architecture of Jdbc in 10g this behavior was changed and
the date component was not reset. This caused a regression for 9i customers.

Resetting the value to 01-Jan-1900 by default would cause a regression for
the 10g users who have been using the flag for over 4 years until now.
So a new connection flag oracle.jdbc.use1900AsYearForTime was introduced
which would force the driver to set the date component in the Time to
01-Jan-1900. The default value of this flag is false.

The user input is passed to the server without checking its

Jdbc does not let user close the connection when the connection
hits ORA-3113.

ArrayOutOfBoundsException while using Jdbc with a big batch.

ORA-00600 when reading a Struct with null attributes bound.

Large memory used for null columns.

SQLException when using savepoints with a pooled connection.

NullPointerException while using OCI driver from checkError.

Appears as an exception when serializing an instance of an
oracle.sql.Datum subclass.

JDBC driver throws MalformedObjectException or InstanceAlreadyExistsException
when loading.

DMS version of JDBC method Namespace.setAttribute throws a
NullPointerException when communicating with the database.

The FUNCTION_TYPE column is not present in the ResultSet returned
by DatabaseMetadata.getFunctions.

JDBC driver consumes large amounts of memory. Application uses Oracle JDBC
implicit statement cache, has many open connections, and only a very few
connections are in use at any one time. All other connections are unused
and all statements in those connections are closed.

Four JDBC internal calls to methods with public APIs appear in the trace log
even when configured for public calls only.

Query used for DatabaseMetaData.getColumns is very slow when
setIncludeSynonyms is true.

Use of the stream obtained from java.sql.Blob.setBinaryStream and
CLob.setCharacterStream and setAsciiStream is slow when the
buffers written to the stream are megabyts in size.

DatabaseMetaData.getColumns returned the schema the target table
rather then the schema of a synonym.

Buffer sizes for InputStreams and Readers will adapt to the size of
user read calls for sizes over about 32k

Excessive network usage and this rdbms resources during commit.

OracleConnection.getEncryptionAlgorithmName does not return the
cipher used when the connection is using SSL.

The AQ notification event doesn't handle character strings correctly
if orai18n.jar isn't in the classpath.

When using PKCS12 wallets, Oracle's PKI provider needs to be
used. If it's enabled statically through, it also
needs to be instantiated in the Java code otherwise it won't be
used. This is a bug, it should be instantiated by the driver not
the user code.

The connection property "" isn't
properly handled.

The thin driver doesn't return the right database version.

Timestamp values are incorrect around daylight savings time change
when the client time zone is different from the session time zone.

Same as 6749320 above but for TIMESTAMP WITH LOCAL TIME ZONE.

Wrong value TIMESTAMPLTZ when the retrieved timestamp is in the
DST overlap for the session timezone.

Wrong value of TIMESTAMPTZ with the retrieved value is near the
DST changeover.

Error code 0 masking the real error code when getting a connection
with the Thin driver.

setQueryTimeout does not work when calling

NullPointerException in oracle.jdbc.driver.ThrowSqlException
caused by IOError.

Alter user with password fails when the new password contains a
question mark (?).

setTypeMap alters its argument, adding two additional entries.
This fix alters the driver behavior so that it copies the argument
rather than capturing it. Some code may no longer work. The new
behavior is fully conformant with the JDBC specification and the
user code will have to be changed. This will happen when the user
code calls setTypeMap and the alters the map, expecting that the
driver will see the change or when the user code calls getTypeMap
and then alters the map.

ResultSetMetadata.getColumnTypeName is not descriptive for

SQLEexception when the user.language is set to "sr" (Serbian).

DatabaseMetaData.getColumns returns the wrong length for NCHAR

Statement.cancel does not work with

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.

* 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. BUG-5965340
- 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.

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

* 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

* 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

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.

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.

A SQL string like "{ call spLengthTest(?, ?) }" shows improper
truncation of a varchar OUT argument with length beyond 4000 when
the escaped form is used, but correct behavior when the Oracle
specific PL/SQL block like "begin spLengthTest(?, ?); end;" is

If a result set contains a TIMESTAMPLTZ column followed by a LONG
column, reading the LONG column gets an error.

If a statement creates an updatable ResultSet, subsequently
calling addBatch and executeBatch does not close the ResultSet as
it should. Subsequent accesses to the ResultSet can cause data

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