|
JavaTM 2 Platform Std. Ed. v1.4.0 |
||||||||||
前のクラス 次のクラス | フレームあり フレームなし | ||||||||||
概要: 入れ子 | フィールド | コンストラクタ | メソッド | 詳細: フィールド | コンストラクタ | メソッド |
java.lang.Object | +--java.nio.charset.CharsetDecoder
特定の文字セットで表現されたバイトシーケンスを 16 ビット Unicode 文字のシーケンスに変換するエンジンです。
入力バイトシーケンスは、byte バッファなどのバッファから渡されます。出力文字シーケンスは、char バッファなどのバッファに書き込まれます。デコーダは、必ず次のメソッド呼び出しシーケンス (以下「デコード処理」) のあとで使用してください。
デコードエラーには一般的な 2 種類のエラーがあります。入力バイトシーケンスがこの文字セットにとって不当な場合は、「不正入力エラー」が発生します。入力バイトシーケンスは正当でも、これを有効な Unicode 文字にマップできない場合は、「マップ不可文字エラー」が発生します。
デコードエラーは、その種類のエラーに対して要求されたアクションに従って処理されます。こうしたアクションは、 不正入力エラーやマップ不可文字エラーが発生した場合、デフォルトのアクションとして、これらのエラーの このクラスは、エラーアクションの実装をはじめとするデコード処理のさまざまな部分を処理するように設計されています。特定の文字セット用のデコーダは、このクラスの具象サブクラスなので、標準デコードループをカプセル化する抽象メソッド、 このクラスのインスタンスを複数の並行スレッドで安全に使用することはできません。
decode
メソッドを呼び出すたびに、入力バッファ内のバイトがデコードされ、出力バッファに文字が書き込まれます。新たな入力要求を受け取ったり、出力バッファの容量が不足したり、デコードエラーが発生したりすると、decode
メソッドは終了し、終了の原因を示す CoderResult
オブジェクトを返します。呼び出し元は、このオブジェクトを確認して、入力バッファを格納するか、出力バッファをフラッシュするか、デコードエラーからの回復処理を実行して、呼び出しを再試行します。
CodingErrorAction
クラスのインスタンスに記述されています。たとえば、不正な入力の
、戻ってきた 無視
CoderResult
オブジェクトによる呼び出し元への
、不正な入力内容を代替文字列の現在値へ報告
といったアクションがあります。代替文字列の初期値は "\uFFFD" ですが、この値は 置き換え
replaceWith
メソッドを使って変更できます。
が行われます。不正入力エラーに対するアクションを変更したい場合は 報告
onMalformedInput
メソッド、マップ不可文字エラーに対するアクションを変更したい場合は onUnmappableCharacter
メソッドを使用します。
decodeLoop
を実装するだけで済みます。内部状態を保持するサブクラスは、これに加えて、flush
メソッドと reset
メソッドをオーバーライドする必要があります。
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 |
コンストラクタの詳細 |
protected CharsetDecoder(Charset cs, float averageCharsPerByte, float maxCharsPerByte)
averageCharsPerByte
- 入力バイトごとに生成される期待文字数を示す正の float 値maxCharsPerByte
- 入力バイトごとに生成される最大文字数を示す正の float 値
IllegalArgumentException
- 上記のパラメータの前提条件が満たされていない場合メソッドの詳細 |
public final Charset charset()
public final String replacement()
public final CharsetDecoder replaceWith(String newReplacement)
このメソッドは、implReplaceWith
メソッドを呼び出し、新しい代替値が条件に合っていることを確認したうえで、この値を渡します。
newReplacement
- 新しい代替値 (null 以外でゼロでない長さの値)
IllegalArgumentException
- 上記のパラメータの前提条件が満たされていない場合protected void implReplaceWith(String newReplacement)
このメソッドのデフォルト実装は、何の処理も行いません。このメソッドは、代替値の変更通知を要求するデコーダによってオーバーライドされます。
newReplacement
- public CodingErrorAction malformedInputAction()
public final CharsetDecoder onMalformedInput(CodingErrorAction newAction)
このメソッドは、implOnMalformedInput
メソッドを呼び出し、新しいアクションを渡します。
newAction
- 新しいアクション (null 以外)
IllegalArgumentException
- 上記のパラメータの前提条件が満たされていない場合protected void implOnMalformedInput(CodingErrorAction newAction)
このメソッドのデフォルト実装は、何の処理も行いません。このメソッドは、不正入力エラーに対するアクションの変更通知を要求するデコーダによってオーバーライドされます。
public CodingErrorAction unmappableCharacterAction()
public final CharsetDecoder onUnmappableCharacter(CodingErrorAction newAction)
このメソッドは、implOnUnmappableCharacter
メソッドを呼び出し、新しいアクションを渡します。
newAction
- 新しいアクション (null 以外)
IllegalArgumentException
- 上記のパラメータの前提条件が満たされていない場合protected void implOnUnmappableCharacter(CodingErrorAction newAction)
このメソッドのデフォルト実装は、何の処理も行いません。このメソッドは、マップできない文字エラーに対するアクションの変更通知を要求するデコーダによってオーバーライドされます。
public final float averageCharsPerByte()
public final float maxCharsPerByte()
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
IllegalStateException
- デコード処理がすでに進行中であり、その直前の処理が reset
メソッドの呼び出しでも、endOfInput パラメータに false を指定したこのメソッドの呼び出しでも、endOfInput パラメータに true を指定したこのメソッドの呼び出しでもないのに、デコード処理が不完全であることを示す戻り値が返された場合
CoderMalfunctionError
- decodeLoop メソッドの呼び出しによって予想外の例外がスローされた場合public final CoderResult flush(CharBuffer out)
内部の状態を保持する一部のデコーダは、入力シーケンスの読み込みが完了した時点で出力バッファに終端文字を書き込む必要があります。
追加の出力は、出力バッファの現在位置に書き込まれます。書き込まれる文字数は多くて out.remaining()
文字です。バッファの位置はこの文字数に従って増加しますが、マークとリミットはそのままです。
このメソッドは、正常に終了した場合 CoderResult.UNDERFLOW
を返します。出力バッファの容量が不足している場合は CoderResult.OVERFLOW
を返します。CoderResult.OVERFLOW
が返された場合は、容量に空きのある出力バッファを指定してこのメソッドを再度呼び出し、このデコード処理を完了させる必要があります。
このメソッドは、implFlush
メソッドを呼び出して、実際にフラッシュを行います。
out
- 出力 char バッファ
CoderResult.UNDERFLOW
または CoderResult.OVERFLOW
)
IllegalStateException
- 現在のデコード処理の直前の処理が reset
メソッドの呼び出しでも、endOfInput パラメータに true を指定した 3 つの引数を持つ decode
メソッドの呼び出しでもない場合protected CoderResult implFlush(CharBuffer out)
このメソッドのデフォルト実装は、何の処理も行わず常に CoderResult.UNDERFLOW
を返します。このメソッドは、入力シーケンスの読み込みが完了した時点で出力バッファに終端文字を書き込む必要があるデコーダによってオーバーライドされます。
out
- 出力 char バッファ
CoderResult.UNDERFLOW
または CoderResult.OVERFLOW
)public final CharsetDecoder reset()
このメソッドは、文字セット固有の状態をリセットします。また、文字セット固有のリセットアクションを実行するために implReset
メソッドを呼び出します。
protected void implReset()
このメソッドのデフォルト実装は、何の処理も行いません。このメソッドは、内部状態を保持するデコーダによってオーバーライドされます。
protected abstract CoderResult decodeLoop(ByteBuffer in, CharBuffer out)
このメソッドは、標準デコードループをカプセル化し、最大限のバイトをデコードします。デコードは、入力がなくなるか、出力バッファの容量が不足するか、デコードエラーが発生すると終了します。このメソッドは、結果解釈とエラー復旧を行う decode
メソッドによって呼び出されます。
バッファからの読み込み、バッファへの書き込みは、現在位置から行われます。読み取られるバイト数は多くて in.remaining()
バイト、書き込まれる文字数は多くて out.remaining()
文字です。バッファの位置は、読み取られたバイト数または書き込まれたバイト数に従って増加しますが、マークとリミットはそのままです。
このメソッドは、decode
メソッドと同様に、終了の原因を説明する CoderResult
オブジェクトを返します。このメソッドの実装の多くは、decode
メソッドを使って解釈される適切なオブジェクトを返すことにより、デコードエラーを処理します。これに対して、最適化された実装は、関連エラーアクションを調べて、そのアクション自体を実装します。
このメソッドの実装は、必要な入力を受け取るまで任意の前方検索を行います。検索中は CoderResult.UNDERFLOW
を返します。
in
- 入力 byte バッファout
- 出力 char バッファ
public final CharBuffer decode(ByteBuffer in) throws CharacterCodingException
このメソッドでは、すべてのデコード処理が実行されます。つまり、このメソッドを実行すると、デコーダがリセットされ、指定された byte バッファ内のバイトがデコードされ、最後にデコーダがフラッシュされます。デコード処理が現在進行中の場合は、このメソッドを呼び出さないでください。
in
- 入力 byte バッファ
IllegalStateException
- デコード処理がすでに進行中である場合
MalformedInputException
- 入力バッファの現在位置からのバイトシーケンスが、この文字セットにとって不当であり、不正入力エラーに対するアクションが CodingErrorAction.REPORT
である場合
UnmappableCharacterException
- 入力バッファの現在位置からのバイトシーケンスを同等の文字シーケンスにマップすることができず、マップ不可文字エラーに対するアクションが CodingErrorAction.REPORT
である場合
CharacterCodingException
public boolean isAutoDetecting()
このメソッドのデフォルト実装は、常に false を返します。自動検出デコーダによってオーバーライドされると、true を返すようになります。
public boolean isCharsetDetected()
デコード処理中にこのデコーダが自動検出エンコーディングを実装していれば、このメソッドは、入力バイトシーケンス内で特定の文字セットが検出されたことを示す true を返します。検出された場合は、その文字セットを取得するため、detectedCharset
メソッドが呼び出されます。
このメソッドの戻り値が false の場合でも、バイトのデコードが行われていることがあります。一部の自動検出デコーダは、特定の文字セットを選択しないで、入力バイトシーケンスの一部または全部をデコードします。
このメソッドのデフォルト実装は、常に UnsupportedOperationException
を返します。自動検出デコーダによってオーバーライドされると、入力文字セットが検出されたときに true を返すようになります。
UnsupportedOperationException
- このデコーダが自動検出文字セットを実装していない場合public Charset detectedCharset()
このメソッドは、このデコーダが自動検出文字セットを実装していれば、検出された実際の文字セットを返します。これ以降、現在のデコード処理が終了するまで同じ値を返します。読み込み入力バイト数が少なすぎて文字セットを特定できない場合は、IllegalStateException
をスローします。
このメソッドのデフォルト実装は、常に UnsupportedOperationException
を返します。自動検出デコーダによってオーバーライドされると、適切な値を返すようになります。
IllegalStateException
- 読み込みバイト数の不足のため、文字セットを特定できなかった場合
UnsupportedOperationException
- このデコーダが自動検出文字セットを実装していない場合
|
JavaTM 2 Platform Std. Ed. v1.4.0 |
||||||||||
前のクラス 次のクラス | フレームあり フレームなし | ||||||||||
概要: 入れ子 | フィールド | コンストラクタ | メソッド | 詳細: フィールド | コンストラクタ | メソッド |
Java、Java 2D、および JDBC は米国ならびにその他の国における米国 Sun Microsystems, Inc. の商標もしくは登録商標です。
Copyright 1993-2002 Sun Microsystems, Inc. 901 San Antonio Road
Palo Alto, California, 94303, U.S.A. All Rights Reserved.