oracle.jdbc.driver
Class DBConversion

java.lang.Object
  oracle.jdbc.driver.DBConversion

public class DBConversion

extends java.lang.Object

Database conversion class.

This class holds information about the character sets used by the driver and the database server. It provides the necessary conversion rountines to convert between Java Strings and character bytes passed via the driver.

The character set used at the driver is determined by the low-layer driver. This class handles these character sets: UCS2, ASCII, ISO_LATIN_1, AL24UTFFSS,UTF8 and AL32UTF8.

Since both AL24UTFFSS and UTF8 use the same UTF8 encoding scheme, the two character sets are handled the same way in this class.

Since:

8.1.6

See Also:

CharacterSet

Field Summary

static short	AL16UTF16_CHARSET
static short	AL24UTFFSS_CHARSET
static short	AL32UTF8_CHARSET
static short	ASCII_CHARSET
static java.lang.String	BUILD_DATE
static short	DBCS_CHARSET
static boolean	DO_CONVERSION_WITH_REPLACEMENT
static short	ISO_LATIN_1_CHARSET
static short	ORACLE8_PROD_VERSION
static boolean	PRIVATE_TRACE
static boolean	TRACE
static short	UCS2_CHARSET
static short	UTF8_CHARSET

Constructor Summary

DBConversion(short svrCharSet, short driverCharSet, short svrNCharSet)
Constructor method.

Method Summary

int	_getMaxCharbyteSize(short cs)
byte[]	asciiBytesToCHARBytes(byte[] bytes) Convert an Ascii byte array into a Driver byte array.
static int	asciiBytesToJavaChars(byte[] bytes, int nbytes, char[] chars) Convert 8-bit ascii character bytes into a Java char array.
int	CHARBytesToJavaChars(byte[] bytes, int byteOffset, char[] chars, int charOffset, int[] nbytes, int charSize)
java.lang.String	CharBytesToString(byte[] bytes, int nbytes) Convert driver character bytes to a string.
java.io.InputStream	CharsToStream(char[] javachars, int offset, int len, int conversion)
java.io.Reader	ConvertCharacterStream(java.io.InputStream stream, int conversion)
java.io.Reader	ConvertCharacterStream(java.io.InputStream stream, int conversion, short form_of_use)
java.io.InputStream	ConvertStream(java.io.InputStream stream, int conversion)
java.io.InputStream	ConvertStream(java.io.InputStream stream, int conversion, int max_bytes)
java.io.InputStream	ConvertStream(java.io.Reader stream, int conversion, int max_chars, short form_of_use)
static short	findDriverCharSet(short svrCharSet, short oraVersion) Find the appropriate driver character set to use.
short	getDbCharSet() Obtain the database character set id.
CharacterSet	getDbCharSetObj() Obtain the database character set object.
short	getDriverCharSet() Obtain the id of the character set used in the driver.
CharacterSet	getDriverCharSetObj() Obtain the Driver character set object.
CharacterSet	getDriverNCharSetObj()
int	getMaxCharbyteSize()
int	getMaxNCharbyteSize()
short	getNCharSet() Obtain the database national character set id.
static int	getUtfLen(char c) Return the UTF8 representation length for the given Java character.
static boolean	isCharSetMultibyte(short charSet) Check if a character set is mutlibyte.
boolean	IsNCharFixedWith()
boolean	isUcs2CharSet()
static int	javaCharsToAsciiBytes(char[] chars, int nchars, byte[] bytes) Convert Java char array into an ascii byte array.
int	javaCharsToCHARBytes(char[] chars, int nchars, byte[] bytes)
int	javaCharsToCHARBytes(char[] chars, int charOffset, byte[] bytes, int byteOffset, int nchars)
int	javaCharsToDbCsBytes(char[] chars, int nchars, byte[] bytes) Convert a Java character array into a byte array in database character set.
int	javaCharsToDbCsBytes(char[] chars, int charOffset, byte[] bytes, int byteOffset, int nchars) Convert a Java character array into a byte array in database character set.
int	javaCharsToNCHARBytes(char[] chars, int nchars, byte[] bytes)
int	javaCharsToNCHARBytes(char[] chars, int charOffset, byte[] bytes, int byteOffset, int nchars)
static int	javaCharsToUcs2Bytes(char[] chars, int nchars, byte[] bytes) Convert a Java character array into a UCS-2 byte array.
static int	javaCharsToUcs2Bytes(char[] chars, int charOffset, byte[] bytes, int byteOffset, int nchars) Convert a Java character array into a UCS-2 byte array.
int	NCHARBytesToJavaChars(byte[] bytes, int byteOffset, char[] chars, int charOffset, int[] nbytes, int charSize) Same as CHARBytesToJavaChars but the charset of the input byte is the National charset.
java.lang.String	NCharBytesToString(byte[] bytes, int nbytes)
static int	RAWBytesToHexChars(byte[] bytes, int nbytes, char[] chars)
static byte[]	stringToAsciiBytes(java.lang.String str) Convert string into its Ascii byte array representation.
byte[]	StringToCharBytes(java.lang.String str) Convert string into a byte array representing characters used at the driver.
static byte[]	stringToDriverCharBytes(java.lang.String str, short charset) Convert string into a byte array representing characters in one of the Driver character sets.
static int	ucs2BytesToJavaChars(byte[] bytes, int nbytes, char[] chars) Convert a UCS-2 byte array into a Java character array.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DO_CONVERSION_WITH_REPLACEMENT

