com.vgrs.xcode.common
Class Native

java.lang.Object
  com.vgrs.xcode.common.Native

public final class Native
extends java.lang.Object

A class that provides algorithms to encode/decode a UTF 16 to/from native characters.
Note: when using JVM 1.4 or greater, the String.getBytes() method can return a java.nio.BufferOverflowException.
(e.g. byte[] b = new String("?").getBytes("ISO2022KR");
It is not possible to catch the java.nio.BufferOverflowException specifically because this won't compile on an older JVM. Instead, the internalDecode() method now catches any Exception and covers it with a XcodeError.NATIVE_INVALID_ENCODING.

Field Summary

static java.lang.String	DOUBLE_UTF8 DOUBLE_UTF8 is not a Java supported encoding, and so requires special processing.
static java.lang.String[]	ENCODINGS Array to stort all Java-Supported native encodings
static java.lang.String	UTF8 Java UTF8 encoding type, used to abstract the Java internals.

Constructor Summary

Native()

Method Summary

static java.util.Map<java.lang.String,java.lang.String>	decode(byte[] aInput) Evaluate the given input against the list of encodings to determine how the input may have been encoded.
static java.lang.String	decode(byte[] aInput, java.lang.String aEncoding) Use the specified native encoding to return the input sequence in UTF16 format.
static java.util.Map<java.lang.String,java.lang.String>	decode(byte[] aInput, java.lang.String[] aEncodings) Decode the input of the indicated encoding types.
static java.util.Set<java.lang.String>	decodeToSet(byte[] aInput) Decode the native string of all encoding types to a HashSet
static java.util.Set<java.lang.String>	decodeToSet(byte[] aInput, java.lang.String[] aEncodings) Decode the native string of indicated encoding types to a HashSet
static java.util.Map<java.lang.String,java.lang.String>	encode(java.lang.String aInput) Encode the input using each of the Java supported encoding types A round-trip check is used to ensure that the encoded data is valid.
static java.lang.String	encode(java.lang.String aInput, java.lang.String aEncoding) Encode the input using the indicated encoding types.
static java.util.Map<java.lang.String,java.lang.String>	encode(java.lang.String aInput, java.lang.String[] aEncodings) Encode the input using the indicated encoding types.
static java.util.Set<java.lang.String>	encodeToSet(java.lang.String aInput) Encode the input using each of the encoding types to a HashSet
static java.util.Set<java.lang.String>	encodeToSet(java.lang.String aInput, java.lang.String[] aEncodings) Encode the input using indicated encoding types to a HashSet
static byte[]	getEncoding(java.lang.String aInput) Retrieve the encoding stored in a Java String.

Methods inherited from class java.lang.Object

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

Field Detail

UTF8

public static final java.lang.String UTF8

Java UTF8 encoding type, used to abstract the Java internals.

See Also:

Constant Field Values

DOUBLE_UTF8

public static final java.lang.String DOUBLE_UTF8

DOUBLE_UTF8 is not a Java supported encoding, and so requires special processing.

See Also:

Constant Field Values

ENCODINGS

public static final java.lang.String[] ENCODINGS

Array to stort all Java-Supported native encodings

Constructor Detail

Native

public Native()

Method Detail

getEncoding

public static byte[] getEncoding(java.lang.String aInput)
                          throws XcodeException

Retrieve the encoding stored in a Java String. In Java, a native encoding is stored as an array of bytes. Unfortunately convenience sometimes dictates that we must use a String to store this data. When creating a String from an encoding, Java places each encoding byte in the low octet of a two byte char, leaving the high byte empty. In order to retrieve an encoding from a String, we will reverse this process, returning only the low bytes from each character in the String. We must also throw an Exception if any high byte is not empty to avoid inaccurate results.

Parameters:

aInput - the String holding the encoded data

Returns:

an array of bytes

Throws:

XcodeException - if the input is null/empty or if any high byte is non-zero

encode

public static java.util.Map<java.lang.String,java.lang.String> encode(java.lang.String aInput)
                                                               throws XcodeException

Encode the input using each of the Java supported encoding types A round-trip check is used to ensure that the encoded data is valid.

Parameters:

aInput - the string to be encoded

Returns:

a HashMap keyed on all encoding types

Throws:

XcodeException - if input is null or empty string.

encode

public static java.lang.String encode(java.lang.String aInput,
                                      java.lang.String aEncoding)
                               throws XcodeException

Encode the input using the indicated encoding types. A round-trip check is used to ensure that the encoded data is valid.

Parameters:

aInput - string to be encoded

aEncoding - string to indicate the encoding type of the output

Returns:

the encoded string

Throws:

XcodeException - if input is null or empty string or if the named charset is not supported

encode

public static java.util.Map<java.lang.String,java.lang.String> encode(java.lang.String aInput,
                                                                      java.lang.String[] aEncodings)
                                                               throws XcodeException

Encode the input using the indicated encoding types. A round-trip check is used to ensure that the encoded data is valid.

Parameters:

aInput - the string to be encoded

aEncodings - indicate the encoding types of the output string

Returns:

a HashMap with keyed on the encoding type

Throws:

XcodeException - if input is null or empty string or if the named charset is not supported

encodeToSet

public static java.util.Set<java.lang.String> encodeToSet(java.lang.String aInput)
                                                   throws XcodeException

Encode the input using each of the encoding types to a HashSet

Parameters:

aInput - the string to be encoded

Returns:

a HashSet of the encoded string

Throws:

XcodeException - if input is null or empty string.

encodeToSet

public static java.util.Set<java.lang.String> encodeToSet(java.lang.String aInput,
                                                          java.lang.String[] aEncodings)
                                                   throws XcodeException

Encode the input using indicated encoding types to a HashSet

Parameters:

aInput - the string to be encoded

aEncodings - encoding types of the decoded string

Returns:

a HashSet of the encoded string

Throws:

XcodeException - if input is null or empty string.

decode

public static java.util.Map<java.lang.String,java.lang.String> decode(byte[] aInput)
                                                               throws XcodeException

Evaluate the given input against the list of encodings to determine how the input may have been encoded. First decode and then re-encode the input using each of the encoding types. Any type for which the round-trip is symmetric is considered a viable encoding, and added to the output list.

Parameters:

aInput - the bytes to be decoded into characters

Returns:

a HashMap with keyed on the encoding type

Throws:

XcodeException - If the named charset is not supported

decode

public static java.lang.String decode(byte[] aInput,
                                      java.lang.String aEncoding)
                               throws XcodeException

Use the specified native encoding to return the input sequence in UTF16 format. This method performs round-trip checking and supports DOUBLE_UTF8.

Parameters:

aInput - the bytes to be decoded

aEncoding - the encoding type to be used in decoding

Returns:

a string of the indicated encoding type

Throws:

XcodeException - if input is null or empty string or if the named charset is not supported

decode

public static java.util.Map<java.lang.String,java.lang.String> decode(byte[] aInput,
                                                                      java.lang.String[] aEncodings)
                                                               throws XcodeException

Decode the input of the indicated encoding types. A round-trip check is used to ensure that the encoded data is valid.

Parameters:

aInput - the native string to be decode

aEncodings - indicate the encoding types of the input string

Returns:

the encoded string

Throws:

XcodeException - if input is null or empty string or if the named charset is not supported

decodeToSet

public static java.util.Set<java.lang.String> decodeToSet(byte[] aInput)
                                                   throws XcodeException

Decode the native string of all encoding types to a HashSet

Parameters:

aInput - the string to be decoded

Returns:

a HashSet of the decoded string

Throws:

XcodeException - if input is null or empty string.

decodeToSet

public static java.util.Set<java.lang.String> decodeToSet(byte[] aInput,
                                                          java.lang.String[] aEncodings)
                                                   throws XcodeException

Decode the native string of indicated encoding types to a HashSet

Parameters:

aInput - the string to be decoded

aEncodings - encoding types of the decoded string

Returns:

a HashSet of the decoded string

Throws:

XcodeException - if input is null or empty string.