java.nio.charset
クラス CharsetDecoder

java.lang.Object
  |
  +--java.nio.charset.CharsetDecoder

public abstract class CharsetDecoder

extends Object

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

入力バイトシーケンスは、byte バッファなどのバッファから渡されます。出力文字シーケンスは、char バッファなどのバッファに書き込まれます。デコーダは、必ず次のメソッド呼び出しシーケンス (以下「デコード処理」) のあとで使用してください。

1. 初めて使用するときは、reset メソッドを使ってデコーダをリセットします。

2. 追加の入力がなくなるまで、繰り返し decode メソッドを呼び出します。endOfInput 引数に false を渡し、入力バッファを格納して、次の呼び出しの前に出力バッファをフラッシュします。

3. decode メソッドの呼び出しを終了するときは、endOfInput 引数に true を渡します。

4. デコーダが内部状態を出力バッファへフラッシュできるように flush メソッドを呼び出します。

decode メソッドを呼び出すたびに、入力バッファ内のバイトがデコードされ、出力バッファに文字が書き込まれます。新たな入力要求を受け取ったり、出力バッファの容量が不足したり、デコードエラーが発生したりすると、decode メソッドは終了し、終了の原因を示す CoderResult オブジェクトを返します。呼び出し元は、このオブジェクトを確認して、入力バッファを格納するか、出力バッファをフラッシュするか、デコードエラーからの回復処理を実行して、呼び出しを再試行します。

デコードエラーには一般的な 2 種類のエラーがあります。入力バイトシーケンスがこの文字セットにとって不当な場合は、「不正入力エラー」が発生します。入力バイトシーケンスは正当でも、これを有効な Unicode 文字にマップできない場合は、「マップ不可文字エラー」が発生します。

デコードエラーは、その種類のエラーに対して要求されたアクションに従って処理されます。こうしたアクションは、CodingErrorAction クラスのインスタンスに記述されています。たとえば、不正な入力の無視、戻ってきた CoderResult オブジェクトによる呼び出し元への報告、不正な入力内容を代替文字列の現在値へ置き換えといったアクションがあります。代替文字列の初期値は "\uFFFD" ですが、この値は replaceWith メソッドを使って変更できます。

不正入力エラーやマップ不可文字エラーが発生した場合、デフォルトのアクションとして、これらのエラーの報告が行われます。不正入力エラーに対するアクションを変更したい場合は onMalformedInput メソッド、マップ不可文字エラーに対するアクションを変更したい場合は onUnmappableCharacter メソッドを使用します。

このクラスは、エラーアクションの実装をはじめとするデコード処理のさまざまな部分を処理するように設計されています。特定の文字セット用のデコーダは、このクラスの具象サブクラスなので、標準デコードループをカプセル化する抽象メソッド、decodeLoop を実装するだけで済みます。内部状態を保持するサブクラスは、これに加えて、flush メソッドと reset メソッドをオーバーライドする必要があります。

このクラスのインスタンスを複数の並行スレッドで安全に使用することはできません。

導入されたバージョン:

1.4

関連項目:

ByteBuffer, CharBuffer, Charset, CharsetEncoder

コンストラクタの概要

protected

CharsetDecoder(Charset cs, float averageCharsPerByte, float maxCharsPerByte) 新しいデコーダを初期化します。

メソッドの概要

float	averageCharsPerByte() 入力バイトごとに生成される平均文字数を返します。
Charset	charset() このデコーダを生成した文字セットを返します。
CharBuffer	decode(ByteBuffer in) 単一の入力 byte バッファのコンテンツを新しく割り当てられた char バッファ内にデコードする簡易メソッドです。
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)

新しいデコーダを初期化します。新しいデコーダは、指定されたバイトごとの文字の値を保持します。この値の代替値は "\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 - 入力 byte バッファ

out - 出力 char バッファ

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 を返します。CoderResult.OVERFLOW が返された場合は、容量に空きのある出力バッファを指定してこのメソッドを再度呼び出し、このデコード処理を完了させる必要があります。

このメソッドは、implFlush メソッドを呼び出して、実際にフラッシュを行います。

パラメータ:

out - 出力 char バッファ

戻り値:

Coder Result オブジェクト (CoderResult.UNDERFLOW または CoderResult.OVERFLOW)

例外:

IllegalStateException - 現在のデコード処理の直前の処理が reset メソッドの呼び出しでも、endOfInput パラメータに true を指定した 3 つの引数を持つ decode メソッドの呼び出しでもない場合

implFlush

protected CoderResult implFlush(CharBuffer out)

このデコーダをフラッシュします。

このメソッドのデフォルト実装は、何の処理も行わず常に CoderResult.UNDERFLOW を返します。このメソッドは、入力シーケンスの読み込みが完了した時点で出力バッファに終端文字を書き込む必要があるデコーダによってオーバーライドされます。

パラメータ:

out - 出力 char バッファ

戻り値:

Coder Result オブジェクト (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 - 入力 byte バッファ

out - 出力 char バッファ

戻り値:

終了の原因を説明する coder-result オブジェクト

decode

public final CharBuffer decode(ByteBuffer in)
                        throws CharacterCodingException

単一の入力 byte バッファのコンテンツを新しく割り当てられた char バッファ内にデコードする簡易メソッドです。

このメソッドでは、すべてのデコード処理が実行されます。つまり、このメソッドを実行すると、デコーダがリセットされ、指定された byte バッファ内のバイトがデコードされ、最後にデコーダがフラッシュされます。デコード処理が現在進行中の場合は、このメソッドを呼び出さないでください。

パラメータ:

in - 入力 byte バッファ

戻り値:

デコード処理の結果を格納する、新しく割り当てられた char バッファ (バッファ位置はゼロ、リミットは最後に書き込まれた文字によって決定される)

例外:

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 - このデコーダが自動検出文字セットを実装していない場合