com.sybase.jdbcx
Interface CharsetConverter

public abstract interface CharsetConverter

This interface contains methods for doing character-set conversions. Implementing character-set conversion involves trade-offs between performance, correctness, and supportability. Users can choose between a 100% Pure Java solution which is safe but slow and other, faster alternatives.

A more efficient implementation of this interface is com.sybase.utils.TruncationConverterwhich works when character data from the normal ASCII range is used. It should not be used with multibyte characters or special characters from the upper half of 8-bit encoding charsets. TruncationConverter is 100% Pure Java.

Though less efficient, com.sybase.utils.PureConverter should work with any Java VM for all character sets supported by that VM. It is the default implementation for jConnect versions higher than 2, and for Version 2 if the character set requires it. Otherwise, the Version 2 default is the TruncationConverter. PureConverter is 100% Pure Java.

The sample directory contains an example of an "impure" implementation of this interface, SunIoConverter. It relies on the sun.io package, especially classes ByteToCharConverter and CharToByteConverter. It may be used with jConnect instead of the 100% Pure Java implementation.

NOTE: SunIoJavaConverteruses classes from the package sun.io, which may not be present in all Java VMs. Sun is free to change anything in the sun.io package in future releases. If you decide to use this converter or any derivative of it in your application for performance reasons, you may need to make code changes in the future if sun.io changes.

To specify a character-set converter, set the CHARSET_CONVERTER_CLASS connection property to the name of a class implementing this interface.

The jConnect driver negotiates with the database server to find a common character-set encoding for representing all character-making valued data over the network. jConnect uses the specified CharsetConverter to do these conversions.

Method Summary

byte[]	fromUnicode(String fromString) Converts a UCS-2 Unicode string to the given encoding.
void	setEncoding(String encoding) Sets or changes the encoding this converter works on.
String	toUnicode(byte[] fromBytes) Converts a byte array of the given encoding to a UCS-2 Unicode string.

Method Detail

setEncoding

public void setEncoding(String encoding)
                 throws UnsupportedEncodingException

Sets or changes the encoding this converter works on.

Parameters:

encoding - a string specifying the encoding. See Sun's documentation for a list of encoding names.

Throws:

UnsupportedEncodingException - if the current Java VM does not have support for conversions between UCS-2 Unicode and the given encoding

fromUnicode

public byte[] fromUnicode(String fromString)
                   throws CharConversionException

Converts a UCS-2 Unicode string to the given encoding.

Parameters:

fromString - the Unicode string to be converted

Returns:

the converted string as a byte array

Throws:

CharConversionException - if not all the characters can be converted to the target character encoding

toUnicode

public String toUnicode(byte[] fromBytes)
                           throws CharConversionException

Converts a byte array of the given encoding to a UCS-2 Unicode string.

Parameters:

fromBytes - the data to be converted

Returns:

the converted string

Throws:

CharConversionException - if not all the characters can be converted from the source character encoding