public static final boolean DO_CONVERSION_WITH_REPLACEMENT

See Also:

Constant Field Values

ORACLE8_PROD_VERSION

public static final short ORACLE8_PROD_VERSION

See Also:

Constant Field Values

DBCS_CHARSET

public static final short DBCS_CHARSET

See Also:

Constant Field Values

UCS2_CHARSET

public static final short UCS2_CHARSET

See Also:

Constant Field Values

ASCII_CHARSET

public static final short ASCII_CHARSET

See Also:

Constant Field Values

ISO_LATIN_1_CHARSET

public static final short ISO_LATIN_1_CHARSET

See Also:

Constant Field Values

AL24UTFFSS_CHARSET

public static final short AL24UTFFSS_CHARSET

See Also:

Constant Field Values

UTF8_CHARSET

public static final short UTF8_CHARSET

See Also:

Constant Field Values

AL32UTF8_CHARSET

public static final short AL32UTF8_CHARSET

See Also:

Constant Field Values

AL16UTF16_CHARSET

public static final short AL16UTF16_CHARSET

See Also:

Constant Field Values

TRACE

public static final boolean TRACE

See Also:

Constant Field Values

PRIVATE_TRACE

public static final boolean PRIVATE_TRACE

See Also:

Constant Field Values

BUILD_DATE

public static final java.lang.String BUILD_DATE

See Also:

Constant Field Values

Constructor Detail

DBConversion

public DBConversion(short svrCharSet,
                    short driverCharSet,
                    short svrNCharSet)
             throws java.sql.SQLException

Constructor method.

Parameters:

svrCharSet - character set id of the character set used in the database server. (Since the Oracle server supports a large number of character sets, no check is performed on this parameter.)

driverCharSet - character set id of the character set used in the driver. These are the possible values: UCS2_CHARSET, ASCII_CHARSET, ISO_LATIN_1_CHARSET, AL24UTFFSS_CHARSET, UTF8_CHARSET.

Throws:

java.sql.SQLException - if driverCharSet is invalid.

Method Detail

getDbCharSet

public short getDbCharSet()

Obtain the database character set id.

Returns:

the requested database character set id.

getNCharSet

public short getNCharSet()

Obtain the database national character set id.

Returns:

the requested database character set id.

IsNCharFixedWith

public boolean IsNCharFixedWith()

getDriverCharSet

public short getDriverCharSet()

Obtain the id of the character set used in the driver.

Returns:

the requested Driver character set id.

getDbCharSetObj

public CharacterSet getDbCharSetObj()

Obtain the database character set object.

Returns:

the requested database character set object.

getDriverCharSetObj

public CharacterSet getDriverCharSetObj()

Obtain the Driver character set object.

Returns:

the requested Driver character set object.

getDriverNCharSetObj

public CharacterSet getDriverNCharSetObj()

findDriverCharSet

public static final short findDriverCharSet(short svrCharSet,
                                            short oraVersion)

Find the appropriate driver character set to use.

This static method is intended to be used by the Thin driver to find the appropriate driver character set to construct a DBConversion object.

Parameters:

svrCharSet - character set id of the character set used in the database server.

oraVersion - Oracle version.

Returns:

the character set id of the appropriate driver character set.

stringToDriverCharBytes

public static final byte[] stringToDriverCharBytes(java.lang.String str,
                                                   short charset)
                                            throws java.sql.SQLException

Convert string into a byte array representing characters in one of the Driver character sets.

Note: DBCS_CHARSET is not supported by this function

