12 Globalization Support

Providing Globalization Support

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

• Oracle character sets for CHAR, VARCHAR. LONGVARCHAR, or CLOB data that is not being retrieved or inserted as a data member of an Oracle 8 Object or Collection type.

• CHAR or VARCHAR data members of Object and Collection for the character setsUS7ASCII, WE8DEC, WE8ISO8859P1 and UTF8.

To use any other character sets in CHAR or VARCHAR data members of Objects or Collections, you must include orai18n.jar in your application's CLASSPATH.

The file orai18n.jar is large because it supports a large number of character sets. You can include only the character set classes you use in your application. To do so, unpack orai18n.jar, then put only the necessary files in your CLASSPATH.

The character set extension class files are named in the following format:

where Oracle...Id is the hexadecimal representation of the Oracle character set, territory, collation sequence, or mapping ID that corresponds to a character set name. These IDs can be found in the Oracle Globalization Development Kit Java API Reference.

You can also include internationalized JDBC error message files selectively. The message files are included in classes*.* under the name oracle/jdbc/driver/Messages_*.properties.

NCHAR, NVARCHAR2, NCLOB and the defaultNChar Property

By default, oracle.jdbc.OraclePreparedStatement treats all columns as CHAR. To insert Java strings into NCHAR, NVARCHAR2, and NCLOB columns, developers had to invoke setFormOfUse() on each national-language column. At this release, if you set the system property oracle.jdbc.defaultNChar to true, JDBC treats all character columns as being national-language. The default value for defaultNChar is false.

To set defaultNChar, you specify a command line like:

java -Doracle.jdbc.defaultNChar=true myApplication

If you prefer, your application can specify defaultNChar as a connection property.

After this property is set, your application can access NCHAR, NVARCHAR2, or NCLOB data without invoking setFormOfUse(). For example:

PreparedStatement pstmt =
conn.prepareStatement("insert into TEST values(?,?,?)");
pstmt.setInt(1, 1); // NUMBER column
pstmt.setString(2, myUnicodeString1); // NVARCHAR2 column
pstmt.setString(3, myUnicodeString2); // NCHAR column
pstmt.execute();

However, if you set defaultNChar to true and then access CHAR columns, the database will implicitly convert all CHAR data into NCHAR. This conversion has a substantial performance impact. To avoid this, call setFormOfUse(4,OraclePreparedStatement.FORM_CHAR) for each CHAR referred to in the statement. For example:

PreparedStatement pstmt =
conn.prepareStatement("insert into TEST values(?,?,?)");
pstmt.setInt(1, 1); // NUMBER column
pstmt.setString(2, myUnicodeString1); // NVARCHAR2 column
pstmt.setString(3, myUnicodeString2); // NCHAR column
pstmt.setFormOfUse(4, OraclePreparedStatement.FORM_CHAR);
pstmt.setString(4, myString); // CHAR column
pstmt.execute();

JDBC Methods Dependent On Conversion

Here are a few examples of commonly used Java methods for JDBC that rely heavily on character set conversion:

• The java.sql.ResultSet methods getString() and getUnicodeStream() return values from the database as Java strings and as a stream of Unicode characters, respectively.

• The oracle.sql.CLOB method getCharacterStream() returns the contents of a CLOB as a Unicode stream.

• The oracle.sql.CHAR methods getString(), toString(), and getStringWithReplacement() convert the following data to strings:

  • getString(): This converts the sequence of characters represented by the CHAR object to a string and returns a Java String object.

  • toString(): This is identical to getString(), but if the character set is not recognized, then toString() returns a hexadecimal representation of the CHAR data.

  • getStringWithReplacement(): This is identical to getString(), except characters that have no Unicode representation in the character set of this CHAR object are replaced by a default replacement character.