java.nio.charset
類別 CharsetEncoder

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

public abstract class CharsetEncoder
extends Object

能夠把 16 位 Unicode 字元序列轉換成特定 charset 中位元組序列的引擎。

輸入字元序列由字元緩衝區或一系列這樣的緩衝區提供。輸出位元組序列寫入位元組緩衝區或一系列這樣的緩衝區。應該始終通過下面的方法調用序列使用編碼器，下文稱為編碼操作：

1. 通過 reset 方法重置編碼器，除非以前未使用過；

2. 只要有其他的輸入資料就應零次或多次調用 encode，為 endOfInput 參數傳遞 false，在調用之間填充輸入緩衝區並刷新輸出緩衝區。

3. 最後時刻調用一次 encode 方法，為 endOfInput 參數傳遞 true；然後

4. 調用 flush 方法，這樣編碼器能夠將任何內部狀態刷新到輸出緩衝區。

每次調用 encode 方法將編碼盡可能多的輸入緩衝區中的字元，將得到的位元組寫入輸出緩衝區。當需要更多的輸入時、輸出緩衝區沒有足夠的空間或出現編碼錯誤時，encode 方法返回。在每種情況下都返回用於描述終止原因的 CoderResult 物件。調用者可根據相應的狀況檢查此物件並填充輸入緩衝區、刷新輸出緩衝區或嘗試從編碼錯誤中恢復，並再次進行嘗試。

有兩種常規編碼錯誤型別。如果輸入字元序列不是合法的 16 位 Unicode 序列，那麼就認為輸入是錯誤的。如果輸入字元序列是合法的，但不能映射為給定 charset 中的有效位元組序列，那麼就出現了不可映射的字元。

如何處理編碼錯誤取決於為該錯誤型別所請求的操作，在 CodingErrorAction 類別的實例中描述了該型別的錯誤。可能的錯誤操作是忽略錯誤的輸入、通過返回的 CoderResult 物件將錯誤報告給調用者，或者用當前的替換 byte 陣列值替換錯誤的輸入。 該替換值初始設置為編碼器的預設替換值，這個值通常（但並非總是）具有初始值 { (byte)'?' }； 可通過 replaceWith 方法更改此值。

對於錯誤輸入和不可映射的字元錯誤的預設操作是報告它們。可通過 onMalformedInput 方法更改針對錯誤輸入的錯誤操作；可通過 onUnmappableCharacter 方法更改不可映射的字元錯誤的操作。

此類別設計用來處理編碼過程中的許多細節問題，包括錯誤操作的實作。一個特定 charset 的編碼器是此類別的具體子類別，它只需要實作抽象的 encodeLoop 方法，這個方法封裝了基本的編碼循環。另外，維護內部狀態的子類別應該覆寫 implFlush 和 implReset 方法。

此類別的實例用於多個共時執行緒是不安全的。

從以下版本開始：

1.4

另請參見：

ByteBuffer, CharBuffer, Charset, CharsetDecoder

建構子摘要

protected	CharsetEncoder(Charset cs, float averageBytesPerChar, float maxBytesPerChar) 初始化新的編碼器。
protected	CharsetEncoder(Charset cs, float averageBytesPerChar, float maxBytesPerChar, byte[] replacement) 初始化新的編碼器。

方法摘要

