CharsetEncoder (moe.ios.core API)

java.lang.Object
- java.nio.charset.CharsetEncoder

```
public abstract class CharsetEncoder
extends Object
```
Transforms a sequence of 16-bit Java characters to a byte sequence in some encoding.
The input character sequence is a CharBuffer and the output byte sequence is a ByteBuffer.
Use encode(CharBuffer) to encode an entire CharBuffer to a new ByteBuffer, or encode(CharBuffer, ByteBuffer, boolean) for more control. When using the latter method, the entire operation proceeds as follows:
1. Invoke reset() to reset the encoder if this instance has been used before.
2. Invoke encode with the endOfInput parameter set to false until additional input is not needed (as signaled by the return value). The input buffer must be filled and the output buffer must be flushed between invocations.
  The encode method will convert as many characters as possible, and the process won't stop until the input buffer has been exhausted, the output buffer has been filled, or an error has occurred. A CoderResult instance will be returned to indicate the current state. The caller should fill the input buffer, flush the output buffer, or recovering from an error and try again, accordingly.
3. Invoke encode for the last time with endOfInput set to true.
4. Invoke flush(ByteBuffer) to flush remaining output.
There are two classes of encoding error: malformed input signifies that the input character sequence is not legal, while unmappable character signifies that the input is legal but cannot be mapped to a byte sequence (because the charset cannot represent the character, for example).
Errors can be handled in three ways. The default is to report the error to the caller. The alternatives are to ignore the error or replace the problematic input with the byte sequence returned by replacement(). The disposition for each of the two kinds of error can be set independently using the onMalformedInput(java.nio.charset.CodingErrorAction) and onUnmappableCharacter(java.nio.charset.CodingErrorAction) methods.
The default replacement bytes depend on the charset but can be overridden using the replaceWith(byte[]) 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 internal state, it should also override the implFlush and implReset methods.
This class is not thread-safe.
See Also:

Charset, CharsetDecoder

Constructor Summary

Constructors
Modifier	Constructor and Description
`protected`	`CharsetEncoder(Charset cs, float averageBytesPerChar, float maxBytesPerChar)` Constructs a new `CharsetEncoder` using the given parameters and the replacement byte array `{ (byte) '?' }`.
`protected`	`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.

Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`float`	`averageBytesPerChar()` Returns the average number of bytes created by this encoder for a single input character.
`boolean`	`canEncode(char c)` Tests whether the given character can be encoded by this encoder.
`boolean`	`canEncode(CharSequence sequence)` Tests whether the given `CharSequence` can be encoded by this encoder.
`Charset`	`charset()` Returns the `Charset` which this encoder uses.
`ByteBuffer`	`encode(CharBuffer in)` This is a facade method for the encoding operation.
`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.
`protected abstract CoderResult`	`encodeLoop(CharBuffer in, ByteBuffer out)` Encodes characters into bytes.
`CoderResult`	`flush(ByteBuffer out)` Flushes this encoder.
`protected CoderResult`	`implFlush(ByteBuffer out)` Flushes this encoder.
`protected void`	`implOnMalformedInput(CodingErrorAction newAction)` Notifies that this encoder's `CodingErrorAction` specified for malformed input error has been changed.
`protected void`	`implOnUnmappableCharacter(CodingErrorAction newAction)` Notifies that this encoder's `CodingErrorAction` specified for unmappable character error has been changed.
`protected void`	`implReplaceWith(byte[] newReplacement)` Notifies that this encoder's replacement has been changed.
`protected void`	`implReset()` Resets this encoder's charset related state.
`boolean`	`isLegalReplacement(byte[] replacement)` Tests whether the given argument is legal as this encoder's replacement byte array.
`CodingErrorAction`	`malformedInputAction()` Returns this encoder's `CodingErrorAction` when a malformed input error occurred during the encoding process.
`float`	`maxBytesPerChar()` Returns the maximum number of bytes which can be created by this encoder for one input character, must be positive.
`CharsetEncoder`	`onMalformedInput(CodingErrorAction newAction)` Sets this encoder's action on malformed input error.
`CharsetEncoder`	`onUnmappableCharacter(CodingErrorAction newAction)` Sets this encoder's action on unmappable character error.
`byte[]`	`replacement()` Returns the replacement byte array, which is never null or empty.
`CharsetEncoder`	`replaceWith(byte[] replacement)` Sets the new replacement value.
`CharsetEncoder`	`reset()` Resets this encoder.
`CodingErrorAction`	`unmappableCharacterAction()` Returns this encoder's `CodingErrorAction` when unmappable character occurred during encoding process.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - CharsetEncoder
```
protected CharsetEncoder(Charset cs,
                         float averageBytesPerChar,
                         float maxBytesPerChar)
```
    Constructs a new CharsetEncoder using the given parameters and the replacement byte array { (byte) '?' }.
  - CharsetEncoder
