public abstract class

CharsetEncoder

extends Object
java.lang.Object
   ↳ java.nio.charset.CharsetEncoder

Class Overview

A converter that can converts a 16-bit Unicode character sequence to a byte sequence in some charset.

The input character sequence is wrapped by a CharBuffer and the output character sequence is a ByteBuffer. An encoder instance should be used in the following sequence, which is referred to as a encoding operation:

  1. invoking the reset method to reset the encoder if the encoder has been used;
  2. 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;
  3. invoking the encode method for the last time and the endOfInput parameter must be set to true
  4. invoking the flush method to flush the output.

The encode method will convert as many characters as possible, and the process won't stop until the input characters have run out, 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 includes filling the input buffer, flushing the output buffer or recovering from an error and trying again.

There are two common encoding errors. One is named malformed and it is returned when the input content is an illegal 16-bit Unicode character sequence, the other is named unmappable character and occurs when there is a problem mapping the input to a valid byte sequence in the specified charset.

Both 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 '?' by default and can be changed by invoking the replaceWith method. The invoker of this encoder can choose one way by specifying a CodingErrorAction instance for each error type via the onMalformedInput method and the onUnmappableCharacter method.

This class is abstract and encapsulates many common operations of the encoding process for all charsets. Encoders for a specific charset should extend this class and need only to implement the encodeLoop method for basic encoding. If a subclass maintains an internal state, it should override the implFlush method and the implReset method in addition.

This class is not thread-safe.

Summary

Protected Constructors
CharsetEncoder(Charset cs, float averageBytesPerChar, float maxBytesPerChar)
Constructs a new CharsetEncoder using the given Charset, average number and maximum number of bytes created by this encoder for one input character.
CharsetEncoder(Charset cs, float averageBytesPerChar, float maxBytesPerChar, byte[] replacement)
Constructs a new CharsetEncoder using the given Charset, replacement byte array, average number and maximum number of bytes created by this encoder for one input character.
Public Methods
final float averageBytesPerChar()
Gets the average number of bytes created by this encoder for a single input character.
boolean canEncode(CharSequence sequence)
Checks if a given CharSequence can be encoded by this encoder.
boolean canEncode(char c)
Checks if the given character can be encoded by this encoder.
final Charset charset()
Gets the Charset which this encoder uses.
final CoderResult encode(CharBuffer in, ByteBuffer out, boolean endOfInput)
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.
final ByteBuffer encode(CharBuffer in)
This is a facade method for the encoding operation.
final CoderResult flush(ByteBuffer out)
Flushes this encoder.
boolean isLegalReplacement(byte[] repl)
Checks if the given argument is legal as this encoder's replacement byte array.
CodingErrorAction malformedInputAction()
Gets this encoder's CodingErrorAction when a malformed input error occurred during the encoding process.
final float maxBytesPerChar()
Gets the maximum number of bytes which can be created by this encoder for one input character, must be positive.
final CharsetEncoder onMalformedInput(CodingErrorAction newAction)
Sets this encoder's action on malformed input error.
final CharsetEncoder onUnmappableCharacter(CodingErrorAction newAction)
Sets this encoder's action on unmappable character error.
final CharsetEncoder replaceWith(byte[] replacement)
Sets the new replacement value.
final byte[] replacement()
Gets the replacement byte array, which is never null or empty.
final CharsetEncoder reset()
Resets this encoder.
CodingErrorAction unmappableCharacterAction()
Gets this encoder's CodingErrorAction when unmappable character occurred during encoding process.
Protected Methods
abstract CoderResult encodeLoop(CharBuffer in, ByteBuffer out)
Encodes characters into bytes.
CoderResult implFlush(ByteBuffer out)
Flushes this encoder.
void implOnMalformedInput(CodingErrorAction newAction)
Notifies that this encoder's CodingErrorAction specified for malformed input error has been changed.
void implOnUnmappableCharacter(CodingErrorAction newAction)
Notifies that this encoder's CodingErrorAction specified for unmappable character error has been changed.
void implReplaceWith(byte[] newReplacement)
Notifies that this encoder's replacement has been changed.
void implReset()
Resets this encoder's charset related state.
[Expand]
Inherited Methods
From class java.lang.Object

Protected Constructors

protected CharsetEncoder (Charset cs, float averageBytesPerChar, float maxBytesPerChar)

Since: API Level 1

Constructs a new CharsetEncoder using the given Charset, average number and maximum number of bytes created by this encoder for one input character.

Parameters
cs the Charset to be used by 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.
Throws
IllegalArgumentException if maxBytesPerChar or averageBytesPerChar is negative.

protected CharsetEncoder (Charset cs, float averageBytesPerChar, float maxBytesPerChar, byte[] replacement)

Since: API Level 1

Constructs a new CharsetEncoder using the given Charset, replacement byte array, average number and maximum number of bytes created by this encoder for one input character.

Parameters
cs the Charset to be used by this encoder.
averageBytesPerChar average number of bytes created by this encoder for one single input character, must be positive.
maxBytesPerChar maximum number of bytes which can be created by this encoder for one single input character, must be positive.
replacement the replacement byte array, cannot be null or empty, its length cannot be larger than maxBytesPerChar, and must be a legal replacement, which can be justified by isLegalReplacement.
Throws
IllegalArgumentException if any parameters are invalid.

Public Methods

public final float averageBytesPerChar ()

Since: API Level 1

Gets the average number of bytes created by this encoder for a single input character.

Returns
  • the average number of bytes created by this encoder for a single input character.

public boolean canEncode (CharSequence sequence)

Since: API Level 1

Checks if a 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 an IllegalStateException. This method can be overridden for performance improvement.

Parameters
sequence the given CharSequence.
Returns
  • true if the given CharSequence can be encoded by this encoder.
Throws
IllegalStateException if current internal status is neither RESET or FLUSH.

public boolean canEncode (char c)

Since: API Level 1

Checks if the 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 encoding process is ongoing, otherwise it will throw an IllegalStateException.

This method can be overridden for performance improvement.

Parameters
c the given encoder.
Returns
  • true if given character can be encoded by this encoder.
Throws
IllegalStateException if another encode process is ongoing so that the current internal status is neither RESET or FLUSH.

public final Charset charset ()

Since: API Level 1

Gets the Charset which this encoder uses.

Returns
  • the Charset which this encoder uses.

public final CoderResult encode (CharBuffer in, ByteBuffer out, boolean endOfInput)

Since: API Level 1

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 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 if the malformed action is CodingErrorAction.REPORT.
  • CoderResult.UNDERFLOW indicates that as many characters as possible in the input buffer have 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 if the invoker can provider further input. This parameter is true if and only if the characters in the current input buffer are all inputs for this encoding operation. Note that it is common and won't cause an error if the invoker sets false and then has no more input available, while it may cause an error if the invoker always sets true in several consecutive invocations. This would make the remaining input to be treated as malformed input. input.

This method invokes the encodeLoop method to implement the basic encode logic for a 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.
Throws
IllegalStateException if the encoding operation has already started or no more input is needed in this encoding process.
CoderMalfunctionError If the encodeLoop method threw an BufferUnderflowException or BufferUnderflowException.

public final ByteBuffer encode (CharBuffer in)

Since: API Level 1

This is a facade method for the 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.

Parameters
in the input buffer.
Returns
  • a new ByteBuffer containing the bytes produced by this encoding operation. The buffer's limit will be the position of the last byte in the buffer, and the position will be zero.
Throws
IllegalStateException if another encoding operation is ongoing.
MalformedInputException if an illegal input character sequence for this charset is encountered, and the action for malformed error is CodingErrorAction.REPORT
UnmappableCharacterException if a legal but unmappable input character sequence for this charset is encountered, and the action for unmappable character error is CodingErrorAction.REPORT. Unmappable means the Unicode character sequence at the input buffer's current position cannot be mapped to a equivalent byte sequence.
CharacterCodingException if other exception happened during the encode operation.

