An converter that can convert 16-bit Unicode character sequence to byte sequence in some charset .
The input character sequence is wrapped by {@link java.nio.CharBuffer CharBuffer} and the output character sequence is{@link java.nio.ByteBuffer ByteBuffer}. A encoder instance should be used in following sequence, which is referred to as a encoding operation:
- Invoking the {@link #reset() reset} method to reset the encoder if theencoder has been used;
- Invoking the {@link #encode(CharBuffer,ByteBuffer,boolean) encode}method until the addtional input is not needed, the
endOfInput
parameter must be set to false, the input buffer must be filled and the output buffer must be flushed between invocations; - Invoking the {@link #encode(CharBuffer,ByteBuffer,boolean) encode}method last time, and the the
endOfInput
parameter must be set to true - Invoking the {@link #flush(ByteBuffer) flush} method to flush theoutput.
The {@link #encode(CharBuffer,ByteBuffer,boolean) encode} method willconvert as many characters as possible, and the process won't stop except the input characters has been run out of, the output buffer has been filled or some error has happened. A {@link CoderResult CoderResult} instance will bereturned to indicate the stop reason, and the invoker can identify the result and choose further action, which can include filling the input buffer, flushing the output buffer, recovering from error and trying again.
There are two common encoding errors. One is named as malformed and it is returned when the input content is illegal 16-bit Unicode character sequence, the other is named as unmappable character and occurs when there is a problem mapping the input to a valid byte sequence in the specific charset.
The two errors can be handled in three ways, the default one is to report the error to the invoker by a {@link CoderResult CoderResult} instance, and thealternatives are to ignore it or to replace the erroneous input with the replacement byte array. The replacement byte array is {(byte)'?'} by default and can be changed by invoking {@link #replaceWith(byte[]) replaceWith}method. The invoker of this encoder can choose one way by specifing a {@link CodingErrorAction CodingErrorAction} instance for each error type via{@link #onMalformedInput(CodingErrorAction) onMalformedInput} method and{@link #onUnmappableCharacter(CodingErrorAction) onUnmappableCharacter}method.
This class is abstract class and encapsulate many common operations of encoding process for all charsets. encoder for specific charset should extend this class and need only implement {@link #encodeLoop(CharBuffer,ByteBuffer) encodeLoop} method for basicencoding loop. If a subclass maintains internal state, it should override the {@link #implFlush(ByteBuffer) implFlush} method and{@link #implReset() implReset} method in addition.
This class is not thread-safe.
@see java.nio.charset.Charset
@see java.nio.charset.CharsetDecoder