java.nio.charset
類別 CharsetDecoder

java.lang.Object
  java.nio.charset.CharsetDecoder

public abstract class CharsetDecoder
extends Object

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

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

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

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

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

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

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

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

如何處理解碼錯誤取決於為該錯誤型別所請求的操作，在 CodingErrorAction 類別的實例中描述了該型別的錯誤。可能的錯誤操作是忽略錯誤的輸入、通過返回的 CoderResult 物件將錯誤報告給調用者，或者用當前的替換字元串值CodingErrorAction#REPLACE替換錯誤的輸入。 該替換字元串的初始值是 "FD"； 可通過 replaceWith 方法更改此值。

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

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

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

從以下版本開始：

1.4

另請參見：

ByteBuffer, CharBuffer, Charset, CharsetEncoder

建構子摘要

protected

CharsetDecoder(Charset cs, float averageCharsPerByte, float maxCharsPerByte) 初始化新的解碼器。

方法摘要

float	averageCharsPerByte() 返回為每個輸入位元組產生的平均字元數。
Charset	charset() 返回創建此解碼器的 charset。
CharBuffer	decode(ByteBuffer in) 把單個輸入位元組緩衝區的剩餘內容解碼到新分派的字元緩衝區的便捷方法。
CoderResult	decode(ByteBuffer in, CharBuffer out, boolean endOfInput) 從給定的輸入緩衝區中解碼盡可能多的位元組，把結果寫入給定的輸出緩衝區。
protected abstract CoderResult	decodeLoop(ByteBuffer in, CharBuffer out) 將一個或多個位元組解碼為一個或多個字元。
Charset	detectedCharset() 獲取此解碼器檢測到的 charset（可選操作）。
CoderResult	flush(CharBuffer out) 刷新此解碼器。
protected CoderResult	implFlush(CharBuffer out) 刷新此解碼器。
protected void	implOnMalformedInput(CodingErrorAction newAction) 報告此解碼器的錯誤輸入操作的更改。
protected void	implOnUnmappableCharacter(CodingErrorAction newAction) 報告此解碼器的不可映射的字元操作的更改。
protected void	implReplaceWith(String newReplacement) 報告此解碼器替換值的更改。
protected void	implReset() 重置此解碼器，清除所有特定於 charset 的內部狀態。
boolean	isAutoDetecting() 通知此解碼器是否實作了自動檢測 charset。
boolean	isCharsetDetected() 通知此解碼器是否已經檢測到了一個 charset（可選操作）。
CodingErrorAction	malformedInputAction() 返回此解碼器對錯誤輸入錯誤的當前操作。
float	maxCharsPerByte() 返回為每個輸入位元組產生的最大字元數。
CharsetDecoder	onMalformedInput(CodingErrorAction newAction) 更改此解碼器對錯誤輸入錯誤的操作。
CharsetDecoder	onUnmappableCharacter(CodingErrorAction newAction) 更改此解碼器對不可映射的字元錯誤的操作。
String	replacement() 返回此解碼器的替換值。
CharsetDecoder	replaceWith(String newReplacement) 更改此解碼器的替換值。
CharsetDecoder	reset() 重置此解碼器，清除所有內部狀態。
CodingErrorAction	unmappableCharacterAction() 返回此解碼器對不可映射的字元錯誤的當前操作。

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

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

建構子詳細資訊

CharsetDecoder

protected CharsetDecoder(Charset cs,
                         float averageCharsPerByte,
                         float maxCharsPerByte)

初始化新的解碼器。新的解碼器具有給定的每位元組多少個字元 (chars-per-byte) 值，它的替換值是字元串 "\uFFFD"。

參數：

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

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

拋出：

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

方法詳細資訊

charset

public final Charset charset()

返回創建此解碼器的 charset。

返回：

此解碼器的 charset

replacement

public final String replacement()

返回此解碼器的替換值。

返回：

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

replaceWith

public final CharsetDecoder replaceWith(String newReplacement)

更改此解碼器的替換值。

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

參數：

newReplacement - 新替換值；一定不能為 null 且長度必須為非零

返回：

此解碼器

拋出：

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

implReplaceWith

protected void implReplaceWith(String newReplacement)

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

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

