Skip Headers
Oracle® Database JDBC Developer's Guide and Reference,
11g Release 1 (11.1)

Part Number B31224-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

19 Globalization Support

The Oracle Java Database Connectivity (JDBC) drivers provide globalization support, formerly known as National Language Support (NLS). Globalization support enables you retrieve data or insert data into a database in any character set that Oracle supports. If the clients and the server use different character sets, then the driver provides the support to perform the conversions between the database character set and the client character set.

This chapter contains the following sections:

See Also:

Note:

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:

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.

Note:

Previous releases depended on the nls_charset12.zip file. This file is now obsolete.

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

Note:

If you are using a custom character set, then you need to perform the following so that JDBC supports the custom character set:
  1. After creating the .nlt and .nlb files as part of the process of creating a custom character set, create .glb files for the newly created character set and also for the lx0boot.nlt file using the following command:

    java -classpath $ORACLE_HOME/jlib/orai18n-tools.jar Ginstall <nlt file>
    
  2. Add the generated files and $ORACLE_HOME/jlib/orai18n-mappings.jar into the classpath environment variable while executing the JDBC code that connects to the database with the custom character set.

For more information about creating a custom character set, refer to Oracle Database Globalization Support Guide.

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

By default, oracle.jdbc.OraclePreparedStatement treats all columns as CHAR. However, since Oracle Database 10g, if you set the system property oracle.jdbc.defaultNChar to true, then JDBC treats all character columns as being national-language. The default value for defaultNChar is false.

To set defaultNChar, you specify the following at the command-line:

java -Doracle.jdbc.defaultNChar=true myApplication

If you prefer, then your application can specify defaultNChar as a connection property and access NCHAR, NVARCHAR2, or NCLOB data. 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, then the database will implicitly convert all CHAR data into NCHAR. This conversion has a substantial performance impact. To avoid this, use the setNString method to access NCHAR and NVARCHAR2 data and setNClob method to access NCLOB data. For example:

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

Note:

You can also use the setObject method to access national character set types, but if the setObject method is used , then the target data type must be specified as Types.NCHAR, Types.NCLOB, Types.NVARCHAR, or Types.LONGNVARCHAR.

Note:

In Oracle Database, SQL strings are converted to the database character set. Therefore you need to keep in mind the following:
  • In Oracle Database 10g release 1 (10.1) and earlier releases, JDBC drivers do not support any NCHAR literal (n'...') containing Unicode characters that are not representable in the database character set. All Unicode characters that are not representable in the database character set get corrupted.

  • If an Oracle Database 10g release 2 (10.2) JDBC driver is connected to an Oracle Database 10g release 2 (10.2) database server, then all NCHAR literals (n'...') are converted to Unicode literals (u'...') and all non-ASCII characters are converted to their corresponding Unicode escape sequence. This is done automatically to prevent data corruption.

  • If an Oracle Database 10g release 2 (10.2) JDBC driver is connected to an Oracle Database 10g release 1 (10.1) or earlier database server, then NCHAR literals (n'...') are not converted and any character that is not representable in the database character set gets corrupted.

New Methods for National Character Set Type Data in JDK 1.6

JDBC 4.0 introduces new JDBC data types, such as NCHAR, NVARCHAR, LONGNVARCHAR, and NCLOB to access the national character set types. 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 Strings to represent NCHAR, NVARCHAR, and LONGNVARCHAR data, and NClob to represent NCLOB values.

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

Note:

The getClob method may be used to return an NClob object since NClob implements Clob.

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

Tip:

If the setObject method is used , then the target data type must be specified as Types.NCHAR, Types.NCLOB, Types.NVARCHAR, or Types.LONGNVARCHAR.