```
protected 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.
    
    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.
- Method Detail
  - averageBytesPerChar
```
public final float averageBytesPerChar()
```
    Returns the average number of bytes created by this encoder for a single input character.
  - canEncode
```
public boolean canEncode(char c)
```
    Tests whether the given character can be encoded by this encoder.
    Note that this method may change the internal state of this encoder, so it should not be called when another encoding process is ongoing, otherwise it will throw an IllegalStateException.
    
    Throws:
    
    IllegalStateException - if another encode process is ongoing.
  - canEncode
```
public boolean canEncode(CharSequence sequence)
```
    Tests whether the given CharSequence can be encoded by this encoder.
    Note that this method may change the internal state of this encoder, so it should not be called when another encode process is ongoing, otherwise it will throw an IllegalStateException.
    
    Throws:
    
    IllegalStateException - if another encode process is ongoing.
  - charset
```
public final Charset charset()
```
    Returns the Charset which this encoder uses.
  - encode
```
public final ByteBuffer encode(CharBuffer in)
                        throws CharacterCodingException
```
    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.
  - encode
```
public 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.
    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.
  - encodeLoop
```
protected abstract CoderResult encodeLoop(CharBuffer in,
                                          ByteBuffer out)
```
    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 subclasses may handle the exception and implement the error action themselves.
    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.
  - flush
```
public final CoderResult flush(ByteBuffer out)
```
    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 override implFlush to perform any writes that are required at the end of the output sequence, such as footers and other metadata.
    The maximum number of written bytes won't be larger than out.remaining(). If the encoder wants to write more bytes than the output buffer's available remaining space, then it will return CoderResult.OVERFLOW. This method must then be called again with a byte buffer that has free space.
    If the encoder was asked to flush its output when its input is incomplete, (because it ends with an unpaired surrogate, say) it may return CodeResult.MALFORMED.
    In all other cases the encoder will return CoderResult.UNDERFLOW, which signifies that all the input so far has been successfully encoded.
    During the flush, the output buffer's position will be changed accordingly, while its mark and limit will be intact.
    This method is a no-op if the encoder has already been flushed.
    
    Parameters:
    
    out - the given output buffer.
    
    Returns:
    
    CoderResult.UNDERFLOW or CoderResult.OVERFLOW or CoderResult.MALFORMED
    
    Throws:
    
    IllegalStateException - if this encoder isn't already flushed or at end of input.
  - implFlush
```
protected CoderResult implFlush(ByteBuffer out)
```
    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.
  - implOnMalformedInput
```
protected void implOnMalformedInput(CodingErrorAction newAction)
```
    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.
  - implOnUnmappableCharacter
```
protected void implOnUnmappableCharacter(CodingErrorAction newAction)
```
    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.
  - implReplaceWith
```
protected void implReplaceWith(byte[] newReplacement)
```
    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.
  - implReset
```
protected void implReset()
```
    Resets this encoder's charset related state. The default implementation does nothing; this method can be overridden if needed.
  - isLegalReplacement
```
public boolean isLegalReplacement(byte[] replacement)
```
    Tests whether 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 decoded into characters.
  - malformedInputAction
```
public CodingErrorAction malformedInputAction()
```
    Returns this encoder's CodingErrorAction when a malformed input error occurred during the encoding process.
  - maxBytesPerChar
```
public final float maxBytesPerChar()
```
    Returns the maximum number of bytes which can be created by this encoder for one input character, must be positive.
  - onMalformedInput
```
public final CharsetEncoder onMalformedInput(CodingErrorAction newAction)
```
    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.
  - onUnmappableCharacter
```
public final CharsetEncoder onUnmappableCharacter(CodingErrorAction newAction)
```
    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.
  - replacement
```
public final byte[] replacement()
```
    Returns the replacement byte array, which is never null or empty.
  - replaceWith
```
public final CharsetEncoder replaceWith(byte[] replacement)
```
    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[] replacement).
    
    Returns:
    
    this encoder.
    
    Throws:
    
    IllegalArgumentException - if the given replacement cannot satisfy the requirement mentioned above.
  - reset
```
public final CharsetEncoder reset()
```
    Resets this encoder. This method will reset the internal state and then calls implReset() to reset any state related to the specific charset.
  - unmappableCharacterAction
```
public CodingErrorAction unmappableCharacterAction()
```
    Returns this encoder's CodingErrorAction when unmappable character occurred during encoding process.

Class CharsetEncoder

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

CharsetEncoder

CharsetEncoder

Method Detail

averageBytesPerChar

canEncode

canEncode

charset

encode

encode

encodeLoop

flush

implFlush

implOnMalformedInput

implOnUnmappableCharacter

implReplaceWith

implReset

isLegalReplacement

malformedInputAction

maxBytesPerChar

onMalformedInput

onUnmappableCharacter

replacement

replaceWith

reset

unmappableCharacterAction