float	averageBytesPerChar() 返回為每個輸入字元產生的平均位元組數。
boolean	canEncode(char c) 通知此編碼器是否能夠編碼給定的字元。
boolean	canEncode(CharSequence cs) 通過此編碼器是否能夠編碼給定的字元序列。
Charset	charset() 返回創建此編碼器的 charset。
ByteBuffer	encode(CharBuffer in) 把單個輸入字元緩衝區的剩餘內容編碼到新分派的位元組緩衝區的便捷方法。
CoderResult	encode(CharBuffer in, ByteBuffer out, boolean endOfInput) 從給定輸入緩衝區中編碼盡可能多的字元，把結果寫入給定的輸出緩衝區。
protected abstract CoderResult	encodeLoop(CharBuffer in, ByteBuffer out) 將一個或多個字元編碼為一個或多個位元組。
CoderResult	flush(ByteBuffer out) 刷新此編碼器。
protected CoderResult	implFlush(ByteBuffer out) 刷新此編碼器。
protected void	implOnMalformedInput(CodingErrorAction newAction) 報告此編碼器的錯誤輸入操作的更改。
protected void	implOnUnmappableCharacter(CodingErrorAction newAction) 報告此編碼器的不可映射的字元操作的更改。
protected void	implReplaceWith(byte[] newReplacement) 報告此編碼器替換值的更改。
protected void	implReset() 重置此編碼器，清除所有特定於 charset 的內部狀態。
boolean	isLegalReplacement(byte[] repl) 通知給定的 byte 陣列是否為此編碼器的合法替換值。
CodingErrorAction	malformedInputAction() 返回此編碼器對錯誤輸入錯誤的當前操作。
float	maxBytesPerChar() 返回為每個輸入字元產生的最大位元組數。
CharsetEncoder	onMalformedInput(CodingErrorAction newAction) 更改此編碼器對錯誤輸入錯誤的操作。
CharsetEncoder	onUnmappableCharacter(CodingErrorAction newAction) 更改此編碼器對不可映射的字元錯誤的操作。
byte[]	replacement() 返回此編碼器的替換值。
CharsetEncoder	replaceWith(byte[] newReplacement) 更改此編碼器的替換值。
CharsetEncoder	reset() 重置此編碼器，清除所有內部狀態。
CodingErrorAction	unmappableCharacterAction() 返回此編碼器對不可映射的字元錯誤的當前操作。

從類別 java.lang.Object 繼承的方法

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

建構子詳細資訊

CharsetEncoder

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

初始化新的編碼器。新編碼器具有給定的每字元多少個位元組 (chars-per-byte) 值和替換值。

參數：

averageBytesPerChar - 一個正的 float 值，指示為每個輸入字元所產生的位元組數

maxBytesPerChar - 一個正的 float 值，指示為每個輸入字元所產生的最大位元組數

replacement - 初始替換值；一定不能為 null、必須具有非零長度、必須小於 maxBytesPerChar，並且必須為 legal

拋出：

IllegalArgumentException - 如果參數有關的前提不成立

CharsetEncoder

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

初始化新的編碼器。新編碼器具有給定的每字元多少個位元組值，它的替換值為 byte 陣列 { (byte)'?' }。

參數：

averageBytesPerChar - 一個正的 float 值，指示為每個輸入字元所產生的位元組數

maxBytesPerChar - 一個正的 float 值，指示為每個輸入字元所產生的最大位元組數

拋出：

IllegalArgumentException - 如果參數有關的前提不成立

方法詳細資訊

charset

public final Charset charset()

返回創建此編碼器的 charset。

返回：

此編碼器的 charset

replacement

public final byte[] replacement()

返回此編碼器的替換值。

返回：

此編碼器的當前替換值，它永遠不能為 null，也不能為空

replaceWith

public final CharsetEncoder replaceWith(byte[] newReplacement)

更改此編碼器的替換值。

此方法調用 implReplaceWith 方法，檢查新的替換值是可接受的後，傳遞該新替換值。

參數：

newReplacement - 新的替換值；一定不能為 null、必須具有非零長度、必須小於 maxBytesPerChar 所返回的值，並且必須為 legal

返回：

此編碼器

拋出：

IllegalArgumentException - 如果參數有關的前提不成立

implReplaceWith

protected void implReplaceWith(byte[] newReplacement)

報告此編碼器替換值的更改。

此方法的預設實作不執行任何操作。需要通知替換值更改的編碼器應該覆寫此方法。

參數：

newReplacement -

isLegalReplacement

public boolean isLegalReplacement(byte[] repl)

通知給定的 byte 陣列是否為此編碼器的合法替換值。

當且僅當替換值是此編碼器的 charset 中合法的位元組序列時才是合法的；也就是說，能夠把替換值解碼成一個或多個 16 位 Unicode 字元。

此方法的預設實作效率不是很高；為了提高性能通常應該覆寫它。

參數：

repl - 要被測試的 byte 陣列

返回：

當且僅當給定的 byte 陣列是此編碼器的合法替換值時才返回 true

malformedInputAction

public CodingErrorAction malformedInputAction()

返回此編碼器對錯誤輸入錯誤的當前操作。

返回：

當前的錯誤輸入操作，它永遠不能為 null

onMalformedInput

public final CharsetEncoder onMalformedInput(CodingErrorAction newAction)

更改此編碼器對錯誤輸入錯誤的操作。

此方法調用 implOnMalformedInput 方法，傳遞新的操作。

參數：

newAction - 新的操作；一定不能為 null

返回：

此編碼器

拋出：

IllegalArgumentException - 如果參數有關的前提不成立

implOnMalformedInput

protected void implOnMalformedInput(CodingErrorAction newAction)

報告此編碼器的錯誤輸入操作的更改。

此方法的預設實作不執行任何操作。需要通知錯誤輸入操作更改的編碼器應該覆寫此方法。

unmappableCharacterAction

public CodingErrorAction unmappableCharacterAction()

返回此編碼器對不可映射的字元錯誤的當前操作。

返回：

當前的不可映射的字元操作，它永遠不能為 null

onUnmappableCharacter

public final CharsetEncoder onUnmappableCharacter(CodingErrorAction newAction)

更改此編碼器對不可映射的字元錯誤的操作。

此方法調用 implOnUnmappableCharacter 方法，傳遞新的操作。

參數：

newAction - 新的操作；一定不能為 null

返回：

此編碼器

拋出：

IllegalArgumentException - 如果參數有關的前提不成立

implOnUnmappableCharacter

protected void implOnUnmappableCharacter(CodingErrorAction newAction)

報告此編碼器的不可映射的字元操作的更改。

此方法的預設實作不執行任何操作。需要通知不可映射的字元操作更改的編碼器應該覆寫此方法。

averageBytesPerChar

public final float averageBytesPerChar()

返回為每個輸入字元產生的平均位元組數。此試探值可用來估算給定輸入序列所需的輸出緩衝區大小。

返回：

每個輸入字元產生的平均位元組數

maxBytesPerChar

public final float maxBytesPerChar()

返回為每個輸入字元產生的最大位元組數。此值可用來計算給定輸入序列最壞情況下所需的輸出緩衝區大小。

返回：

每個輸入字元產生的最大位元組數

encode

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

從給定輸入緩衝區中編碼盡可能多的字元，把結果寫入給定的輸出緩衝區。

應該從各緩衝區的當前位置開始進行讀取和寫入。最多將讀取 in.remaining() 個字元，最多將寫入 out.remaining() 個位元組。前移緩衝區的位置，以反映字元讀取和寫入位元組，但是其標記和界限將無法修改。

除了從輸入緩衝區讀取字元和向輸出緩衝區寫入位元組，此方法還返回一個 CoderResult 物件來描述它終止的原因：

• CoderResult.UNDERFLOW 指示已編碼盡可能多的輸入緩衝區。如果沒有進一步的輸入，則調用者可以進行到編碼操作的下一個步驟。否則，應該使用進一步的輸入再次調用此方法。

• CoderResult.OVERFLOW 指示該輸出緩衝區中沒有足夠空間來編碼任何更多字元。應該使用具有更多剩餘位元組的輸出緩衝區再次調用此方法。這通常是通過排空輸出緩衝區的所有編碼位元組來完成的。

• CoderResult#malformedForLengthmalformed-input 結果指示已檢測到錯誤輸入錯誤。錯誤的字元起始於輸入緩衝區（可能向前增加）的位置；錯誤字元數可以通過調用結果物件的 length 方法來確定。這種情況只適用於此編碼器的錯誤輸入的動作是 CodingErrorAction.REPORT 的情況下；否則將像請求的那樣忽略或替換錯誤的輸入。

• CoderResult#unmappableForLengthunmappable-character 結果指示已檢測到不可映射的字元錯誤。編碼不可映射的字元的字元起始於輸入緩衝區（可能向前增加）的位置；這種字元的數目可以通過調用結果物件的 length 方法來確定。這種情況只適用於此編碼器的不可映射的字元的動作是 CodingErrorAction.REPORT 的情況下；否則將像請求的那樣忽略或替換不可映射的字元。

在任一情況下，如果在相同的編碼操作中調用此方法，則要注意保留輸入緩衝區中剩餘的所有字元，以便可提供給下一次調用使用。

endOfInput 參數通知此方法除了給定輸入緩衝區包含的內容，調用者是否能提供更多的輸入。如果可能提供其他的輸入，則調用者應該為此參數傳遞 false；如果不能提供更多的輸入，則調用者應該傳遞 true。實際上在一次調用中傳遞 false，但後來發現實際上沒有更多的輸入可用是相當普遍的，這不是錯誤。但關鍵是，在此方法的一系列調用中，最後一次調用總是傳遞 true，這樣所有剩餘的未編碼輸入都作為錯誤輸入處理。

此方法通過調用 encodeLoop 方法、解釋它的結果、處理錯誤情況並重新調用（如有必要）來完成其工作。

參數：

in - 輸入字元緩衝區

out - 輸出位元組緩衝區

endOfInput - 當且僅當調用者除了給定緩衝區中的內容外不提供其他輸入字元時才為 true

返回：

描述終止原因的 CoderResult 物件

拋出：

IllegalStateException - 如果編碼操作已在進行中並且前面的步驟不是調用 reset 方法，也不是為 endOfInput 參數使用 false 來調用此方法，也不是為 endOfInput 參數使用 true 來調用此方法，而是一個指示未完成編碼操作的返回值

CoderMalfunctionError - 如果對 encodeLoop 方法的調用拋出不可預料的異常

flush

public final CoderResult flush(ByteBuffer out)

刷新此編碼器。

一些編碼器維護內部狀態，並且一旦讀取完所有的輸入序列後，可能需要向輸出緩衝區寫入一些最終位元組。

任何其他輸出寫入輸出緩衝區時都要從緩衝區的當前位置開始。最多將寫入 out.remaining() 個位元組。緩衝區的位置要相應地向前移動，但是其標記和界限將無法修改。

如果此方法成功完成，則它返回 CoderResult.UNDERFLOW。如果輸出緩衝區沒有足夠的空間，則它返回 CoderResult.OVERFLOW。如果發生這種情況，那麼為了完成當前的編碼操作，必須使用具有更多空間的輸出緩衝區再次調用此方法。

如果此編碼器已刷新，則調用此方法無效。

此方法調用 implFlush 方法來執行實際的刷新操作。

參數：

out - 輸出位元組緩衝區

返回：

一個 CoderResult 物件，可能是 CoderResult.UNDERFLOW 或 CoderResult.OVERFLOW

拋出：

IllegalStateException - 如果當前編碼操作的前一步既不是調用 flush 方法，也不是為 endOfInput 參數使用 true 來調用三參數的 encode 方法

implFlush

protected CoderResult implFlush(ByteBuffer out)

刷新此編碼器。

此方法的預設實作不執行任何操作，並且始終返回 CoderResult.UNDERFLOW。對於那些一旦讀取完整個的輸入序列後，可能需要向輸出緩衝區寫入最終位元組的編碼器而言，應該覆寫此方法。

參數：

out - 輸出位元組緩衝區

返回：

一個 CoderResult 物件，可能是 CoderResult.UNDERFLOW 或 CoderResult.OVERFLOW

reset

public final CharsetEncoder reset()

重置此編碼器，清除所有內部狀態。

