java.nio.charset

クラス CharsetDecoder

java.lang.Object

java.nio.charset.CharsetDecoder

public abstract class CharsetDecoder
extends Object

特定の文字セットで表現されたバイトシーケンスを 16 ビット Unicode 文字のシーケンスに変換するエンジンです。

入力バイトシーケンスは、単一の byte バッファーまたは一連の byte バッファーとして提供されます。出力文字シーケンスは、単一の文字バッファーまたは一連の文字バッファーに書き込まれます。デコーダを使用する際には、必ず次のメソッド呼び出し手順 (以下、デコード処理) に従ってください。

1. デコーダをはじめて使用する場合以外は、reset メソッドを使用してデコーダをリセットします。

2. 追加入力がある限り decode メソッドを 0 回以上呼び出し、各呼び出しの間に endOfInput 引数に false を渡し、入力バッファーにデータを格納し、出力バッファーをフラッシュします。

3. decode メソッドを最後に 1 回呼び出し、endOfInput 引数に true を渡します。

4. デコーダが内部状態を出力バッファーへフラッシュできるように、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	averageCharsPerByte() 入力バイトごとに生成される平均文字数を返します。
Charset	charset() このデコーダを生成した文字セットを返します。
CharBuffer	decode(ByteBuffer in) 単一の入力 byte バッファーのコンテンツを新しく割り当てられた文字バッファー内にデコードする簡易メソッドです。
CoderResult	decode(ByteBuffer in, CharBuffer out, boolean endOfInput) 指定された入力バッファー内のバイトを最大限デコードし、指定された出力バッファーに結果を書き込みます。
protected abstract CoderResult	decodeLoop(ByteBuffer in, CharBuffer out) 1 個以上のバイトをデコードし、1 個以上の文字へデコードします。
Charset	detectedCharset() このデコーダによって検出された文字セットを取得します (オプションの操作)。
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() このデコーダをリセットし、文字セット固有の内部の状態をクリアします。
boolean	isAutoDetecting() このデコーダが自動検出文字セットを実装するかどうかを判断します。
boolean	isCharsetDetected() このデコーダがすでに文字セットを検出しているかどうかを判断します (オプションの操作)。
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)

新しいデコーダを初期化します。新しいデコーダには指定された 1 バイト当たりの文字数値が格納され、その置換文字列は "\uFFFD" になります。

パラメータ:

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 以外でゼロでない長さの値)

戻り値:

このデコーダ

例外:

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 は、出力バッファーの容量が不足していて、これ以上バイトをデコードできないことを示します。残りの文字数が多い出力バッファーを指定して、このメソッドを再度呼び出す必要があります。このためには通常、出力バッファーに入っているデコード済みの文字を排出します。

• 入力形式が正しくない結果は、入力形式が正しくないエラーが検出されたことを示します。不正なバイトは、入力バッファーの位置 (位置の値が増加している可能性もある) から始まります。不正なバイト数は、結果オブジェクトの 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 - このデコーダが自動検出文字セットを実装していない場合