java.nio.charset.CharsetDecoder
|
JavaTM Platform Standard Ed. 6 |
|||||||||
| 前のクラス 次のクラス | フレームあり フレームなし | |||||||||
| 概要: 入れ子 | フィールド | コンストラクタ | メソッド | 詳細: フィールド | コンストラクタ | メソッド | |||||||||
java.lang.Object
public abstract class CharsetDecoder
特定の文字セットで表現されたバイトシーケンスを 16 ビット Unicode 文字のシーケンスに変換するエンジンです。
入力バイトシーケンスは、単一の byte バッファーまたは一連の byte バッファーとして提供されます。出力文字シーケンスは、単一の文字バッファーまたは一連の文字バッファーに書き込まれます。デコーダを使用する際には、必ず次のメソッド呼び出し手順 (以下「デコード処理」) に従ってください。
デコードエラーには一般的な 2 種類のエラーがあります。入力バイトシーケンスがこの文字セットにとって不当な場合は、「不正入力エラー」が発生します。入力バイトシーケンスは正当でも、これを有効な Unicode 文字にマップできない場合は、「マップ不可文字エラー」が発生します。
特定のデコードエラーがどのように処理されるかは、そのエラーに対して要求されるアクションによって決まります。 これらのアクションは、 不正入力エラーやマップ不可文字エラーが発生した場合、デフォルトのアクションとして、これらのエラーの { このクラスは、エラーアクションの実装をはじめとするデコード処理の詳細の多くを処理するように設計されています。特定の文字セットに対するデコーダ (このクラスの具象サブクラス) が実装する必要があるのは、標準デコードループをカプセル化する抽象メソッド このクラスのインスタンスは、複数のスレッドで並行して使用することはできません。
decode メソッドを呼び出すたびに、入力バッファー内のバイトが文字にデコードされ、出力バッファーに書き込まれます。新たな入力要求を受け取ったり、出力バッファーの容量が不足したり、デコードエラーが発生したりすると、decode メソッドは終了し、終了の原因を示す CoderResult オブジェクトを返します。呼び出し元は、このオブジェクトを確認して、入力バッファーをいっぱいにするか、出力バッファーをフラッシュするか、デコードエラーからの回復処理を実行して、呼び出しを再試行します。
CodingErrorAction クラスのインスタンスによって記述されます。利用可能なエラーアクションは、エラー入力の 無視CoderResult オブジェクトを経由した呼び出し元へのエラーの 報告置換replaceWith メソッドを使用すると変更できます。
報告onMalformedInput メソッドを、マップ不可文字エラーに対するアクションを変更する場合は onUnmappableCharacter メソッドを、それぞれ使用します。
decodeLoop だけです。これに加え、内部状態を保持するサブクラスは、implFlush メソッドと implReset メソッドをオーバーライドする必要があります。
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 |
| コンストラクタの詳細 |
|---|
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 - 出力文字バッファー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 - 出力文字バッファー
CoderResult.UNDERFLOW または CoderResult.OVERFLOW
IllegalStateException - 現在のデコード処理の直前の処理が、flush メソッドの呼び出しでも、endOfInput パラメータに true を指定した 3 つの引数を持つ decode メソッドの呼び出しでもない場合protected CoderResult implFlush(CharBuffer out)
このメソッドのデフォルト実装は、何の処理も行わず、常に CoderResult.UNDERFLOW を返します。入力シーケンスの読み込み完了後に出力バッファーに最後の文字を書き込む必要があるデコーダでは、このメソッドをオーバーライドする必要があります。
out - 出力文字バッファー
CoderResult.UNDERFLOW または CoderResult.OVERFLOWpublic 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 - 出力文字バッファー
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 Platform Standard Ed. 6 |
|||||||||
| 前のクラス 次のクラス | フレームあり フレームなし | |||||||||
| 概要: 入れ子 | フィールド | コンストラクタ | メソッド | 詳細: フィールド | コンストラクタ | メソッド | |||||||||
Copyright 2009 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms. Documentation Redistribution Policy も参照してください。