java.nio.charset
public
abstract
class
java.nio.charset.CharsetEncoder
An converter that can convert 16-bit Unicode character sequence to byte
sequence in some charset .
The input character sequence is wrapped by
CharBuffer and the output character sequence is
ByteBuffer. A encoder instance should be used in
following sequence, which is referred to as a encoding operation:
- Invoking the reset method to reset the encoder if the
encoder has been used;
- Invoking the encode
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;
- Invoking the encode
method last time, and the the
endOfInput
parameter must be set
to true
- Invoking the flush method to flush the
output.
The encode method will
convert 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 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 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 CoderResult instance, and the
alternatives 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 replaceWith
method. The invoker of this encoder can choose one way by specifying a
CodingErrorAction instance for each error type via
onMalformedInput method and
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
encodeLoop method for basic
encoding loop. If a subclass maintains internal state, it should override the
implFlush method and
implReset method in addition.
This class is not thread-safe.
Summary
Protected Constructors
Public Methods
Protected Methods
clone,
equals,
finalize,
getClass,
hashCode,
notify,
notifyAll,
toString,
wait,
wait,
wait
Details
Protected Constructors
protected
CharsetEncoder(Charset cs, float averageBytesPerChar, float maxBytesPerChar)
Construct a new
CharsetEncoder
using given
Charset
, average number and maximum number of bytes
created by this encoder for one input character.
Parameters
cs
| this encoder's Charset , which create this
encoder |
averageBytesPerChar
| average number of bytes created by this encoder for one input
character, must be positive |
maxBytesPerChar
| maximum number of bytes which can be created by this encoder
for one input character, must be positive |
protected
CharsetEncoder(Charset cs, float averageBytesPerChar, float maxBytesPerChar, byte[] replacement)
Construct a new
CharsetEncoder
using given
Charset
, replace byte array, average number and maximum
number of bytes created by this encoder for one input character.
Parameters
cs
| the this encoder's Charset , which create this
encoder |
averageBytesPerChar
| average number of bytes created by this encoder for single
input character, must be positive |
maxBytesPerChar
| maximum number of bytes which can be created by this encoder
for single input character, must be positive |
replacement
| the replacement byte array, cannot be null or empty, its
length cannot larger than maxBytesPerChar , and
must be legal replacement, which can be justified by
isLegalReplacement |
Public Methods
public
final
float
averageBytesPerChar()
get the average number of bytes created by this encoder for single input
character
Returns
- the average number of bytes created by this encoder for single
input character
public
boolean
canEncode(CharSequence sequence)
Check if given
CharSequence
can be encoded by this
encoder.
Note that this method can change the internal status of this encoder, so
it should not be called when another encode process is ongoing, otherwise
it will throw
IllegalStateException
.
This method can be overridden for performance improvement.
Parameters
sequence
| the given CharSequence |
Returns
- true if given
CharSequence
can be encoded by this
encoder
public
boolean
canEncode(char c)
Check if given character can be encoded by this encoder.
Note that this method can change the internal status of this encoder, so
it should not be called when another encode process is ongoing, otherwise
it will throw
IllegalStateException
.
This method can be overridden for performance improvement.
Returns
- true if given character can be encoded by this encoder
Throws
IllegalStateException
| if another encode process is ongoing so that current internal
status is neither RESET or FLUSH
|
public
final
Charset
charset()
Get the
Charset
which creates this encoder.
Returns
- the
Charset
which creates this encoder
Encodes characters starting at the current position of the given input
buffer, and writes the equivalent byte sequence into the given output
buffer from its current position.
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:
- A malformed input result
indicates that some malformed input error encountered, and the erroneous
characters start at the input buffer's position and their number can be
got by result's length. This kind of result
can be returned only if the malformed action is
CodingErrorAction.REPORT.
- CoderResult.UNDERFLOW indicates that
as many characters as possible in the input buffer has been encoded. If
there is no further input and no characters left in the input buffer then
this task is complete. If this is not the case then the client should
call this method again supplying some more input characters.
- CoderResult.OVERFLOW indicates that the
output buffer has been filled, while there are still some characters
remaining in the input buffer. This method should be invoked again with a
non-full output buffer
- A unmappable character
result indicates that some unmappable character error was encountered,
and the erroneous characters start at the input buffer's position and
their number can be got by result's length.
This kind of result can be returned only on
CodingErrorAction.REPORT.
The endOfInput
parameter indicates that if the invoker can
provider further input. This parameter is true if and only if the
characters in current input buffer are all inputs for this encoding
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
encodeLoop method to
implement basic encode logic for specific charset.
Parameters
in
| the input buffer |
out
| the output buffer |
endOfInput
| true if all the input characters have been provided |
Returns
- a
CoderResult
instance indicating the result
This is a facade method for encoding operation.
This method encodes the remaining character sequence of the given
character buffer into a new byte buffer. This method performs a complete
encoding operation, resets at first, then encodes, and flushes at last.
This method should not be invoked if another encode operation is ongoing.
Returns
- a new
ByteBuffer
containing the the bytes produced
by this encoding operation. The buffer's limit will be the
position of last byte in buffer, and the position will be zero
Flush this encoder.
This method will call
implFlush. Some
encoders may need to write some bytes to the output buffer when they have
read all input characters, subclasses can overridden
implFlush to perform writing action.
The maximum number of written bytes won't larger than
out.remaining(). If some encoder want to
write more bytes than output buffer's remaining spaces, then
CoderResult.OVERFLOW
will be returned, and this method
must be called again with a byte buffer has more spaces. Otherwise this
method will return
CoderResult.UNDERFLOW
, which means one
encoding process has been completed successfully.
During the flush, the output buffer's position will be changed
accordingly, while its mark and limit will be intact.
Parameters
out
| the given output buffer |
Returns
CoderResult.UNDERFLOW
or
CoderResult.OVERFLOW
public
boolean
isLegalReplacement(byte[] repl)
Check if the given argument is legal as this encoder's replacement byte
array.
The given byte array is legal if and only if it can be decode into
sixteen bits Unicode characters.
This method can be overridden for performance improvement.
Parameters
repl
| the given byte array to be checked |
Returns
- true if the the given argument is legal as this encoder's
replacement byte array.
Gets this encoder's
CodingErrorAction
when malformed input
occurred during encoding process.
Returns
- this encoder's
CodingErrorAction
when malformed
input occurred during encoding process.
public
final
float
maxBytesPerChar()
Get the maximum number of bytes which can be created by this encoder for
one input character, must be positive
Returns
- the maximum number of bytes which can be created by this encoder
for one input character, must be positive
Set this encoder's action on malformed input error.
This method will call the
implOnMalformedInput
method with the given new action as argument.
Parameters
newAction
| the new action on malformed input error |
Set this encoder's action on unmappable character error.
This method will call the
implOnUnmappableCharacter
method with the given new action as argument.
Parameters
newAction
| the new action on unmappable character error |
public
final
CharsetEncoder
replaceWith(byte[] replacement)
Set new replacement value.
This method first checks the given replacement's validity, then changes
the replacement value, and at last calls
implReplaceWith method with the given
new replacement as argument.
Parameters
replacement
| the replacement byte array, cannot be null or empty, its
length cannot larger than maxBytesPerChar , and
must be legal replacement, which can be justified by
isLegalReplacement(byte[] repl) |
public
final
byte[]
replacement()
Get the replacement byte array, which is never null or empty, and it is
legal
Returns
- the replacement byte array, cannot be null or empty, and it is
legal
Reset this encoder. This method will reset internal status, and then call
implReset()
to reset any status related to specific
charset.
public
CodingErrorAction
unmappableCharacterAction()
Gets this encoder's
CodingErrorAction
when unmappable
character occurred during encoding process.
Returns
- this encoder's
CodingErrorAction
when unmappable
character occurred during encoding process.
Protected Methods
Encode characters into bytes. This method is called by
encode.
This method will implement the essential encoding operation, and it won't
stop encoding until either all the input characters are read, the output
buffer is filled, or some exception encountered. And then it will return
a
CoderResult
object indicating the result of current
encoding operation. The rules to construct the
CoderResult
is same as the
encode.
When exception encountered in the encoding operation, most implementation
of this method will return a relevant result object to
encode method, and some
performance optimized implementation may handle the exception and
implement the error action itself.
The buffers are scanned from their current positions, and their positions
will be modified accordingly, while their marks and limits will be
intact. At most
in.remaining() characters
will be read, and
out.remaining() bytes
will be written.
Note that some implementation may pre-scan the input buffer and return
CoderResult.UNDERFLOW
until it receives sufficient input.
Parameters
in
| the input buffer |
out
| the output buffer |
Returns
- a
CoderResult
instance indicating the result
Flush this encoder. Default implementation does nothing and always return
CoderResult.UNDERFLOW
, and this method can be overridden
if needed.
Returns
CoderResult.UNDERFLOW
or
CoderResult.OVERFLOW
protected
void
implOnMalformedInput(CodingErrorAction newAction)
Notify that this encoder's
CodingErrorAction
specified for
malformed input error has been changed. Default implementation does
nothing, and this method can be overridden if needed.
protected
void
implOnUnmappableCharacter(CodingErrorAction newAction)
Notify that this encoder's
CodingErrorAction
specified for
unmappable character error has been changed. Default implementation does
nothing, and this method can be overridden if needed.
protected
void
implReplaceWith(byte[] newReplacement)
Notify that this encoder's replacement has been changed. Default
implementation does nothing, and this method can be overridden if needed.
Parameters
newReplacement
| the new replacement string
|
protected
void
implReset()
Reset this encoder's charset related state. Default implementation does
nothing, and this method can be overridden if needed.