入力バイト・シーケンスは、単一のbyteバッファまたは一連のbyteバッファとして提供されます。 出力文字シーケンスは、単一の文字バッファまたは一連の文字バッファに書き込まれます。 デコーダを使用する際には、必ず次のメソッド呼出し手順(以下、デコード処理)に従ってください。
デコーダをはじめて使用する場合以外は、
reset
メソッドを使用してデコーダをリセットします。追加入力がある限り
decode
メソッドを0回以上呼び出し、各呼出しの間にendOfInput
引数にfalse
を渡し、入力バッファにデータを格納し、出力バッファをフラッシュします。decode
メソッドを最後に1回呼び出し、endOfInput
引数にtrue
を渡します。デコーダが内部状態を出力バッファへフラッシュできるように、
flush
メソッドを呼び出します。
decode
メソッドを呼び出すたびに、入力バッファ内のバイトが文字にデコードされ、出力バッファに書き込まれます。 新たな入力要求を受け取ったり、出力バッファの容量が不足したり、デコード・エラーが発生したりすると、decode
メソッドは終了します。 いずれの場合でも、終了の理由を説明するためにCoderResult
オブジェクトが返されます。 呼出し元は、このオブジェクトを確認して、入力バッファをいっぱいにするか、出力バッファをフラッシュするか、デコード・エラーからの回復処理を実行して、呼出しを再試行します。
デコード・エラーには一般的な2種類のエラーがあります。 入力バイト・シーケンスがこの文字セットにとって不当な場合は、不正入力エラーが発生します。 入力バイト・シーケンスは正当でも、これを有効なUnicode文字にマップできない場合は、マップ不可文字エラーが発生します。
特定のデコード・エラーがどのように処理されるかは、その種類のエラーに対して要求されるアクションによって決まります。これらのアクションは、CodingErrorAction
クラスのインスタンスによって記述されます。 利用可能なエラー・アクションは、エラー入力の無視、戻り値のCoderResult
オブジェクトを経由した呼出し元へのエラーの報告、または現在の置換文字列値によるエラー入力の置換です。 置換の初期値は"\uFFFD"
です。この値は、replaceWith
メソッドを使って変更できます。
入力形式が正しくないエラーやマップ不可文字エラーが発生した場合、デフォルトのアクションとして、これらのエラーの報告が行われます。 入力形式が正しくないエラーに対するアクションを変更する場合はonMalformedInput
メソッドを、マップ不可文字エラーに対するアクションを変更する場合はonUnmappableCharacter
メソッドを、それぞれ使用します。
このクラスは、エラー・アクションの実装をはじめとするデコード処理の詳細の多くを処理するように設計されています。 特定の文字セットに対するデコーダ(このクラスの具象サブクラス)が実装する必要があるのは、標準デコード・ループをカプセル化する抽象メソッドdecodeLoop
だけです。 これに加え、内部状態を保持するサブクラスは、implFlush
メソッドとimplReset
メソッドをオーバーライドする必要があります。
このクラスのインスタンスは、複数のスレッドで並行して使用することはできません。
- 導入されたバージョン:
- 1.4
- 関連項目:
ByteBuffer
,CharBuffer
,Charset
,CharsetEncoder
-
コンストラクタのサマリー
修飾子コンストラクタ説明protected
CharsetDecoder(Charset cs, float averageCharsPerByte, float maxCharsPerByte)
新しいデコーダを初期化します。 -
メソッドのサマリー
修飾子と型メソッド説明float
入力バイトごとに生成される平均文字数を返します。charset()
このデコーダを生成した文字セットを返します。decode(ByteBuffer in)
単一の入力byteバッファのコンテンツを新しく割り当てられた文字バッファ内にデコードする簡易メソッドです。decode(ByteBuffer in, CharBuffer out, boolean endOfInput)
指定された入力バッファ内のバイトを最大限デコードし、指定された出力バッファに結果を書き込みます。protected abstract CoderResult
decodeLoop(ByteBuffer in, CharBuffer out)
1個以上のバイトをデコードし、1個以上の文字へデコードします。このデコーダによって検出された文字セットを取得します (オプションの操作)。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
このデコーダをリセットし、文字セット固有の内部の状態をクリアします。boolean
このデコーダが自動検出文字セットを実装するかどうかを判断します。boolean
このデコーダがすでに文字セットを検出しているかどうかを判断します (オプションの操作)。不正入力エラーに対する、このデコーダの現在のアクションを返します。float
入力バイトごとに生成される最大文字数を返します。onMalformedInput(CodingErrorAction newAction)
不正入力エラーに対するこのデコーダのアクションを変更します。onUnmappableCharacter(CodingErrorAction newAction)
マップできない文字エラーに対する、このデコーダのアクションを変更します。このデコーダの置換値を返します。replaceWith(String newReplacement)
このデコーダの代替値を変更します。reset()
このデコーダをリセットし、内部の状態をクリアします。マップ不可文字エラーに対する、このデコーダの現在のアクションを返します。
-
コンストラクタの詳細
-
CharsetDecoder
protected CharsetDecoder(Charset cs, float averageCharsPerByte, float maxCharsPerByte)新しいデコーダを初期化します。 新しいデコーダには指定された1バイト当たりの文字数値が格納され、その置換文字列は"\uFFFD"
になります。- パラメータ:
cs
- このデコーダを生成した文字セットaverageCharsPerByte
- 入力バイトごとに生成される期待文字数を示す正のfloat値maxCharsPerByte
- 入力バイトごとに生成される最大文字数を示す正のfloat値- 例外:
IllegalArgumentException
- 上記のパラメータの前提条件が満たされていない場合
-
-
メソッドの詳細
-
charset
public final Charset charset()このデコーダを生成した文字セットを返します。- 戻り値:
- このデコーダの文字セット
-
replacement
public final String replacement()このデコーダの置換値を返します。- 戻り値:
- このデコーダの現在の代替値(
null
以外、空の値以外)
-
replaceWith
public final CharsetDecoder replaceWith(String newReplacement)このデコーダの代替値を変更します。このメソッドは、新しい置換値が条件に合っていることを確認したうえで、その値を渡して
implReplaceWith
メソッドを呼び出します。- パラメータ:
newReplacement
- 新しい交換。null
であってはならず、長さがゼロでなくてはならず、maxCharsPerByte
メソッドから返された値よりも長くてはいけません- 戻り値:
- このデコーダ
- 例外:
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)不正入力エラーに対する、このデコーダのアクションが変更されたことを報告します。このメソッドのデフォルト実装では何の処理も行われません。 不正入力エラーに対するアクションの変更通知を必要とするデコーダでは、このメソッドをオーバーライドする必要があります。
- パラメータ:
newAction
- 新しいアクション
-
unmappableCharacterAction
public CodingErrorAction unmappableCharacterAction()マップ不可文字エラーに対する、このデコーダの現在のアクションを返します。- 戻り値:
- マップ不可文字エラーに対する現在のアクション(
null
以外)
-
onUnmappableCharacter
public final CharsetDecoder onUnmappableCharacter(CodingErrorAction newAction)マップできない文字エラーに対する、このデコーダのアクションを変更します。このメソッドは、新しいアクションを渡して
implOnUnmappableCharacter
メソッドを呼び出します。- パラメータ:
newAction
- 新しいアクション(null
以外)- 戻り値:
- このデコーダ
- 例外:
IllegalArgumentException
- 上記のパラメータの前提条件が満たされていない場合
-
implOnUnmappableCharacter
protected void implOnUnmappableCharacter(CodingErrorAction newAction)マップできない文字エラーに対する、このデコーダのアクションが変更されたことを報告します。このメソッドのデフォルト実装では何の処理も行われません。 マップ不可文字エラーに対するアクションの変更通知を必要とするデコーダでは、このメソッドをオーバーライドする必要があります。
- パラメータ:
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
は、出力バッファの容量が不足していて、これ以上バイトをデコードできないことを示します。 残りの文字数が多い出力バッファを指定して、このメソッドを再度呼び出す必要があります。 このためには通常、出力バッファに入っているデコード済みの文字を排出します。入力形式が正しくない結果は、入力形式が正しくないエラーが検出されたことを示します。 形式が不正なバイトは、入力バッファの位置(位置の値が増加している可能性もある)から始まります。形式が不正なバイト数は、結果オブジェクトの
length
メソッドを呼び出すことで特定できます。 ただし、これが当てはまるのは、このデコーダの形式不正入力エラーに対するアクションがCodingErrorAction.REPORT
である場合に限られます。それ以外の場合、形式不正入力は要求に応じて無視されるか、別の値に置換されます。マップ不可文字結果は、マップ不可文字エラーが検出されたことを示します。 マップ不可文字をデコードするバイトは、入力バッファの位置(位置の値が増加している可能性もある)から始まります。そのバイト数は、結果オブジェクトの
length
メソッドを呼び出すことで特定できます。 ただし、これが当てはまるのは、このデコーダのマップ不可文字エラーに対するアクションがCodingErrorAction.REPORT
である場合に限られます。それ以外の場合、マップ不可文字は要求に応じて無視されるか、別の値に置換されます。
endOfInput
パラメータは、指定された入力バッファに呼出し元からの新たな入力があるかどうかをこのメソッドに通知します。 まだ入力の可能性がある場合、呼出し元はこのパラメータにfalse
を渡す必要があります。これ以上入力の可能性がない場合はtrue
を渡します。 呼出し元からfalse
を渡したあとで入力がなかったとしても、問題はありません。 しかし、呼出しシーケンスにおけるこのメソッドの最後の呼出しでは、true
を渡さなければいけません。これ以降、まだデコードされていない入力は「不正入力」と見なされるようになります。このメソッドは、まず
decodeLoop
メソッドを呼び出します。その後、その結果を解釈し、エラー条件の処理を済ませたあと、必要に応じて再度そのメソッドを呼び出します。- パラメータ:
in
- 入力バイト・バッファout
- 出力文字バッファendOfInput
- 呼出し元が指定されたバッファにこれ以上の入力バイトを追加する可能性がない場合に限りtrue
- 戻り値:
- 終了の原因を説明するcoder-resultオブジェクト
- 例外:
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
を指定した3つの引数を持つdecode
メソッドの呼出しでもない場合
-
implFlush
protected CoderResult implFlush(CharBuffer out)このデコーダをフラッシュします。このメソッドのデフォルト実装では何の処理も行われず、常に
CoderResult.UNDERFLOW
を返します。 入力シーケンスの読込み完了後に出力バッファに最後の文字を書き込む必要があるデコーダでは、このメソッドをオーバーライドする必要があります。- パラメータ:
out
- 出力文字バッファ- 戻り値:
- CoderResultオブジェクト。
CoderResult.UNDERFLOW
またはCoderResult.OVERFLOW
-
reset
public final CharsetDecoder reset()このデコーダをリセットし、内部の状態をクリアします。このメソッドは、文字セットに依存しない状態をリセットします。また、文字セット固有のリセット・アクションを実行するために、
implReset
メソッドも呼び出します。- 戻り値:
- このデコーダ
-
implReset
protected void implReset()このデコーダをリセットし、文字セット固有の内部の状態をクリアします。このメソッドのデフォルト実装では何の処理も行われません。 内部状態を保持するデコーダでは、このメソッドをオーバーライドする必要があります。
-
decodeLoop
protected abstract CoderResult decodeLoop(ByteBuffer in, CharBuffer out)1個以上のバイトをデコードし、1個以上の文字へデコードします。このメソッドは、基本的なデコード・ループをカプセル化し、入力がなくなるか、出力バッファの容量が不足するか、デコード・エラーが発生するまで最大限のバイトをデコードします。 このメソッドは、結果解釈とエラー復旧を行う
decode
メソッドによって呼び出されます。バッファに対する読書きは、各バッファの現在位置から行われます。 読み取られるバイト数は多くて
in.remaining()
バイト、書き込まれる文字数は多くてout.remaining()
文字です。 バッファの位置は、読み取られたバイト数または書き込まれた文字数に従って増加しますが、マークとリミットはそのままです。このメソッドは、
decode
メソッドと同様に、終了の理由を記述したCoderResult
オブジェクトを返します。 このメソッドの実装の大部分は、decode
メソッドでの解釈に必要な結果オブジェクトを返すことで、デコード・エラーを処理します。 これに対し、最適化された実装は、関連エラー・アクションを調べ、そのアクションを自身で実行する可能性もあります。このメソッドの実装によっては、十分な量の入力を受け取るまで任意の前方検索を行い、
CoderResult.UNDERFLOW
を返し続ける可能性があります。- パラメータ:
in
- 入力バイト・バッファout
- 出力文字バッファ- 戻り値:
- 終了の原因を説明するcoder-resultオブジェクト
-
decode
public final CharBuffer decode(ByteBuffer in) throws CharacterCodingException単一の入力byteバッファのコンテンツを新しく割り当てられた文字バッファ内にデコードする簡易メソッドです。このメソッドはデコード処理全体を実装しています。つまり、このメソッドは、このデコーダをリセットした後、指定されたbyteバッファ内のバイトをデコードし、最後にこのデコーダをフラッシュします。 したがって、デコード処理がすでに進行中の場合は、このメソッドを呼び出さないでください。
- パラメータ:
in
- 入力バイト・バッファ- 戻り値:
- デコード処理の結果を格納する、新しく割り当てられた文字バッファ。 バッファ位置はゼロで、リミットは最後に書き込まれた文字によって決定される
- 例外:
IllegalStateException
- デコード処理がすでに進行中である場合MalformedInputException
- 入力バッファの現在位置から始まるバイト・シーケンスがこの文字セットにとって不正であり、不正入力エラーに対するアクションがCodingErrorAction.REPORT
である場合UnmappableCharacterException
- 入力バッファの現在位置から始まるバイト・シーケンスを同等の文字シーケンスにマップすることができず、マップ不可文字エラーに対するアクションがCodingErrorAction.REPORT
である場合CharacterCodingException
-
isAutoDetecting
public boolean isAutoDetecting()このデコーダが自動検出文字セットを実装するかどうかを判断します。このメソッドのデフォルト実装は、常に
false
を返します。自動検出デコーダでは、このメソッドをオーバーライドしてtrue
を返すようにする必要があります。- 戻り値:
- このデコーダが自動検出文字セットを実装している場合に限り
true
-
isCharsetDetected
public boolean isCharsetDetected()このデコーダがすでに文字セットを検出しているかどうかを判断します (オプションの操作)。このデコーダが自動検出文字セットを実装している場合、デコード処理のある時点からこのメソッドから
true
が返されるようになりますが、これは、入力バイト・シーケンス内で特定の文字セットが検出されたことを示します。 それ以降は、detectedCharset
メソッドを呼び出すことで、検出された文字セットを取得できます。このメソッドの戻り値が
false
であっても、バイトのデコードが行われていることがあります。 一部の自動検出デコーダは、特定の文字セットを選択しないまま入力バイト・シーケンスの一部または全部をデコードすることができます。このメソッドのデフォルト実装は、常に
UnsupportedOperationException
を返します。自動検出デコーダの場合、入力文字セットが検出された時点でtrue
を返すように、このメソッドをオーバーライドする必要があります。- 戻り値:
- このデコーダが特定の文字セットを検出した場合に限り
true
- 例外:
UnsupportedOperationException
- このデコーダが自動検出文字セットを実装していない場合
-
detectedCharset
public Charset detectedCharset()このデコーダによって検出された文字セットを取得します (オプションの操作)。このデコーダが自動検出文字セットを実装している場合、このメソッドは、実際の文字セットが検出された時点でその文字セットを返します。 これ以降、現在のデコード処理が終了するまで同じ値を返します。 読込み入力バイト数が少なすぎて文字セットを特定できていない場合、このメソッドは
IllegalStateException
をスローします。このメソッドのデフォルト実装は、常に
UnsupportedOperationException
を返します。自動検出デコーダの場合、適切な値を返すようにこのメソッドをオーバーライドする必要があります。- 戻り値:
- この自動検出デコーダによって検出された文字セットか、文字セットが特定されなかった場合は
null
- 例外:
IllegalStateException
- 読込みバイト数の不足のため、文字セットを特定できなかった場合UnsupportedOperationException
- このデコーダが自動検出文字セットを実装していない場合
-