Oracle JDBC Drivers release 9.0.1 README

What Is New In This Release Since 8.1.7 ?

These are the major Oracle specific features/enhancements in this

- NCHAR support for storing unicode data

- Object type inheritance

- Multiple level Collection

- SQLJ Object types in SQLData representation

- New LOB APIs to support temporary LOBs, trim(), open/close and
getXXXStream(offset) to read/write LOBs from specified offset.

- NativeXA support in the JDBC OCI driver
* Extends Java XA support to Oracle 8.0 databases and higher
* Improves performance of Java XA

- Additional Functionality in the JDBC OCI driver
* OCI Connection Pooling
* Middle-tier authentication
* Transparent Application Failover (TAF)

- DATETIME data types. (This feature is only supported in the
Jdbc Thin driver with JDK 1.2.)

- New package oracle.jdbc with interfaces and classes that contain
the Oracle extensions. Package oracle.jdbc.driver deprecated.

These are the major bugs fixed in since 8.1.7:

- BUG-1319755 (since 8.1.6)
There was memory leak in the JDBC OCI driver when statements
were being re-used.

- BUG-1338356 (since 8.1.6)
The value set by OracleStatement.setRowPrefetch() was
overwritten in some cases.

- BUG-1346564 (since 8.1.5)
The returned value of OracleResultSetMetaData.isNullable() was
not consistent across the JDBC Thin and OCI drivers.

- BUG-1403594 (since 8.1.6)
JDBC connections returned ORA-28000 before FAILED_LOGIN_ATTEMPTS
were reached. When FAILED_LOGIN_ATTEMPTS were set through a
profile and assigned to a database user, the user's account would
be locked before the specified number of failed attempts was
reached. This was the case with any JDBC Thin or OCI programs
that tried to log on to the database under these circumstances.

- BUG-1454333 (since 8.1.6)
There were deadlocks between Connection and Statement resources.

- BUG-1483556 (since 8.1.7)
The JDBC Thin driver hung in some cases during an insert.

- BUG-1500535 (since 8.0.6)
The user could not identify client process in V$SESSION for a
JDBC Thin client. Now, the user can set "v$session.process" as
part of the connection property.

Driver Versions

These are the driver versions in the 9.0.1 release:

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

- JDBC Thin Driver 9.0.1
100% Java client-side JDBC driver for use in Java applets and

- JDBC Thin Server-side Driver 9.0.1
JDBC driver for use by Java Stored Procedures or by Java CORBA
objects running in Oracle 9.0.1. This driver is typically used
in a middle tier server.

- JDBC Server-side Internal Driver 9.0.1
Server-side JDBC driver for use by Java Stored procedures or by
Java CORBA objects running in Oracle 9.0.1. 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


The [ORACLE_HOME]/jdbc/lib directory contains:

- & classes111.jar
Classes for use with JDK 1.1.x. It contains the JDBC driver
classes except classes necessary for NLS support in Object and
Collection types.

- & nls_charset11.jar
NLS classes for use with JDK 1.1.x. It contains classes necessary
for NLS support in Object and Collection types.

- & classes111_g.jar
Same as, except that classes were compiled with
"javac -g" and contain tracing information.

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

- & nls_charset12.jar
NLS classes for use with JDK 1.2.x. It contains classes necessary
for NLS support in Object and Collection types.

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

In general, <file>.zip and <file>.jar are identical except for the
format of the archive. Both the .zip and .jar formats are provided.

Note that most of the classes pertaining to specific character sets
support in Oracle Object and Collection types are separated from the
basic zip/jar files. These NLS classes are packaged into the
extension zip/jar files. This allows the user to include the NLS
classes only if necessary. Please refer to the "NLS Extension Zip
Files (for client-side only)" section for further details.

[ORACLE_HOME]/lib directory contains ocijdbc9.dll, ocijdbc9_g.dll,
heteroxa9.dll, heteroxa9_g.dll (on NT), which are the shared libraries
used by the JDBC OCI driver.

[ORACLE_HOME]/jdbc/doc/javadoc.tar contains the JDBC Javadoc. This
release contains a beta release of the Javadoc files for the public
API of the public classes of Oracle JDBC.

[ORACLE_HOME]/jdbc/demo/demo.tar contains sample JDBC programs.
Some demo programs were written for JDK 1.1 and the other for JDK 1.2.
The makefiles in each demo subdirectory will by default use a working
JDK version. The demos that work with JDK 1.1 can be easily converted
to used JDK 1.2 via the jdk12-convert make target. The demos that work
with JDK 1.2 can be converted to work with JDK 1.1, but this will take
some hand editing.

NLS and NLS Extension Zip/Jar Files (for client-side only)

The JDBC Server-side Internal Driver provides complete NLS support.
It does not require any NLS extension zip/jar files, nls_charset*.*.
Discussions in this section do not apply to the JDBC Server-side
Internal Driver. You can skip this section if you only use the
Server-side Internal Driver.