Parameters:

str - input string to be converted.

charset - character set id of the character set used in the driver. These are the possible values: UCS2_CHARSET, ASCII_CHARSET, ISO_LATIN_1_CHARSET, AL24UTFFSS_CHARSET, UTF8_CHARSET, AL32UTF8_CHARSET.

Returns:

byte array representation of the input string.

Throws:

java.sql.SQLException - if charset is invalid.

StringToCharBytes

public byte[] StringToCharBytes(java.lang.String str)
                         throws java.sql.SQLException

Convert string into a byte array representing characters used at the driver.

Parameters:

str - input string to be converted.

Returns:

Driver character byte array representation of the input string.

Throws:

java.sql.SQLException - if a Jdbc internal error occurred.

CharBytesToString

public java.lang.String CharBytesToString(byte[] bytes,
                                          int nbytes)
                                   throws java.sql.SQLException

Convert driver character bytes to a string.

Parameters:

bytes - input character byte array.

nbytes - length of input character byte array to be converted.

Returns:

the resulting string.

Throws:

java.sql.SQLException - if errors occurred.

NCharBytesToString

public java.lang.String NCharBytesToString(byte[] bytes,
                                           int nbytes)
                                    throws java.sql.SQLException

Throws:

java.sql.SQLException

javaCharsToCHARBytes

public int javaCharsToCHARBytes(char[] chars,
                                int nchars,
                                byte[] bytes)
                         throws java.sql.SQLException

Throws:

java.sql.SQLException

javaCharsToCHARBytes

public int javaCharsToCHARBytes(char[] chars,
                                int charOffset,
                                byte[] bytes,
                                int byteOffset,
                                int nchars)
                         throws java.sql.SQLException

Throws:

java.sql.SQLException

javaCharsToNCHARBytes

public int javaCharsToNCHARBytes(char[] chars,
                                 int nchars,
                                 byte[] bytes)
                          throws java.sql.SQLException

Throws:

java.sql.SQLException

javaCharsToNCHARBytes

public int javaCharsToNCHARBytes(char[] chars,
                                 int charOffset,
                                 byte[] bytes,
                                 int byteOffset,
                                 int nchars)
                          throws java.sql.SQLException

Throws:

java.sql.SQLException

CHARBytesToJavaChars

public int CHARBytesToJavaChars(byte[] bytes,
                                int byteOffset,
                                char[] chars,
                                int charOffset,
                                int[] nbytes,
                                int charSize)
                         throws java.sql.SQLException

Throws:

java.sql.SQLException

NCHARBytesToJavaChars

public int NCHARBytesToJavaChars(byte[] bytes,
                                 int byteOffset,
                                 char[] chars,
                                 int charOffset,
                                 int[] nbytes,
                                 int charSize)
                          throws java.sql.SQLException

Same as CHARBytesToJavaChars but the charset of the input byte is the National charset.

Throws:

java.sql.SQLException

asciiBytesToCHARBytes

public byte[] asciiBytesToCHARBytes(byte[] bytes)

Convert an Ascii byte array into a Driver byte array.

Parameters:

bytes - input Ascii byte arary.

Returns:

the result byte array.

javaCharsToDbCsBytes

public int javaCharsToDbCsBytes(char[] chars,
                                int nchars,
                                byte[] bytes)
                         throws java.sql.SQLException

Convert a Java character array into a byte array in database character set.

Parameters:

chars - input Java character array.

bytes - output byte array. (Buffer is allocated by the calling routine.)

Returns:

the number of bytes written into bytes[].

Throws:

java.sql.SQLException - if the input is invalid.

javaCharsToDbCsBytes

public int javaCharsToDbCsBytes(char[] chars,
                                int charOffset,
                                byte[] bytes,
                                int byteOffset,
                                int nchars)
                         throws java.sql.SQLException

Convert a Java character array into a byte array in database character set.

Parameters:

chars - input Java character array.

charOffset - offset in the char array

bytes - output byte array. (Buffer is allocated by the calling routine.)

byteOffset - offset in the byte array

nchars - number of characters in chars[] to convert.

Returns:

the number of bytes written into bytes[].

Throws:

java.sql.SQLException - if the input is invalid.

javaCharsToUcs2Bytes

public static final int javaCharsToUcs2Bytes(char[] chars,
                                             int nchars,
                                             byte[] bytes)
                                      throws java.sql.SQLException

Convert a Java character array into a UCS-2 byte array.

Parameters:

chars - input Java character array.

nchars - number of characters in chars[] to convert.

bytes - output byte array. (Buffer is allocated by the calling routine.)

Returns:

the number of bytes written into bytes[].

Throws:

java.sql.SQLException - if the input is invalid.

javaCharsToUcs2Bytes

public static final int javaCharsToUcs2Bytes(char[] chars,
                                             int charOffset,
                                             byte[] bytes,
                                             int byteOffset,
                                             int nchars)
                                      throws java.sql.SQLException

Convert a Java character array into a UCS-2 byte array.

Parameters:

chars - input Java character array.

charOffset - offset in the char array

bytes - output byte array. (Buffer is allocated by the calling routine.)

byteOffset - offset in the byte array

nchars - number of characters in chars[] to convert.

Returns:

the number of bytes written into bytes[].

Throws:

java.sql.SQLException - if the input is invalid.

ucs2BytesToJavaChars

public static final int ucs2BytesToJavaChars(byte[] bytes,
                                             int nbytes,
                                             char[] chars)
                                      throws java.sql.SQLException

Convert a UCS-2 byte array into a Java character array.

Parameters:

bytes - input byte array.

nbytes - number of bytes in bytes[] to convert.

chars - input Java character array. (Buffer is allocated by the calling routine.)

Returns:

the number of bytes written into chars[].

Throws:

java.sql.SQLException - if the input is invalid.

stringToAsciiBytes

public static final byte[] stringToAsciiBytes(java.lang.String str)

Convert string into its Ascii byte array representation.

Parameters:

str - input string to be converted.

Returns:

byte array representation of the input string.

asciiBytesToJavaChars

public static final int asciiBytesToJavaChars(byte[] bytes,
                                              int nbytes,
                                              char[] chars)
                                       throws java.sql.SQLException

Convert 8-bit ascii character bytes into a Java char array.

Parameters:

bytes - input character bytes.

nbytes - number of bytes to be converted.

chars - output Java char array (buffer allocated by calling rountine).

Returns:

the number of bytes written into chars[].

Throws:

java.sql.SQLException - if input is invalid.

javaCharsToAsciiBytes

public static final int javaCharsToAsciiBytes(char[] chars,
                                              int nchars,
                                              byte[] bytes)
                                       throws java.sql.SQLException

Convert Java char array into an ascii byte array.

Parameters:

chars - input Java character array.

nchars - number of Java characters to be converted.

bytes - output ascii byte array (buffer allocated by calling rountine).

Returns:

the number of bytes written into bytes[].

Throws:

java.sql.SQLException - if the input is invalid.

isCharSetMultibyte

public static final boolean isCharSetMultibyte(short charSet)

Check if a character set is mutlibyte.

Parameters:

charSet - input character set identifier.

Returns:

true if the input character set is multibyte, or false if not.

getMaxCharbyteSize

public int getMaxCharbyteSize()

getMaxNCharbyteSize

public int getMaxNCharbyteSize()

_getMaxCharbyteSize

public int _getMaxCharbyteSize(short cs)

isUcs2CharSet

public boolean isUcs2CharSet()

RAWBytesToHexChars

public static final int RAWBytesToHexChars(byte[] bytes,
                                           int nbytes,
                                           char[] chars)

ConvertStream

public java.io.InputStream ConvertStream(java.io.InputStream stream,
                                         int conversion)

ConvertStream

public java.io.InputStream ConvertStream(java.io.InputStream stream,
                                         int conversion,
                                         int max_bytes)

ConvertStream

public java.io.InputStream ConvertStream(java.io.Reader stream,
                                         int conversion,
                                         int max_chars,
                                         short form_of_use)

ConvertCharacterStream

public java.io.Reader ConvertCharacterStream(java.io.InputStream stream,
                                             int conversion)
                                      throws java.sql.SQLException

Throws:

java.sql.SQLException

ConvertCharacterStream

public java.io.Reader ConvertCharacterStream(java.io.InputStream stream,
                                             int conversion,
                                             short form_of_use)
                                      throws java.sql.SQLException

Throws:

java.sql.SQLException

CharsToStream

public java.io.InputStream CharsToStream(char[] javachars,
                                         int offset,
                                         int len,
                                         int conversion)
                                  throws java.sql.SQLException

Throws:

java.sql.SQLException

getUtfLen

public static final int getUtfLen(char c)

Return the UTF8 representation length for the given Java character. Note this method can not be used on a AL32UTF8 character.

Parameters:

c - is a Java character.

Returns:

the length in UTF bytes.