com.dalsemi.io
Class CharToByteConverter

java.lang.Object
  |
  +--com.dalsemi.io.CharToByteConverter

Direct Known Subclasses:

CharToByteISO8859_1, CharToByteUTF8

public abstract class CharToByteConverter

extends Object

This class defines an interface to allow conversion of characters to bytes for a particular encoding scheme. Encoding converters should reside in the com.dalsemi.io package.

Many encoding schemes need to take state into account in the conversion process. That is, the conversion to a byte might depend on the character sequence converted before it. To accommodate this, the CharToByteConverter has the ability to remember state between conversions (between calls to convert(). Therefore, the caller should call the flush() method to finalize the conversion and reset the converter's internal state.

Subclasses of this abstract class need to implement getMaxByteCount(), convert(), flush(), and getName().

Programs should not call into a converter directly. A better method of executing character conversions is to use the java.lang.String.getBytes(String) method.

      ...
      String str = new String("this is a test");
      byte[] convertedString = str.getBytes("UTF8");
      ...
 

This will convert the String "this is a test" into a byte array according to the UTF8 encoding scheme.

See Also:

ByteToCharConverter

Constructor Summary

CharToByteConverter()

Method Summary

abstract int	convert(char[] src, int srcStart, int srcEnd, byte[] dst, int dstStart, int dstEnd) Converts the specified char array into a byte array based on this CharToByteConverter's encoding scheme.
abstract int	flush(byte[] buff, int start, int end) Tells the CharToByteConverter to convert any unconverted data it has internally stored.
static CharToByteConverter	getConverter(String name) Dynamically loads a CharToByteConverter for the specified encoding scheme.
static CharToByteConverter	getDefaultConverter() Returns the default CharToByteConverter for the system.
abstract int	getMaxByteCount(char[] forThis, int start, int end) Returns the number of bytes that the specified character sequence will require for encoding.
abstract String	getName() Returns the name of this encoding scheme.

Methods inherited from class java.lang.Object

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

Constructor Detail

CharToByteConverter

public CharToByteConverter()

Method Detail

getConverter

public static CharToByteConverter getConverter(String name)

Dynamically loads a CharToByteConverter for the specified encoding scheme. All converters should be placed in the com.dalsemi.io package, and have class name CharToByteNAME, where NAME is the encoding scheme. For example, the UTF8 CharToByteConverter is called com.dalsemi.io.CharToByteUTF8.

Parameters:

name - the name of the encoding scheme, such as "UTF8"

Returns:

converter for the specified encoding scheme, or null if none could be found

getDefaultConverter

public static CharToByteConverter getDefaultConverter()

Returns the default CharToByteConverter for the system. The name of the default encoding scheme is stored in the system property "file.encoding". This method finds the name of the default encoding scheme, and calls getConverter() with that name as its argument.

Returns:

converter that corresponds to the system's default file encoding property, or null if the converter could not be found

See Also:

getConverter(java.lang.String)

getMaxByteCount

public abstract int getMaxByteCount(char[] forThis,
                                    int start,
                                    int end)

Returns the number of bytes that the specified character sequence will require for encoding. For instance, in UTF8 encoding, a character can be encoded as one, two, or three bytes. This method should always be called before the convert() method. The value returned may not be the actual number of converted bytes that will be produced due to conversion errors, but it will be the maximum that will be produced.

Parameters:

forThis - contains the character sequence that will be encoded to determine the number of bytes required

start - offset into the character array to begin processing

end - ending offset in the character array to end processing. The number of processed characters will then be (end-start).

Returns:

The number of bytes required to encode the specified character sequence.

See Also:

convert(char[],int,int,byte[],int,int)

convert

public abstract int convert(char[] src,
                            int srcStart,
                            int srcEnd,
                            byte[] dst,
                            int dstStart,
                            int dstEnd)
                     throws CharConversionException

Converts the specified char array into a byte array based on this CharToByteConverter's encoding scheme. getMaxByteCount() should always be called first to find out how much room is required in the destination byte array.

Parameters:

src - the same character array passed to getMaxByteCount()

srcStart - the same starting offset as passed to getMaxByteCount()

srcEnd - the same ending offset as passed to getMaxByteCount()

dst - the destination byte array

dstStart - offset to begin storing converted characters in the destination array

dstEnd - the ending location for storing converted characters into the destination array. This argument may usually be ignored, as the algorithm may choose to continue converting characters until finished.

Returns:

number of bytes created and stored from this character sequence

Throws:

CharConversionException - If an illegal character is encountered that cannot be converted

See Also:

getMaxByteCount(char[],int,int), flush(byte[],int,int)

flush

public abstract int flush(byte[] buff,
                          int start,
                          int end)
                   throws CharConversionException

Tells the CharToByteConverter to convert any unconverted data it has internally stored. Some CharToByteConverter's will store state between calls to convert(). Since the converter may be left in an unknown state, the converter should be flushed to notify it that no more input will be received. The converter can handle any unfinished conversions before its output is used.

Parameters:

buff - the destination byte array

start - the next available offset into the destination array

end - offset in the destination array to stop placing data (may be ignored by some algorithms)

Returns:

number of bytes that were stored in the destination array from this call to flush().

Throws:

CharConversionException - if an illegal character is encountered that cannot be converted.

See Also:

convert(char[],int,int,byte[],int,int)

getName

public abstract String getName()

Returns the name of this encoding scheme. For example, "UTF8".

Returns:

the name of this encoding scheme