| Methods Summary |
|---|
| public final float | averageBytesPerChar()Returns the average number of bytes that will be produced for each
character of input. This heuristic value may be used to estimate the size
of the output buffer required for a given input sequence.
return averageBytesPerChar;
|
| private boolean | canEncode(java.nio.CharBuffer cb)
if (state == ST_FLUSHED)
reset();
else if (state != ST_RESET)
throwIllegalStateException(state, ST_CODING);
CodingErrorAction ma = malformedInputAction();
CodingErrorAction ua = unmappableCharacterAction();
try {
onMalformedInput(CodingErrorAction.REPORT);
onUnmappableCharacter(CodingErrorAction.REPORT);
encode(cb);
} catch (CharacterCodingException x) {
return false;
} finally {
onMalformedInput(ma);
onUnmappableCharacter(ua);
reset();
}
return true;
|
| public boolean | canEncode(char c)Tells whether or not this encoder can encode the given character.
This method returns false if the given character is a
surrogate character; such characters can be interpreted only when they
are members of a pair consisting of a high surrogate followed by a low
surrogate. The {@link #canEncode(java.lang.CharSequence)
canEncode(CharSequence)} method may be used to test whether or not a
character sequence can be encoded.
This method may modify this encoder's state; it should therefore not
be invoked if an encoding operation is already in
progress.
The default implementation of this method is not very efficient; it
should generally be overridden to improve performance.
CharBuffer cb = CharBuffer.allocate(1);
cb.put(c);
cb.flip();
return canEncode(cb);
|
| public boolean | canEncode(java.lang.CharSequence cs)Tells whether or not this encoder can encode the given character
sequence.
If this method returns false for a particular character
sequence then more information about why the sequence cannot be encoded
may be obtained by performing a full encoding
operation.
This method may modify this encoder's state; it should therefore not
be invoked if an encoding operation is already in progress.
The default implementation of this method is not very efficient; it
should generally be overridden to improve performance.
CharBuffer cb;
if (cs instanceof CharBuffer)
cb = ((CharBuffer)cs).duplicate();
else
cb = CharBuffer.wrap(cs.toString());
return canEncode(cb);
|
| public final java.nio.charset.Charset | charset()Returns the charset that created this encoder.
return charset;
|
| public final java.nio.charset.CoderResult | encode(java.nio.CharBuffer in, java.nio.ByteBuffer out, boolean endOfInput)Encodes as many characters 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()} characters
will be read and at most {@link Buffer#remaining out.remaining()}
bytes will be written. The buffers' positions will be advanced to
reflect the characters read and the bytes written, but their marks and
limits will not be modified.
In addition to reading characters from the input buffer and writing
bytes 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 encoded. If there is no further
input then the invoker can proceed to the next step of the
encoding 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 encode any more characters.
This method should be invoked again with an output buffer that has
more {@linkplain Buffer#remaining remaining} bytes. This is
typically done by draining any encoded bytes from the output
buffer. A {@link CoderResult#malformedForLength
malformed-input} result indicates that a malformed-input
error has been detected. The malformed characters begin at the input
buffer's (possibly incremented) position; the number of malformed
characters 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 encoder
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 characters that
encode the unmappable character begin at the input buffer's (possibly
incremented) position; the number of such characters 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 encoder 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 encoding
operation then care should be taken to preserve any characters 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 unencoded input will be treated
as being malformed.
This method works by invoking the {@link #encodeLoop encodeLoop}
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 = encodeLoop(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.ByteBuffer | encode(java.nio.CharBuffer in)Convenience method that encodes the remaining content of a single input
character buffer into a newly-allocated byte buffer.
This method implements an entire encoding
operation; that is, it resets this encoder, then it encodes the
characters in the given character buffer, and finally it flushes this
encoder. This method should therefore not be invoked if an encoding
operation is already in progress.
int n = (int)(in.remaining() * averageBytesPerChar());
ByteBuffer out = ByteBuffer.allocate(n);
if ((n == 0) && (in.remaining() == 0))
return out;
reset();
for (;;) {
CoderResult cr = in.hasRemaining() ?
encode(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!
ByteBuffer o = ByteBuffer.allocate(n);
out.flip();
o.put(out);
out = o;
continue;
}
cr.throwException();
}
out.flip();
return out;
|
| protected abstract java.nio.charset.CoderResult | encodeLoop(java.nio.CharBuffer in, java.nio.ByteBuffer out)Encodes one or more characters into one or more bytes.
This method encapsulates the basic encoding loop, encoding as many
characters as possible until it either runs out of input, runs out of room
in the output buffer, or encounters an encoding error. This method is
invoked by the {@link #encode encode} 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()} characters
will be read, and at most {@link Buffer#remaining out.remaining()}
bytes will be written. The buffers' positions will be advanced to
reflect the characters read and the bytes 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 #encode encode}
method. Most implementations of this method will handle encoding errors
by returning an appropriate result object for interpretation by the
{@link #encode encode} 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 final java.nio.charset.CoderResult | flush(java.nio.ByteBuffer out)Flushes this encoder.
Some encoders maintain internal state and may need to write some
final bytes 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()}
bytes 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 encoding
operation.
If this encoder 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.ByteBuffer out)Flushes this encoder.
The default implementation of this method does nothing, and always
returns {@link CoderResult#UNDERFLOW}. This method should be overridden
by encoders that may need to write final bytes 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 encoder's malformed-input action.
The default implementation of this method does nothing. This method
should be overridden by encoders that require notification of changes to
the malformed-input action.
|
| protected void | implOnUnmappableCharacter(java.nio.charset.CodingErrorAction newAction)Reports a change to this encoder's unmappable-character action.
The default implementation of this method does nothing. This method
should be overridden by encoders that require notification of changes to
the unmappable-character action.
|
| protected void | implReplaceWith(byte[] newReplacement)Reports a change to this encoder's replacement value.
The default implementation of this method does nothing. This method
should be overridden by encoders that require notification of changes to
the replacement.
|
| protected void | implReset()Resets this encoder, clearing any charset-specific internal state.
The default implementation of this method does nothing. This method
should be overridden by encoders that maintain internal state.
|
| public boolean | isLegalReplacement(byte[] repl)Tells whether or not the given byte array is a legal replacement value
for this encoder.
A replacement is legal if, and only if, it is a legal sequence of
bytes in this encoder's charset; that is, it must be possible to decode
the replacement into one or more sixteen-bit Unicode characters.
The default implementation of this method is not very efficient; it
should generally be overridden to improve performance.
WeakReference wr = cachedDecoder;
CharsetDecoder dec = null;
if ((wr == null) || ((dec = (CharsetDecoder)wr.get()) == null)) {
dec = charset().newDecoder();
dec.onMalformedInput(CodingErrorAction.REPORT);
dec.onUnmappableCharacter(CodingErrorAction.REPORT);
cachedDecoder = new WeakReference(dec);
} else {
dec.reset();
}
ByteBuffer bb = ByteBuffer.wrap(repl);
CharBuffer cb = CharBuffer.allocate((int)(bb.remaining()
* dec.maxCharsPerByte()));
CoderResult cr = dec.decode(bb, cb, true);
return !cr.isError();
|
| public java.nio.charset.CodingErrorAction | malformedInputAction()Returns this encoder's current action for malformed-input errors.
return malformedInputAction;
|
| public final float | maxBytesPerChar()Returns the maximum number of bytes that will be produced for each
character of input. This value may be used to compute the worst-case size
of the output buffer required for a given input sequence.
return maxBytesPerChar;
|
| public final java.nio.charset.CharsetEncoder | onMalformedInput(java.nio.charset.CodingErrorAction newAction)Changes this encoder'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.CharsetEncoder | onUnmappableCharacter(java.nio.charset.CodingErrorAction newAction)Changes this encoder'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.CharsetEncoder | replaceWith(byte[] newReplacement)Changes this encoder'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 > maxBytesPerChar)
throw new IllegalArgumentException("Replacement too long");
if (!isLegalReplacement(newReplacement))
throw new IllegalArgumentException("Illegal replacement");
this.replacement = newReplacement;
implReplaceWith(newReplacement);
return this;
|
| public final byte[] | replacement()Returns this encoder's replacement value.
return replacement;
|
| public final java.nio.charset.CharsetEncoder | reset()Resets this encoder, 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 encoder's current action for unmappable-character errors.
return unmappableCharacterAction;
|
