International Features of the JDBC Driver

The internationalization features of the Microsoft SQL Server JDBC Driver include the following:

  • Support for a fully localized experience in the same languages as SQL Server.

  • Support for the Java language conversions for locale sensitive SQL Server data.

  • Support for international languages, regardless of operating system.

Character data in Java is handled as Unicode by default; the Java String object represents Unicode character data. In the JDBC driver, the only exception to this rule is the ASCII stream getter and setter methods, which are special cases because they use byte streams with the implicit assumption of single well-known code pages (ASCII).

In addition, the JDBC driver provides the sendStringParametersAsUnicode connection string property. This property can be used to specify that prepared parameters for character data are sent as ASCII or Multi-byte Character Set (MBCS) instead of Unicode. For more information about the sendStringParametersAsUnicode connection string property, see Setting the Connection Properties.

Driver Incoming Conversions

Unicode text data coming from the server does not have to be converted. It is passed directly as Unicode. Non-Unicode data coming from the server is converted from the code page for the data, at the database or column level, to Unicode. The JDBC driver uses the Java Virtual Machine (JVM) conversion routines to perform these conversions. These conversions are performed on all typed String and Character stream getter methods.

If the JVM does not have the proper code page support for the data from the database, the JDBC driver throws a "XXX codepage not supported by the Java environment" exception. To solve this problem, you should install the full international character support required for that JVM. For an example, see the Supported Encodings documentation on Sun Microsystems Web site.

Driver Outgoing Conversions

Character data going from the driver to the server can be ASCII or Unicode. For example, the new JDBC 4.0 national character methods, such as setNString, setNCharacterStream, and setNClob methods of SQLServerPreparedStatement and SQLServerCallableStatement classes, always send their parameter values to the server in Unicode.

On the other hand, the non-national character API methods, such as setString, setCharacterStream, and setClob methods of SQLServerPreparedStatement and SQLServerCallableStatement classes send their values to the server in Unicode only when the sendStringParametersAsUnicode property is set to "true", which is the default value.

For optimal performance with CHAR, VARCHAR or LONGVARCHAR type of non-Unicode parameters, set the sendStringParametersAsUnicode connection string property to "false" and use the non-national character methods.

For date, time, and currencies, all formatting with localized data is performed at the Java language level using the Locale object; and the various formatting methods for Date, Calendar, and Number data types. In the rare case where the JDBC driver must pass along locale sensitive data in a localized format, the proper formatter is used with the default JVM locale.

The JDBC Driver 3.0 supports all the collations supported by SQL Server 2000, SQL Server 2005, and the new collations or new versions of Windows collation names introduced in SQL Server 2008.

For more information on the collations, see Collation and Unicode Support and Windows Collation Name (Transact-SQL) in SQL Server Books Online.