The basic zip/jar files (, classes111.jar, and classes12.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 8
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 and UTF8.

Users must include the appropriate extension zip in their CLASSPATH
if utilization of other character sets in CHAR/VARCHAR data members
of Objects/Collections is desired. It is important to note that
extension zip files are large in size due to the requirement of
supporting a large number of character sets. Users may choose to
include only the necessary classes from the extension zip/jar file.
To do so, users can first un-pack the extension zip/jar file, and
then put only the necessary classes in the CLASSPATH. The character
set extension class files are named in the following format:


where <OracleCharacterSetId> is the hexadecimal representation of the
Oracle character set id of the corresponding character set.

In addition, users can also include internationalized Jdbc error
message files selectively. The message files are included in
classes*.* with the name oracle/jdbc/dbaccess/Messages_*.properties.



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 Win95/Win98/NT:
- Add [ORACLE_HOME]\jdbc\lib\ and
[ORACLE_HOME]\jdbc\lib\ to your CLASSPATH.
(Add and if JDK 1.2.x is used.)
- Make sure [ORACLE_HOME]\bin is in your PATH.

On Solaris/Digital Unix:
- Add [ORACLE_HOME]/jdbc/lib/ and
[ORACLE_HOME]/jdbc/lib/ to your CLASSPATH.
(Add and if JDK 1.2.x is used.)
- Add [ORACLE_HOME]/jdbc/lib to your LD_LIBRARY_PATH.

- Add [ORACLE_HOME]/jdbc/lib/ and
[ORACLE_HOME]/jdbc/lib/ to your CLASSPATH.
(Add and if JDK 1.2.x is used.)
- Add [ORACLE_HOME]/jdbc/lib to your SHLIB_PATH and LD_LIBRARY_PATH.

- Add [ORACLE_HOME]/jdbc/lib/ and
[ORACLE_HOME]/jdbc/lib/ to your CLASSPATH.
(Add and if JDK 1.2.x is used.)
- Add [ORACLE_HOME]/jdbc/lib to your LIBPATH and LD_LIBRARY_PATH.

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.*;

2. Register the Oracle driver before before calling other JDBC APIs.
(This is not needed if you are using the JDBC Server-side Internal
Driver because registration is done automatically in the server.)
To register the Oracle driver, make sure the following statement
is executed at least once in your Java session:

new oracle.jdbc.OracleDriver());

3. Open a connection to the database with the getConnection call.
Different connection URLs should be used for different JDBC
drivers. The following examples demonstrate the different URLs.

For the JDBC OCI Driver:

Connection conn = DriverManager.getConnection(
"my_user", "my_password");

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

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

Connection conn = DriverManager.getConnection(
"my_user", "my_password");

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

For the JDBC Server-side Internal Driver:

Connection conn = DriverManager.getConnection(

Note that the trailing ':' character 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();

New Package oracle.jdbc

Beginning in Oracle 9i, the 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.

Your code should use the package oracle.jdbc instead of the package
oracle.jdbc.driver used in earlier versions of Oracle. Use of the
package oracle.jdbc.driver is now deprecated, but will continue to be
supported for backwards compatibility.

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. Conversion is
not required, but is highly recommended. Future releases of Oracle may
have features that are incompatible with use of the package

The purpose of this change in to enable the Oracle JDBC drivers to
have multiple implementations. In all releases up to and including
Oracle 9i, all of the Oracle JDBC drivers have used the same top level
implementation classes, the classes in the package
oracle.jdbc.driver. By converting your code to use oracle.jdbc, you
will be able to take advantage of future enhancements that use
different implementation classes. There are no such enhancements in
Oracle 9i, but there are plans for such enhancements in the future.

Additionally, these interfaces permit the use of some code patterns
that are difficult to use when your code uses the package
oracle.jdbc.driver. For example, you can more easily develop wrapper
classes for the Oracle JDBC classes. If you wished to wrap the
OracleStatement class in order to log all SQL statements, you could
easily do so by creating a class that wraps OracleStatment. That class
would implement the interface oracle.jdbc.OracleStatement and hold an
oracle.jdbc.OracleStatement as an instance variable. This wrapping
pattern is much more difficult when your code uses the package
oracle.jdbc.driver as you cannot extend the class

Once again, your code should use the new package oracle.jdbc instead
of the package oracle.jdbc.driver. Conversion is not required as
oracle.jdbc.driver will continue to be supported for backwards
compatibility. Conversion is highly recommended as there may in later
releases be features that are not supported if your code uses

Java Stored Procedures

Please note that examples for callins and instance methods using Oracle
8 Object Types are provided in:


Once unzipped, the directory containing the examples is:


Known Problems/Limitations In This Release


The following is a list of known problems/limitations:

1. There is a limitation regarding the use of stream input for LOB
types. Stream input for LOB types can only be used for 8.1.7
JDBC OCI driver connecting to an 8.1.7 Oracle server. The use of
stream input for LOB types in all other configurations may result
in data corruption. PreparedStatement stream input APIs include:
setBinaryStream(), setAsciiStream(), setUnicodeStream(),
setCharacterStream() and setObject().

2. BUG-1018797
Extra characters may be appended to the end of a CLOB value
mistakenly under the following conditions:
- setCharacterStream() is used to insert a CLOB value, and
- The Oracle server uses multi-byte character set.

(See 1 for limitation of stream input for LOB type.)

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

4. The Server-side Internal Driver has the following limitation:
- Data access for LONG and LONG RAW types is limited to 32K of
- Inserts of Object Types (Oracle Objects, Collections and
References) will not work when the database compatibility mode
is set to 8.0. This limitation does not apply when the
compatibility mode is set to 8.1.
- Statement.cancel() is not implemented.
- 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.

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

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

7. When using OracleStatement.defineColumnType(), it is not necessary
to define the column type to be the same as the column type
declared in the database. If the types are different, the
retrieved values are converted to the type specified in

Note: Most reasonable conversions work, but not all. If you find
a conversion that you think is reasonable, but that does not work,
please submit a TAR to Oracle Support.

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

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

10. BUG-899078 (since 8.1.6)
The JDBC Server-side Internal driver has extra space padding with
PL/SQL CHAR OUT (2 to 3 space depending on character set).
Problem occurs in most of the multibyte database character set
except UTF8.

11. There is a limitation for Triggers implemented in Java and Object
Types. It only affects the IN argument types of triggers
implemented using Java on the client-side. The restriction does
not apply to JDBC programs running inside the server. Triggers
implemented as Java methods cannot have IN 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

12. The scrollable result set implementation has the following

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

Support Type Concurrency

13. BUG-1324918
The JDBC OCI driver can consume temporary tablespace when it is
used to update a CLOB with PreparedStatement.setCharacterStream()
repeatedly. In such situation, either the temp tablespace will
continue to grow, or you may get this exception in thread "main":
java.sql.SQLException: ORA-01652: unable to extend segment if
you have a limit on the tablespace size. The workaround is to
use oracle.sql.CLOB::setCharacterOutputStream() instead.

14. BUG-1516862 (since 9.0.0)
Passing an OPAQUE type as an argument to a Java Stored Procedure
does not work.

15. BUG-1542130 (since 9.0.0)
The use of OciConnectionPool may cause a hang in a multi-threaded

16. BUG-1591421 (since 9.0.0)
A connection created from the connection cache fails to pass the
default batch value to the statement object.

17. BUG-1630414 (since 9.0.0)
After a type evolution is performed on an existing type, objects
of the evolved type cannot be retrieved via JDBC.

18. BUG-1640110 (since 9.0.0)
The JDBC OCI driver may hang when executing a query with invalid
double quotes in the query string. This problem only occurs when
the NLS_LANG environment variable is set.

19. Access to the new Datetime datatypes is only supported in the
Jdbc Thin driver with JDK 1.2. These Datetime data types
String APIs like PreparedStatement.setString() and
Resultset.getString() do not work for these data types. Users
must use setTIMESTAMP*() and getTIMESTAMP*().

20. BUG-1730903 (since 9.0.0)
setFormOfUse() method must be put before blinding/definding SQL
NCHAR datatypes. For example, setString() and
registerOutParameter() has to be called after setFormOfUse().
Otherwise, unpredictable results will be received. This
restriction applies to all JDBC drivers.

21. BUG-1714281 (since 9.0.1)
The maximum number of characters can be inserted into NCHAR
datatypes using setString() is less than the database maximum
size if the database character set is neither US7ASCII nor
WE8ISO8859P1. This restriction applies to JDBC Thin and Thin
Server-side drivers. Workaround is to use setCharacterStream().

22. BUG-1714947 (since 9.0.1)
oracle.sql.JAVA_STRUCT produces class not found
exception when used by code run in Oracle9i JVM. The problem is
that the code in JAVA_STRUCT uses Class.forName to find the
class which is specified in the create type statement for the
object type. But in Oracle9i JVM a Class.forName call uses the
class loader appropriate for the class from which it is
called. Since the Oracle JDBC code is loaded in SYS, the class
loader searches SYS and PUBLIC. A workaround is to create a
public synonym for the class. This workaround has several
problems, however.

23. BUG-1720657 ( since 9.0.1)
Java code runing on the server which uses the KPRB driver to execute
multiple create type statements may cause server crashes. Similar
problems exist if a PL/SQL block uses execute immediate to execute
the same statements. The workaround is to use the thin driver or to
perform the needed operations another way.

24. Page 5-13 of the Oracle9i JDBC Developer's Guide and Reference
refers to "US_PACIFIC" as an example of an Oracle time zone.
This is incorrect. It should be "US/Pacific" instead.