19 Globalization Support

Providing Globalization Support

The basic Java Archive (JAR) files, ojdbc5.jar and ojdbc6.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 object or collection type.

• CHAR or VARCHAR data members of object and collection for the character sets US7ASCII, WE8DEC, WE8ISO8859P1, WE8MSWIN1252, and UTF8.

To use any other character sets in CHAR or VARCHAR data members of objects or collections, you must include orai18n.jar in the CLASSPATH environment variable of your application.

Compressing orai18n.jar

The orai18n.jar file contains many important character set and globalization support files. You can reduce the size of orai18n.jar using the built-in customization tool, as follows:

java -jar orai18n.jar -custom-charsets-jar [jar/zip_filename] -charset characterset_name [characterset_name ...]

For example, if you want to create a custom character set file, custom_orai18n_ja.jar, that includes the JA16SJIS and JA16EUC character sets, then issue the following command:

$ java -jar orai18n.jar -custom-charsets-jar custom_orai18n_ja.jar -charset JA16SJIS JA16EUC

The output of the command is as follows:

Added Character set : JA16SJIS
Added Character set : JA16EUC

If you do not specify a file name for your custom JAR/ZIP file, then a file with the name jdbc_orai18n_cs.jar is created in the current working directory. Also, for your custom JAR/ZIP file, you cannot specify a name that starts with orai18n.

If any invalid or unsupported character set name is specified in the command, then no output JAR/ZIP file will be created. If the custom JAR/ZIP file exists, then the file will not be updated or removed.

The custom character set JAR/ZIP does not accept any command. However, it prints the version information and the command that was used to generate the JAR/ZIP file. For example, you have jdbc_orai18n_cs.zip, the command that displays the information and the displayed information is as follows:

$ java -jar jdbc_orai18n_cs.jar
Oracle Globalization Development Kit - 11.2.X.X.X Release
This custom character set jar/zip file was created with the following command:
java -jar orai18n.jar -custom-charsets-jar jdbc_orai18n_cs.jar -charset WE8ISO8859P15

The limitation to the number of character sets that can be specified depends on that of the shell or command prompt of the operating system. It is certified that all supported character sets can be specified with the command.

NCHAR, NVARCHAR2, NCLOB and the defaultNChar Property in JDK 1.5

By default, the oracle.jdbc.OraclePreparedStatement interface treats the data type of all the columns in the same way as they are encoded in the database character set. However, since Oracle Database 10g, if you set the value of oracle.jdbc.defaultNChar system property to true, then JDBC treats all character columns as being national-language.

The default value of defaultNChar is false. If the value of defaultNChar is false, then you must call the setFormOfUse(<column_Index>, OraclePreparedStatement.FORM_NCHAR) method for those columns that specifically need national-language characters. For example:

PreparedStatement pstmt =
conn.prepareStatement("insert into TEST values(?,?,?)");
pstmt.setFormOfUse(1, OraclePreparedStatement.FORM_NCHAR);
pstmt.setString(1, myUnicodeString1); // NCHAR column
pstmt.setFormOfUse(2, OraclePreparedeStatement.FORM_NCHAR);
pstmt.setString(2, myUnicodeString2); // NVARCHAR2 column

If you want to set the value of defaultNChar to true, then specify the following at the command-line:

java -Doracle.jdbc.defaultNChar=true myApplication

If you prefer, then you can also specify defaultNChar as a connection property and access NCHAR, NVARCHAR2, or NCLOB data.

Properties props = new Properties();
props.put(OracleConnection.CONNECTION_PROPERTY_DEFAULTNCHAR, "true");
// set URL, username, password, and so on.
...
Connection conn = DriverManager.getConnection(props);

If the value of defaultNChar is true, then you should call the setFormOfUse(<column_Index>, FORM_CHAR) for columns that do not need national-language characters. For example:

PreparedStatement pstmt =
conn.prepareStatement("insert into TEST values(?,?,?)");
pstmt.setFormOfUse(3, OraclePreparedStatement.FORM_CHAR);
pstmt.setString(3, myString); // CHAR column

New Methods for National Character Set Type Data in JDK 1.6

JDBC 4.0 introduces support for the following four additional SQL types to access the national character set types:

• NCHAR

• NVARCHAR

• LONGNVARCHAR

• NCLOB

These types are similar to the CHAR, VARCHAR, LONGVARCHAR, and CLOB types, except that the values are encoded using the national character set. The JDBC specification uses the String class to represent NCHAR, NVARCHAR, and LONGNVARCHAR data, and the NClob class to represent NCLOB values.

To retrieve a national character value, an application calls one of the following methods:

• getNString

• getNClob

• getNCharacterStream

• getObject

To specify a value for a parameter marker of national character type, an application calls one of the following methods:

• setNString

• setNCharacterStream

• setNClob

• setObject