: Class CharToByteConverter

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD