An converter that can convert bytes sequence in some charset to 16-bit Unicode character sequence.
The input byte sequence is wrapped by {@link java.nio.ByteBuffer ByteBuffer}and the output character sequence is {@link java.nio.CharBuffer CharBuffer}. A decoder instance should be used in following sequence, which is referred to as a decoding operation:
- Invoking the {@link #reset() reset} method to reset the decoder if thedecoder has been used;
- Invoking the {@link #decode(ByteBuffer,CharBuffer,boolean) decode}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 #decode(ByteBuffer,CharBuffer,boolean) decode}method last time, and the the
endOfInput
parameter must be set to true - Invoking the {@link #flush(CharBuffer) flush} method to flush theoutput.
The {@link #decode(ByteBuffer,CharBuffer,boolean) decode} method willconvert as many bytes as possible, and the process won't stop except the input bytes 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 decoding errors. One is named as malformed and it is returned when the input byte sequence is illegal for current specific charset, the other is named as unmappable character and it is returned when a problem occurs mapping a legal input byte sequence to its Unicode character equivalent.
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 string. The replacement string is "\uFFFD" by default and can be changed by invoking {@link #replaceWith(String) replaceWith} method. Theinvoker of this decoder 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 decoding process for all charsets. Decoder for specific charset should extend this class and need only implement {@link #decodeLoop(ByteBuffer,CharBuffer) decodeLoop} method for basicdecoding loop. If a subclass maintains internal state, it should override the {@link #implFlush(CharBuffer) implFlush} method and{@link #implReset() implReset} method in addition.
This class is not thread-safe.
@see java.nio.charset.Charset
@see java.nio.charset.CharsetEncoder