|Oracle® Database JDBC Developer's Guide and Reference
10g Release 1 (10.1)
Part Number B10979-01
Oracle's JDBC drivers provide Globalization Support (formerly NLS). Globalization Support allows 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:
For more information on Globalization Support, Globalization Support environment variables, and the character sets that Oracle supports, see "Oracle Character Datatypes Support" and the Oracle Database Globalization Support Guide. See the Oracle Database Reference for more information on the database character set and how it is created.
The basic 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 8 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 your application's
Note:Previous releases depended on 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
The character set extension class files are named in the following format:
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.OraclePreparedStatement treats all columns as
CHAR. To insert Java strings into
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
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();
getUnicodeStream() return values from the database as Java strings and as a stream of Unicode characters, respectively.
getCharacterStream() returns the contents of a
CLOB as a Unicode stream.
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
toString(): This is identical to
getString(), but if the character set is not recognized, then
toString() returns a hexadecimal representation of the
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.