參數：

newReplacement -

malformedInputAction

public CodingErrorAction malformedInputAction()

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

返回：

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

onMalformedInput

public final CharsetDecoder onMalformedInput(CodingErrorAction newAction)

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

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

參數：

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

返回：

此解碼器

拋出：

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

implOnMalformedInput

protected void implOnMalformedInput(CodingErrorAction newAction)

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

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

unmappableCharacterAction

public CodingErrorAction unmappableCharacterAction()

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

返回：

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

onUnmappableCharacter

public final CharsetDecoder onUnmappableCharacter(CodingErrorAction newAction)

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

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

參數：

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

返回：

此解碼器

拋出：

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

implOnUnmappableCharacter

protected void implOnUnmappableCharacter(CodingErrorAction newAction)

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

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

averageCharsPerByte

public final float averageCharsPerByte()

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

返回：

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

maxCharsPerByte

public final float maxCharsPerByte()

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

返回：

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

decode

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

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

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

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

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

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

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

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

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

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

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

參數：

in - 輸入位元組緩衝區

out - 輸出字元緩衝區

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

返回：

描述終止原因的 CoderResult 物件

拋出：

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

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

flush

public final CoderResult flush(CharBuffer out)

刷新此解碼器。

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

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

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

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

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

參數：

out - 輸出字元緩衝區

返回：

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

拋出：

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

implFlush

protected CoderResult implFlush(CharBuffer out)

刷新此解碼器。

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

參數：

out - 輸出字元緩衝區

返回：

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

reset

public final CharsetDecoder reset()

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

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

返回：

此解碼器

implReset

protected void implReset()

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

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

decodeLoop

protected abstract CoderResult decodeLoop(ByteBuffer in,
                                          CharBuffer out)

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

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

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

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

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

參數：

in - 輸入位元組緩衝區

out - 輸出字元緩衝區

返回：

描述終止原因的 CoderResult 物件

decode

public final CharBuffer decode(ByteBuffer in)
                        throws CharacterCodingException

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

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

參數：

in - 輸入位元組緩衝區

返回：

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

拋出：

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

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

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

CharacterCodingException

isAutoDetecting

public boolean isAutoDetecting()

通知此解碼器是否實作了自動檢測 charset。

此方法的預設實作總是返回 false；為了返回 true，應該由自動檢測解碼器覆寫此方法。

返回：

當且僅當此解碼器實作自動檢測 charset 時才返回 true

isCharsetDetected

public boolean isCharsetDetected()

通知此解碼器是否已經檢測到了一個 charset（可選操作）。

如果此解碼器實作了自動檢測 charset，那麼在解碼操作期間的某個點上此方法可能開始返回 true，以指示在輸入位元組序列中檢測到一個具體的 charset。一旦發生這種情況，就可以調用 detectedCharset 方法來獲取檢測到 charset。

此方法返回 false 並不表示尚未解碼任何位元組。一些自動檢測解碼器能夠解碼某些（甚至全部）輸入位元組序列，而不是固定於某個特定的 charset。

此方法的預設實作總是拋出 UnsupportedOperationException；一旦確定了輸入 charset，那麼為了返回 true，自動檢測解碼器應該覆寫此方法。

返回：

當且僅當此解碼器檢測到具體的 charset 時才返回 true

拋出：

UnsupportedOperationException - 如果此解碼器沒有實作自動檢測 charset

detectedCharset

public Charset detectedCharset()

獲取此解碼器檢測到的 charset（可選操作）。

如果此解碼器實作自動檢測 charset，那麼一旦檢測到該 charset，則此方法返回實際的 charset。之後，此方法在當前的解碼操作過程中都返回相同的值。如果尚未讀取足夠的輸入位元組來確定實際的 charset，則此方法拋出 IllegalStateException。

此方法的預設實作總是拋出 UnsupportedOperationException；為了返回適當的值，應該由自動檢測解碼器覆寫此方法。

返回：

此自動檢測解碼器檢測到的 charset，如果尚未確定 charset，則返回 null

拋出：

IllegalStateException - 如果尚未讀取足夠的位元組來確定 charset

UnsupportedOperationException - 如果此解碼器沒有實作自動檢測 charset