java.nio.charset.CharsetDecoder
|
JavaTM 2 Platform Standard Ed. 5.0 |
|||||||||
| 前のクラス 次のクラス | フレームあり フレームなし | |||||||||
| 概要: 入れ子 | フィールド | コンストラクタ | メソッド | 詳細: フィールド | コンストラクタ | メソッド | |||||||||
java.lang.Object
public abstract class CharsetDecoder
特定の文字セットで表現されたバイトシーケンスを 16 ビット Unicode 文字のシーケンスに変換するエンジンです。
入力バイトシーケンスは、単一の byte バッファまたは一連の byte バッファとして提供されます。出力文字シーケンスは、単一の char バッファまたは一連の char バッファに書き込まれます。デコーダを使用する際には、必ず次のメソッド呼び出し手順 (以下「デコード処理」) に従ってください。
デコードエラーには一般的な 2 種類のエラーがあります。入力バイトシーケンスがこの文字セットにとって不当な場合は、「不正入力エラー」が発生します。入力バイトシーケンスは正当でも、これを有効な Unicode 文字にマップできない場合は、「マップ不可文字エラー」が発生します。
特定のデコードエラーがどのように処理されるかは、そのエラーに対して要求されるアクションによって決まります。これらのアクションは、 不正入力エラーやマップ不可文字エラーに対するデフォルトのアクションは、エラーの このクラスは、エラーアクションの実装をはじめとするデコード処理の詳細の多くを処理するように設計されています。特定の文字セットに対するデコーダ (このクラスの具象サブクラス) が実装する必要があるのは、標準デコードループをカプセル化する抽象メソッド このクラスのインスタンスは、複数のスレッドで同時に使用することはできません。
decode メソッドを呼び出すたびに、入力バッファ内の可能なかぎり多くのバイトがデコードされ、その結果が出力バッファに書き込まれます。decode メソッドが終了するのは、新たな入力が必要になった場合、出力バッファの容量が不足した場合、またはデコードエラーが発生した場合のいずれかです。いずれの場合も、終了した理由を記述した CoderResult オブジェクトが返されます。呼び出し元は、このオブジェクトの内容を確認したうえで、入力バッファへのデータの格納、出力バッファのフラッシュ、またはデコードエラーからの回復の試みができます。そしてその後、このメソッドを再度呼び出せます。
CodingErrorAction クラスのインスタンスによって記述されます。利用可能なエラーアクションは、エラー入力の 無視CoderResult オブジェクトを経由した呼び出し元へのエラーの 報告置換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 であったり、長さが 0 であってはならない
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 である場合
CharacterCodingExceptionpublic boolean isAutoDetecting()
このメソッドのデフォルト実装は、常に false を返します。自動検出デコーダでは、このメソッドをオーバーライドして true を返すようにする必要があります。
public boolean isCharsetDetected()
このデコーダが自動検出文字セットを実装している場合、デコード処理のある時点からこのメソッドから true が返されるようになりますが、これは、入力バイトシーケンス内で特定の文字セットが検出されたことを示します。それ以降は、detectedCharset メソッドを呼び出すことで、検出された文字セットを取得できます。
このメソッドの戻り値が false であっても、バイトのデコードが行われていることがあります。一部の自動検出デコーダは、特定の文字セットを選択しないまま入力バイトシーケンスの一部または全部をデコードすることができます。
このメソッドのデフォルト実装は、常に UnsupportedOperationException を返します。自動検出デコーダの場合、入力文字セットが検出された時点で true を返すように、このメソッドをオーバーライドする必要があります。
UnsupportedOperationException - このデコーダが自動検出文字セットを実装していない場合public Charset detectedCharset()
このデコーダが自動検出文字セットを実装している場合、このメソッドは、実際の文字セットが検出された時点でその文字セットを返します。これ以降、現在のデコード処理が終了するまで同じ値を返します。読み込み入力バイト数が少なすぎて文字セットを特定できていない場合、このメソッドは IllegalStateException をスローします。
このメソッドのデフォルト実装は、常に UnsupportedOperationException を返します。自動検出デコーダの場合、適切な値を返すようにこのメソッドをオーバーライドする必要があります。
IllegalStateException - 読み込みバイト数の不足のため、文字セットを特定できなかった場合
UnsupportedOperationException - このデコーダが自動検出文字セットを実装していない場合
|
JavaTM 2 Platform Standard Ed. 5.0 |
|||||||||
| 前のクラス 次のクラス | フレームあり フレームなし | |||||||||
| 概要: 入れ子 | フィールド | コンストラクタ | メソッド | 詳細: フィールド | コンストラクタ | メソッド | |||||||||
Copyright 2004 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms. Documentation Redistribution Policy も参照してください。