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:
The basic Java Archive (JAR) files,
ojdbc14.jar, contain all the necessary classes to provide complete globalization support for:
Oracle character sets for
CLOB data that is not being retrieved or inserted as a data member of an Oracle object or collection type.
VARCHAR data members of object and collection for the character sets
To use any other character sets in
VARCHAR data members of objects or collections, you must include
orai18n.jar in the
CLASSPATH of your application.
Note:Previous releases depended on the
nls_charset12.zipfile. This file is now obsolete.
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
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.
oracle.jdbc.OraclePreparedStatement treats all columns as
CHAR. To insert Java
String values into
NCLOB columns, applications had to call
setFormOfUse on each national-language column. However, in Oracle Database 10g, 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.
defaultNChar, you specify the following at the command-line:
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
NCLOB data without calling
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, then 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 column 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();
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.