JavaTM Platform
Standard Ed. 6

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 メソッドを繰り返し呼び出します。 各呼び出しの間で、endOfInput 引数に false を指定し、入力バッファーにデータを格納して、出力バッファーをフラッシュします。

  3. decode メソッドの最後の呼び出しでは、endOfInput 引数に true を指定します。

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

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

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

特定のデコードエラーがどのように処理されるかは、そのエラーに対して要求されるアクションによって決まります。 これらのアクションは、CodingErrorAction クラスのインスタンスによって記述されます。利用可能なエラーアクションは、エラー入力の 無視、戻り値 CoderResult オブジェクトを経由した呼び出し元へのエラーの 報告、現在の置換文字列値によるエラー入力の 置換 の 3 つです。置換の初期値は「\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 オブジェクトを返します。

いずれの場合も、このメソッドを同じデコード処理の中で再度呼び出すときは、次の呼び出しで使用できるように、入力バッファー内のバイトを保存する必要があります。

endOfInput パラメータは、指定された入力バッファーに呼び出し元からの新たな入力があるかどうかをこのメソッドに通知します。まだ入力の可能性がある場合、呼び出し元はこのパラメータに false を渡す必要があります。これ以上入力の可能性がない場合は true を渡します。呼び出し元から false を渡したあとで入力がなかったとしても、問題はありません。しかし、呼び出しシーケンスにおける最後の呼び出しでは、true を渡さなければなりません。 これ以降、まだデコードされていない入力は「不正入力」と見なされるようになります。

このメソッドは、まず decodeLoop メソッドを呼び出します。 その後、その結果を解釈し、エラー条件の処理を済ませたあと、必要に応じて再度そのメソッドを呼び出します。

パラメータ:
in - 入力 byte バッファー
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 を返します。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 - 入力 byte バッファー
out - 出力文字バッファー
戻り値:
終了の原因を説明する coder-result オブジェクト

decode

public final CharBuffer decode(ByteBuffer in)
                        throws CharacterCodingException
単一の入力 byte バッファーのコンテンツを新しく割り当てられた文字バッファー内にデコードする簡易メソッドです。

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

パラメータ:
in - 入力 byte バッファー
戻り値:
デコード処理の結果を格納する、新しく割り当てられた文字バッファー。バッファー位置はゼロで、リミットは最後に書き込まれた文字によって決定される
例外:
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 - このデコーダが自動検出文字セットを実装していない場合

JavaTM Platform
Standard Ed. 6

バグの報告と機能のリクエスト
さらに詳しい API リファレンスおよび開発者ドキュメントについては、Java SE 開発者用ドキュメントを参照してください。開発者向けの詳細な解説、概念の概要、用語の定義、バグの回避策、およびコード実例が含まれています。

Copyright 2006 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms. Documentation Redistribution Policy も参照してください。