public final CoderResult flush (ByteBuffer out)

Since: API Level 1

Flushes 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 wants to write more bytes than the output buffer's available remaining space, then CoderResult.OVERFLOW will be returned, and this method must be called again with a byte buffer that has free space. 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.
Throws
IllegalStateException if this encoder hasn't read all input characters during one encoding process, which means neither after calling encode(CharBuffer) nor after calling encode(CharBuffer, ByteBuffer, boolean) with true for the last boolean parameter.

public boolean isLegalReplacement (byte[] repl)

Since: API Level 1

Checks 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.

public CodingErrorAction malformedInputAction ()

Since: API Level 1

Gets this encoder's CodingErrorAction when a malformed input error occurred during the encoding process.

Returns
  • this encoder's CodingErrorAction when a malformed input error occurred during the encoding process.

public final float maxBytesPerChar ()

Since: API Level 1

Gets 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.

public final CharsetEncoder onMalformedInput (CodingErrorAction newAction)

Since: API Level 1

Sets 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.
Returns
  • this encoder.
Throws
IllegalArgumentException if the given newAction is null.

public final CharsetEncoder onUnmappableCharacter (CodingErrorAction newAction)

Since: API Level 1

Sets 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.
Returns
  • this encoder.
Throws
IllegalArgumentException if the given newAction is null.

public final CharsetEncoder replaceWith (byte[] replacement)

Since: API Level 1

Sets the new replacement value. This method first checks the given replacement's validity, then changes the replacement value and finally calls the implReplaceWith method with the given new replacement as argument.

Parameters
replacement the replacement byte array, cannot be null or empty, its length cannot be larger than maxBytesPerChar, and it must be legal replacement, which can be justified by calling isLegalReplacement(byte[] repl).
Returns
  • this encoder.
Throws
IllegalArgumentException if the given replacement cannot satisfy the requirement mentioned above.

public final byte[] replacement ()

Since: API Level 1

Gets the replacement byte array, which is never null or empty.

Returns
  • the replacement byte array, cannot be null or empty.

public final CharsetEncoder reset ()

Since: API Level 1

Resets this encoder. This method will reset the internal status and then calla implReset() to reset any status related to the specific charset.

Returns
  • this encoder.

public CodingErrorAction unmappableCharacterAction ()

Since: API Level 1

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

protected abstract CoderResult encodeLoop (CharBuffer in, ByteBuffer out)

Since: API Level 1

Encodes 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 is encountered. Then it will return a CoderResult object indicating the result of the current encoding operation. The rule to construct the CoderResult is the same as for encode. When an exception is encountered in the encoding operation, most implementations of this method will return a relevant result object to the 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 implementations 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.

protected CoderResult implFlush (ByteBuffer out)

Since: API Level 1

Flushes this encoder. The default implementation does nothing and always returns CoderResult.UNDERFLOW; this method can be overridden if needed.

Parameters
out the output buffer.
Returns
  • CoderResult.UNDERFLOW or CoderResult.OVERFLOW.

protected void implOnMalformedInput (CodingErrorAction newAction)

Since: API Level 1

Notifies that this encoder's CodingErrorAction specified for malformed input error has been changed. The default implementation does nothing; this method can be overridden if needed.

Parameters
newAction the new action.

protected void implOnUnmappableCharacter (CodingErrorAction newAction)

Since: API Level 1

Notifies that this encoder's CodingErrorAction specified for unmappable character error has been changed. The default implementation does nothing; this method can be overridden if needed.

Parameters
newAction the new action.

protected void implReplaceWith (byte[] newReplacement)

Since: API Level 1

Notifies that this encoder's replacement has been changed. The default implementation does nothing; this method can be overridden if needed.

Parameters
newReplacement the new replacement string.

protected void implReset ()

Since: API Level 1

Resets this encoder's charset related state. The default implementation does nothing; this method can be overridden if needed.