此方法重置與 charset 無關的狀態，並且為了執行所有特定於 charset 的重置操作，還會調用 implReset 方法。

返回：

此編碼器

implReset

protected void implReset()

重置此編碼器，清除所有特定於 charset 的內部狀態。

此方法的預設實作不執行任何操作。維護內部狀態的編碼器應該覆寫此方法。

encodeLoop

protected abstract CoderResult encodeLoop(CharBuffer in,
                                          ByteBuffer out)

將一個或多個字元編碼為一個或多個位元組。

此方法封裝了基本的編碼循環，在用完輸入、用完輸出緩衝區的空間或遇到編碼錯誤之前編碼盡可能多的字元。此方法由 encode 方法調用，encode 方法處理結果解釋和錯誤恢復。

應該從各緩衝區的當前位置開始進行讀取和寫入。最多將讀取 in.remaining() 個字元，最多將寫入 out.remaining() 個位元組。前移緩衝區的位置，以反映字元讀取和寫入位元組，但是其標記和界限將無法修改。

此方法返回一個 CoderResult 物件描述它終止的原因，其方式和 encode 方法的相同。大多數此方法的實作處理編碼錯誤的方式是由 encode 方法返回一個用來解釋錯誤的相應結果物件。最優的實作可能是檢查相關的錯誤操作並且自己實作該操作。

此方法的一種實作可能在接收到足夠的輸入之前，通過返回 CoderResult.UNDERFLOW 來執行任意的 lookahead。

參數：

in - 輸入字元緩衝區

out - 輸出位元組緩衝區

返回：

描述終止原因的 CoderResult 物件

encode

public final ByteBuffer encode(CharBuffer in)
                        throws CharacterCodingException

把單個輸入字元緩衝區的剩餘內容編碼到新分派的位元組緩衝區的便捷方法。

此方法實作完整的編碼操作；也就是說，它重置編碼器，然後編碼給定字元緩衝區中的字元，最後刷新此編碼器。因此如果正在進行編碼操作，則不應該調用此方法。

參數：

in - 輸入字元緩衝區

返回：

新分派的位元組緩衝區，包含編碼操作結果。該緩衝區的位置是零，並且它的界限是在最後寫入的位元組之後。

拋出：

IllegalStateException - 如果已經進行編碼操作

MalformedInputException - 如果從輸入緩衝區當前位置開始的字元序列不是合法的 16 位 Unicode 序列，並且當前的錯誤輸入操作是 CodingErrorAction.REPORT

UnmappableCharacterException - 如果從輸入緩衝區當前位置開始的字元序列不能映射到等同的位元組序列，並且當前的不可映射的字元操作是 CodingErrorAction.REPORT

CharacterCodingException

canEncode

public boolean canEncode(char c)

通知此編碼器是否能夠編碼給定的字元。

如果給定的字元是代理項字元，則此方法返回 false；只有當這些字元是高代理項後跟低代理項所組成的代理項對的成員時，才能對其進行解釋。可使用 canEncode(CharSequence) 方法來檢測是否能夠編碼某個字元序列。

此方法可以修改此編碼器的狀態；因此如果正在進行編碼操作，則不應該調用此方法。

此方法的預設實作效率不是很高；為了提高性能通常應該覆寫它。

返回：

當且僅當此編碼器能夠編碼給定字元時才返回 true

拋出：

IllegalStateException - 如果已經進行編碼操作

canEncode

public boolean canEncode(CharSequence cs)

通過此編碼器是否能夠編碼給定的字元序列。

如果此方法對特定的字元序列返回 false，則通過執行完整編碼操作可獲得有關無法編碼序列的更多資訊。

此方法可以修改此編碼器的狀態；因此如果正在進行編碼操作，則不應該調用此方法。

此方法的預設實作效率不是很高；為了提高性能通常應該覆寫它。

返回：

當且僅當此編碼器在既不拋出任何異常也不執行任何替換的情況下就能編碼給定的字元時才返回 true

拋出：

IllegalStateException - 如果已經進行編碼操作