| Methods Summary |
|---|
| public final float | averageCharsPerByte()Returns the average number of characters that will be produced for each
byte of input. This heuristic value may be used to estimate the size
of the output buffer required for a given input sequence.
return averageCharsPerByte;
|
| public final java.nio.charset.Charset | charset()Returns the charset that created this decoder.
return charset;
|
| public final java.nio.charset.CoderResult | decode(java.nio.ByteBuffer in, java.nio.CharBuffer out, boolean endOfInput)Decodes as many bytes as possible from the given input buffer,
writing the results to the given output buffer.
The buffers are read from, and written to, starting at their current
positions. At most {@link Buffer#remaining in.remaining()} bytes
will be read and at most {@link Buffer#remaining out.remaining()}
characters will be written. The buffers' positions will be advanced to
reflect the bytes read and the characters written, but their marks and
limits will not be modified.
In addition to reading bytes from the input buffer and writing
characters to the output buffer, this method returns a {@link CoderResult}
object to describe its reason for termination:
{@link CoderResult#UNDERFLOW} indicates that as much of the
input buffer as possible has been decoded. If there is no further
input then the invoker can proceed to the next step of the
decoding operation. Otherwise this method
should be invoked again with further input. {@link CoderResult#OVERFLOW} indicates that there is
insufficient space in the output buffer to decode any more bytes.
This method should be invoked again with an output buffer that has
more {@linkplain Buffer#remaining remaining} characters. This is
typically done by draining any decoded characters from the output
buffer. A {@link CoderResult#malformedForLength
malformed-input} result indicates that a malformed-input
error has been detected. The malformed bytes begin at the input
buffer's (possibly incremented) position; the number of malformed
bytes may be determined by invoking the result object's {@link
CoderResult#length() length} method. This case applies only if the
{@link #onMalformedInput malformed action} of this decoder
is {@link CodingErrorAction#REPORT}; otherwise the malformed input
will be ignored or replaced, as requested. An {@link CoderResult#unmappableForLength
unmappable-character} result indicates that an
unmappable-character error has been detected. The bytes that
decode the unmappable character begin at the input buffer's (possibly
incremented) position; the number of such bytes may be determined
by invoking the result object's {@link CoderResult#length() length}
method. This case applies only if the {@link #onUnmappableCharacter
unmappable action} of this decoder is {@link
CodingErrorAction#REPORT}; otherwise the unmappable character will be
ignored or replaced, as requested.
In any case, if this method is to be reinvoked in the same decoding
operation then care should be taken to preserve any bytes remaining
in the input buffer so that they are available to the next invocation.
The endOfInput parameter advises this method as to whether
the invoker can provide further input beyond that contained in the given
input buffer. If there is a possibility of providing additional input
then the invoker should pass false for this parameter; if there
is no possibility of providing further input then the invoker should
pass true. It is not erroneous, and in fact it is quite
common, to pass false in one invocation and later discover that
no further input was actually available. It is critical, however, that
the final invocation of this method in a sequence of invocations always
pass true so that any remaining undecoded input will be treated
as being malformed.
This method works by invoking the {@link #decodeLoop decodeLoop}
method, interpreting its results, handling error conditions, and
reinvoking it as necessary.
int newState = endOfInput ? ST_END : ST_CODING;
if ((state != ST_RESET) && (state != ST_CODING)
&& !(endOfInput && (state == ST_END)))
throwIllegalStateException(state, newState);
state = newState;
for (;;) {
CoderResult cr;
try {
cr = decodeLoop(in, out);
} catch (BufferUnderflowException x) {
throw new CoderMalfunctionError(x);
} catch (BufferOverflowException x) {
throw new CoderMalfunctionError(x);
}
if (cr.isOverflow())
return cr;
if (cr.isUnderflow()) {
if (endOfInput && in.hasRemaining()) {
cr = CoderResult.malformedForLength(in.remaining());
// Fall through to malformed-input case
} else {
return cr;
}
}
CodingErrorAction action = null;
if (cr.isMalformed())
action = malformedInputAction;
else if (cr.isUnmappable())
action = unmappableCharacterAction;
else
assert false : cr.toString();
if (action == CodingErrorAction.REPORT)
return cr;
if (action == CodingErrorAction.REPLACE) {
if (out.remaining() < replacement.length())
return CoderResult.OVERFLOW;
out.put(replacement);
}
if ((action == CodingErrorAction.IGNORE)
|| (action == CodingErrorAction.REPLACE)) {
// Skip erroneous input either way
in.position(in.position() + cr.length());
continue;
}
assert false;
}
|
| public final java.nio.CharBuffer | decode(java.nio.ByteBuffer in)Convenience method that decodes the remaining content of a single input
byte buffer into a newly-allocated character buffer.
This method implements an entire decoding
operation; that is, it resets this decoder, then it decodes the
bytes in the given byte buffer, and finally it flushes this
decoder. This method should therefore not be invoked if a decoding
operation is already in progress.
int n = (int)(in.remaining() * averageCharsPerByte());
CharBuffer out = CharBuffer.allocate(n);
if ((n == 0) && (in.remaining() == 0))
return out;
reset();
for (;;) {
CoderResult cr = in.hasRemaining() ?
decode(in, out, true) : CoderResult.UNDERFLOW;
if (cr.isUnderflow())
cr = flush(out);
if (cr.isUnderflow())
break;
if (cr.isOverflow()) {
n = 2*n + 1; // Ensure progress; n might be 0!
CharBuffer o = CharBuffer.allocate(n);
out.flip();
o.put(out);
out = o;
continue;
}
cr.throwException();
}
out.flip();
return out;
|
| protected abstract java.nio.charset.CoderResult | decodeLoop(java.nio.ByteBuffer in, java.nio.CharBuffer out)Decodes one or more bytes into one or more characters.
This method encapsulates the basic decoding loop, decoding as many
bytes as possible until it either runs out of input, runs out of room
in the output buffer, or encounters a decoding error. This method is
invoked by the {@link #decode decode} method, which handles result
interpretation and error recovery.
The buffers are read from, and written to, starting at their current
positions. At most {@link Buffer#remaining in.remaining()} bytes
will be read, and at most {@link Buffer#remaining out.remaining()}
characters will be written. The buffers' positions will be advanced to
reflect the bytes read and the characters written, but their marks and
limits will not be modified.
This method returns a {@link CoderResult} object to describe its
reason for termination, in the same manner as the {@link #decode decode}
method. Most implementations of this method will handle decoding errors
by returning an appropriate result object for interpretation by the
{@link #decode decode} method. An optimized implementation may instead
examine the relevant error action and implement that action itself.
An implementation of this method may perform arbitrary lookahead by
returning {@link CoderResult#UNDERFLOW} until it receives sufficient
input.
|
| public java.nio.charset.Charset | detectedCharset()Retrieves the charset that was detected by this
decoder (optional operation).
If this decoder implements an auto-detecting charset then this
method returns the actual charset once it has been detected. After that
point, this method returns the same value for the duration of the
current decoding operation. If not enough input bytes have yet been
read to determine the actual charset then this method throws an {@link
IllegalStateException}.
The default implementation of this method always throws an {@link
UnsupportedOperationException}; it should be overridden by
auto-detecting decoders to return the appropriate value.
throw new UnsupportedOperationException();
|
| public final java.nio.charset.CoderResult | flush(java.nio.CharBuffer out)Flushes this decoder.
Some decoders maintain internal state and may need to write some
final characters to the output buffer once the overall input sequence has
been read.
Any additional output is written to the output buffer beginning at
its current position. At most {@link Buffer#remaining out.remaining()}
characters will be written. The buffer's position will be advanced
appropriately, but its mark and limit will not be modified.
If this method completes successfully then it returns {@link
CoderResult#UNDERFLOW}. If there is insufficient room in the output
buffer then it returns {@link CoderResult#OVERFLOW}. If this happens
then this method must be invoked again, with an output buffer that has
more room, in order to complete the current decoding
operation.
If this decoder has already been flushed then invoking this method
has no effect.
This method invokes the {@link #implFlush implFlush} method to
perform the actual flushing operation.
if (state == ST_END) {
CoderResult cr = implFlush(out);
if (cr.isUnderflow())
state = ST_FLUSHED;
return cr;
}
if (state != ST_FLUSHED)
throwIllegalStateException(state, ST_FLUSHED);
return CoderResult.UNDERFLOW; // Already flushed
|
| protected java.nio.charset.CoderResult | implFlush(java.nio.CharBuffer out)Flushes this decoder.
The default implementation of this method does nothing, and always
returns {@link CoderResult#UNDERFLOW}. This method should be overridden
by decoders that may need to write final characters to the output buffer
once the entire input sequence has been read.
return CoderResult.UNDERFLOW;
|
| protected void | implOnMalformedInput(java.nio.charset.CodingErrorAction newAction)Reports a change to this decoder's malformed-input action.
The default implementation of this method does nothing. This method
should be overridden by decoders that require notification of changes to
the malformed-input action.
|
| protected void | implOnUnmappableCharacter(java.nio.charset.CodingErrorAction newAction)Reports a change to this decoder's unmappable-character action.
The default implementation of this method does nothing. This method
should be overridden by decoders that require notification of changes to
the unmappable-character action.
|
| protected void | implReplaceWith(java.lang.String newReplacement)Reports a change to this decoder's replacement value.
The default implementation of this method does nothing. This method
should be overridden by decoders that require notification of changes to
the replacement.
|
| protected void | implReset()Resets this decoder, clearing any charset-specific internal state.
The default implementation of this method does nothing. This method
should be overridden by decoders that maintain internal state.
|
| public boolean | isAutoDetecting()Tells whether or not this decoder implements an auto-detecting charset.
The default implementation of this method always returns
false; it should be overridden by auto-detecting decoders to
return true.
return false;
|
| public boolean | isCharsetDetected()Tells whether or not this decoder has yet detected a
charset (optional operation).
If this decoder implements an auto-detecting charset then at a
single point during a decoding operation this method may start returning
true to indicate that a specific charset has been detected in
the input byte sequence. Once this occurs, the {@link #detectedCharset
detectedCharset} method may be invoked to retrieve the detected charset.
That this method returns false does not imply that no bytes
have yet been decoded. Some auto-detecting decoders are capable of
decoding some, or even all, of an input byte sequence without fixing on
a particular charset.
The default implementation of this method always throws an {@link
UnsupportedOperationException}; it should be overridden by
auto-detecting decoders to return true once the input charset
has been determined.
throw new UnsupportedOperationException();
|
| public java.nio.charset.CodingErrorAction | malformedInputAction()Returns this decoder's current action for malformed-input errors.
return malformedInputAction;
|
| public final float | maxCharsPerByte()Returns the maximum number of characters that will be produced for each
byte of input. This value may be used to compute the worst-case size
of the output buffer required for a given input sequence.
return maxCharsPerByte;
|
| public final java.nio.charset.CharsetDecoder | onMalformedInput(java.nio.charset.CodingErrorAction newAction)Changes this decoder's action for malformed-input errors.
This method invokes the {@link #implOnMalformedInput
implOnMalformedInput} method, passing the new action.
if (newAction == null)
throw new IllegalArgumentException("Null action");
malformedInputAction = newAction;
implOnMalformedInput(newAction);
return this;
|
| public final java.nio.charset.CharsetDecoder | onUnmappableCharacter(java.nio.charset.CodingErrorAction newAction)Changes this decoder's action for unmappable-character errors.
This method invokes the {@link #implOnUnmappableCharacter
implOnUnmappableCharacter} method, passing the new action.
if (newAction == null)
throw new IllegalArgumentException("Null action");
unmappableCharacterAction = newAction;
implOnUnmappableCharacter(newAction);
return this;
|
| public final java.nio.charset.CharsetDecoder | replaceWith(java.lang.String newReplacement)Changes this decoder's replacement value.
This method invokes the {@link #implReplaceWith implReplaceWith}
method, passing the new replacement, after checking that the new
replacement is acceptable.
if (newReplacement == null)
throw new IllegalArgumentException("Null replacement");
int len = newReplacement.length();
if (len == 0)
throw new IllegalArgumentException("Empty replacement");
if (len > maxCharsPerByte)
throw new IllegalArgumentException("Replacement too long");
this.replacement = newReplacement;
implReplaceWith(newReplacement);
return this;
|
| public final java.lang.String | replacement()Returns this decoder's replacement value.
return replacement;
|
| public final java.nio.charset.CharsetDecoder | reset()Resets this decoder, clearing any internal state.
This method resets charset-independent state and also invokes the
{@link #implReset() implReset} method in order to perform any
charset-specific reset actions.
implReset();
state = ST_RESET;
return this;
|
| private void | throwIllegalStateException(int from, int to)
throw new IllegalStateException("Current state = " + stateNames[from]
+ ", new state = " + stateNames[to]);
|
| public java.nio.charset.CodingErrorAction | unmappableCharacterAction()Returns this decoder's current action for unmappable-character errors.
return unmappableCharacterAction;
|
