Oracle JDBC Drivers release 8.1.7 README ======================================== What Is New In This Release? ---------------------------- These are the major new features/enhancements in this release: - Statement Caching * Implicit Statement Caching * Explicit Statement Caching - Full XA Support * Including XA Recover and Forget * OracleXid independent implementation for 8.1.7 servers and above - Connection Caching * New Scheme (FIXED_WAIT_SCHEME) * Statement Caching coupling - PLSQL Tables Support for Scalar types (for OCI driver only) - User-Defined Datatypes Performance Enhancement - Object Types Extensions * Serializable Type Descriptors * Accessing collection elements in Java primitive types * Buffering and indexing collection elements * Creating empty Lobs - Support for 56-bit encryption algorithms for connection using the Thin JDBC driver. These are the major bug fixes: - BUG-903011 The JDBC Thin driver could not be used with usernames that contained Latin-1 characters when the server used UTF8 character set. This problem has been fixed in release 8.1.7. - BUG-1052489 There was a problem with PreparedStatements being executed multiple times and the length of one of the bind variables (bound with setBinaryStream or setCharacterStream) increased. This problem has been fixed in release 8.1.7. - BUG-1069768 There was a problem with insertion of ADTs with an image bigger than 4K with the JDBC Thin driver. This problem has been fixed in release 8.1.7. - BUG-1247015 When using ResultSet::getObject() to access CHAR or VARCHAR columns in scrollable result sets, ResultSet::getObject() returned null. - BUG-1349713 getString() of scrollable result sets returns incorrect values if the column data contains multibyte characters. Driver Versions --------------- These are the driver versions in the 8.1.7 release: - JDBC OCI Driver 8.1.7 Client-side JDBC for use on a machine where OCI 8.1.7 is installed. - JDBC Thin Driver 8.1.7 100% Java client-side JDBC for use in applets and applications. - JDBC Thin Server-side Driver 8.1.7 JDBC for use by Java Stored Procedures or by Java CORBA objects running in Oracle 8.1.7. This driver is typically used in a middle tier server. - JDBC Server-side Internal Driver 8.1.7 Server-side JDBC for use by Java Stored procedures or by Java CORBA objects running in Oracle 8.1.7. 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.zip 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.zip NLS classes for use with JDK 1.1.x. It contains classes necessary for NLS support in Object and Collection types. - classes111_g.zip Same as classes111.zip, except that classes were compiled with "javac -g". - classes12.zip 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.zip NLS classes for use with JDK 1.2.x. It contains classes necessary for NLS support in Object and Collection types. - classes12_g.zip Same as classes12.zip, except that classes were compiled with "javac -g". Note that the packaging of the JDBC classes to support NLS was changed in 8i. The classes pertaining to specific character sets support in Object and Collection types have been separated from the basic zip files. These NLS classes are now packaged into the extension zip 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)" for further details. [ORACLE_HOME]/lib directory contains libocijdbc8.so and libocijdbc8_g.so (on Solaris), 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. Demo programs written for JDK 1.1 must be modified to run in JDK 1.2. Please refer to the "Support For JDK 1.2" for porting details. NLS Extension Zip Files (for client-side only) ---------------------------------------------- The JDBC Server-side Internal Driver provides complete NLS support. It does not require any NLS extension zip files, nls_charset*.zip. 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 files, classes111.zip and classes12.zip, 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 file. To do so, users can first unzip the extension zip file, and then put only the necessary classes in the CLASSPATH. The character set extension class files are named in the following format: CharacterConverter.class where is the hexidecimal representation of the Oracle character set id of the corresponding character set. ----------------------------------------------------------------------- Installation ------------ 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\classes111.zip and [ORACLE_HOME]\jdbc\lib\nls_charset11.zip to your CLASSPATH. (Add classes12.zip and nls_charset12.zip if JDK 1.2.x is used.) - Add [ORACLE_HOME]\jdbc\lib to your PATH. On Solaris/Digital Unix: - Add [ORACLE_HOME]/jdbc/lib/classes111.zip and [ORACLE_HOME]/jdbc/lib/nls_charset11.zip to your CLASSPATH. (Add classes12.zip and nls_charset12.zip if JDK 1.2.x is used.) - Add [ORACLE_HOME]/jdbc/lib to your LD_LIBRARY_PATH. On HP/UX: - Add [ORACLE_HOME]/jdbc/lib/classes111.zip and [ORACLE_HOME]/jdbc/lib/nls_charset11.zip to your CLASSPATH. (Add classes12.zip and nls_charset12.zip if JDK 1.2.x is used.) - Add [ORACLE_HOME]/jdbc/lib to your SHLIB_PATH and LD_LIBRARY_PATH. On AIX: - Add [ORACLE_HOME]/jdbc/lib/classes111.zip and [ORACLE_HOME]/jdbc/lib/nls_charset11.zip to your CLASSPATH. (Add classes12.zip and nls_charset12.zip 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: DriverManager.registerDriver( new oracle.jdbc.driver.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 OCI8 Driver: Connection conn = DriverManager.getConnection( "jdbc:oracle:oci8:@", "scott", "tiger"); where 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( "jdbc:oracle:thin:@", "scott", "tiger"); where is either a string of the form :: or a SQL*net name-value pair. For the JDBC Server-side Internal Driver: Connection conn = DriverManager.getConnection( "jdbc:oracle:kprb:"); 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.driver.OracleDriver().defaultConnection(); Java Stored Procedures ---------------------- Please note that examples for callins and instance methods using Oracle 8 Object Types are provided in: [ORACLE_HOME]/javavm/demo/demo.zip Once unzipped, the directory containing the examples is: [ORACLE_HOME]/javavm/demo/examples/jsp 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 data. - Inserts of Object Types (Oracle 8 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. 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 defineColumnType. 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 deprecated. 10. BUG-899078 (since 8.1.6 SDK): 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 oracle.sql.CustomDatum 12. The scrollable result set implementation has the following limitation: - 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 ------------------------------------------------------- no TYPE_FORWARD_ONLY CONCUR_READ_ONLY no TYPE_FORWARD_ONLY CONCUR_UPDATABLE no TYPE_SCROLL_INSENSITIVE CONCUR_READ_ONLY yes TYPE_SCROLL_INSENSITIVE CONCUR_UPDATABLE yes TYPE_SCROLL_SENSITIVE CONCUR_READ_ONLY yes TYPE_SCROLL_SENSITIVE CONCUR_UPDATABLE 13. BUG-1324918 Repeatedly updating a clob with jdbc-oci, prepared statement, and setCharacterStream consumes the temporary tablespace. If you repeatedly update the clob, either the temp tablespace will continue to grow, or you may get a Exception in thread "main" java.sql.SQLException: ORA-01652: unable to extend segment if you have a limit on the tablespace size. The work-around is to use oracle.sql.CLOB::setCharacterOutputStream() instead.