Java Doc for CharsetDecoder.java in  » Apache-Harmony-Java-SE » java-package » java » nio » charset » Java Source Code / Java DocumentationJava Source Code and Java Documentation

The input byte sequence is wrapped by java.nio.ByteBuffer ByteBuffer and the output character sequence is java.nio.CharBuffer CharBuffer . A decoder instance should be used in following sequence, which is referred to as a decoding operation:

1. Invoking the CharsetDecoder.reset() reset method to reset the decoder if the decoder has been used;
2. Invoking the CharsetDecoder.decode(ByteBuffer,CharBuffer,boolean) decode method until the additional 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;
3. Invoking the CharsetDecoder.decode(ByteBuffer,CharBuffer,boolean) decode method last time, and the the endOfInput parameter must be set to true
4. Invoking the CharsetDecoder.flush(CharBuffer) flush method to flush the output.

The CharsetDecoder.decode(ByteBuffer,CharBuffer,boolean) decode method will convert 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 CoderResult CoderResult instance will be returned 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 CoderResult CoderResult instance, and the alternatives 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 CharsetDecoder.replaceWith(String) replaceWith method. The invoker of this decoder can choose one way by specifying a CodingErrorAction CodingErrorAction instance for each error type via CharsetDecoder.onMalformedInput(CodingErrorAction) onMalformedInput method and CharsetDecoder.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 CharsetDecoder.decodeLoop(ByteBuffer,CharBuffer) decodeLoop method for basic decoding loop. If a subclass maintains internal state, it should override the CharsetDecoder.implFlush(CharBuffer) implFlush method and CharsetDecoder.implReset() implReset method in addition.

This class is not thread-safe.

This method decodes the remaining byte sequence of the given byte buffer into a new character buffer.

The buffers' position will be changed with the reading and writing operation, but their limits and marks will be kept intact.

A CoderResult instance will be returned according to following rules:

• CoderResult.OVERFLOW CoderResult.OVERFLOW indicates that even though not all of the input has been processed, the buffer the output is being written to has reached its capacity.

If implementing an auto-detecting charset, then this decoder returns the detected charset from this method when it is available.

If this decoder implements an auto-detecting charset, then this method may start to return true during decoding operation to indicate that a charset has been detected in the input bytes and that the charset can be retrieved by invoking CharsetDecoder.detectedCharset() detectedCharset method.

Note that a decoder that implements an auto-detecting charset may still succeed in decoding a portion of the given input even when it is unable to detect the charset.

This method decodes the remaining byte sequence of the given byte buffer into a new character buffer. This method performs a complete decoding operation, resets at first, then decodes, and flushes at last.

This method should not be invoked if another decode operation is ongoing.

The buffers' position will be changed with the reading and writing operation, but their limits and marks will be kept intact.

A CoderResult instance will be returned according to following rules:

• CoderResult.OVERFLOW CoderResult.OVERFLOW indicates that even though not all of the input has been processed, the buffer the output is being written to has reached its capacity. In the event of this code being returned this method should be called once more with an out argument that has not already been filled.
• CoderResult.UNDERFLOW CoderResult.UNDERFLOW indicates that as many bytes as possible in the input buffer have been decoded. If there is no further input and no remaining bytes in the input buffer then this operation may be regarded as complete. Otherwise, this method should be called once more with additional input.
• A CoderResult.malformedForLength(int) malformed input result indicates that some malformed input error encountered, and the erroneous bytes start at the input buffer's position and their number can be got by result's CoderResult.length length . This kind of result can be returned only if the malformed action is CodingErrorAction.REPORT CodingErrorAction.REPORT .
• A CoderResult.unmappableForLength(int) unmappable character result indicates that some unmappable character error encountered, and the erroneous bytes start at the input buffer's position and their number can be got by result's CoderResult.length length . This kind of result can be returned only if the unmappable character action is CodingErrorAction.REPORT CodingErrorAction.REPORT .

The endOfInput parameter indicates that if the invoker can provider further input. This parameter is true if and only if the bytes in current input buffer are all inputs for this decoding operation. Note that it is common and won't cause error that the invoker sets false and then finds no more input available; while it may cause error that the invoker always sets true in several consecutive invocations so that any remaining input will be treated as malformed input.

This method invokes CharsetDecoder.decodeLoop(ByteBuffer,CharBuffer) decodeLoop method to implement basic decode logic for specific charset.

If implementing an auto-detecting charset, then this decoder returns the detected charset from this method when it is available. The returned charset will be the same for the rest of the decode operation.

If insufficient bytes have been read to determine the charset, IllegalStateException will be thrown.

The default implementation always throws UnsupportedOperationException, so it should be overridden by subclass if needed.

If this decoder implements an auto-detecting charset, then this method may start to return true during decoding operation to indicate that a charset has been detected in the input bytes and that the charset can be retrieved by invoking CharsetDecoder.detectedCharset() detectedCharset method.

Note that a decoder that implements an auto-detecting charset may still succeed in decoding a portion of the given input even when it is unable to detect the charset. For this reason users should be aware that a false return value does not indicate that no decoding took place.

The default implementation always throws an UnsupportedOperationException; it should be overridden by subclass if needed.