java.nio.charset.CharsetEncoder
|
JavaTM 2 Platform Standard Ed. 5.0 |
|||||||||
| 前のクラス 次のクラス | フレームあり フレームなし | |||||||||
| 概要: 入れ子 | フィールド | コンストラクタ | メソッド | 詳細: フィールド | コンストラクタ | メソッド | |||||||||
java.lang.Object
public abstract class CharsetEncoder
16 ビット Unicode 文字のシーケンスを特定の文字セットで表現されたバイトシーケンスに変換するエンジンです。
入力文字シーケンスは、単一の char バッファまたは一連の char バッファとして提供されます。出力バイトシーケンスは、単一の byte バッファまたは一連の byte バッファに書き込まれます。エンコーダを使用する際には、必ず次のメソッド呼び出し手順 (以下「エンコード処理」) に従ってください。
エンコードエラーには一般的な 2 種類のエラーがあります。入力文字シーケンスが正当な 16 ビット Unicode シーケンスでない場合は、「不正入力エラー」が発生します。入力文字シーケンスは正当でも、これを有効なバイトシーケンスにマップできない場合は、「マップ不可文字エラー」が発生します。
特定のエンコードエラーがどのように処理されるかは、そのタイプのエラーに対して要求されるアクションによって決まります。これらのアクションは、 不正入力エラーやマップ不可文字エラーに対するデフォルトのアクションは、エラーの このクラスは、エラーアクションの実装をはじめとするエンコード処理の詳細の多くを処理するように設計されています。特定の文字セットに対するエンコーダ (このクラスの具象サブクラス) が実装する必要があるのは、標準エンコードループをカプセル化する抽象メソッド このクラスのインスタンスは、複数のスレッドで同時に使用することはできません。
encode メソッドを呼び出すたびに、入力バッファ内の可能なかぎり多くの文字がエンコードされ、その結果が出力バッファに書き込まれます。encode メソッドが終了するのは、新たな入力が必要になった場合、出力バッファの容量が不足した場合、またはエンコードエラーが発生した場合のいずれかです。いずれの場合も、終了した理由を記述した CoderResult オブジェクトが返されます。呼び出し元は、このオブジェクトの内容を確認したうえで、入力バッファへのデータの格納、出力バッファのフラッシュ、またはエンコードエラーからの回復の試みができます。そしてその後、このメソッドを再度呼び出せます。
CodingErrorAction クラスのインスタンスによって記述されます。利用可能なエラーアクションは、エラー入力の 無視CoderResult オブジェクトを経由した呼び出し元へのエラーの 報告置換replaceWith メソッドを使用すると変更できます。
報告onMalformedInput メソッドを、マップ不可文字エラーに対するアクションを変更する場合は onUnmappableCharacter メソッドを、それぞれ使用します。
encodeLoop だけです。これに加え、内部状態を保持するサブクラスは、flush メソッドと reset メソッドをオーバーライドする必要があります。
ByteBuffer,
CharBuffer,
Charset,
CharsetDecoder
| コンストラクタの概要 | |
|---|---|
protected |
CharsetEncoder(Charset cs,
float averageBytesPerChar,
float maxBytesPerChar)
新しいエンコーダを初期化します。 |
protected |
CharsetEncoder(Charset cs,
float averageBytesPerChar,
float maxBytesPerChar,
byte[] replacement)
新しいエンコーダを初期化します。 |
| メソッドの概要 | |
|---|---|
float |
averageBytesPerChar()
入力文字ごとに生成される平均バイト数を返します。 |
boolean |
canEncode(char c)
このエンコーダが指定された文字をエンコードできるかどうかを判断します。 |
boolean |
canEncode(CharSequence cs)
このエンコーダが指定された文字シーケンスをエンコードできるかどうかを判断します。 |
Charset |
charset()
このエンコーダを作成した文字セットを返します。 |
ByteBuffer |
encode(CharBuffer in)
単一の入力 char バッファのコンテンツを新しく割り当てられた byte バッファ内にエンコードする簡易メソッドです。 |
CoderResult |
encode(CharBuffer in,
ByteBuffer out,
boolean endOfInput)
指定された入力バッファ内の文字を最大限エンコードし、指定された出力バッファに結果を書き込みます。 |
protected abstract CoderResult |
encodeLoop(CharBuffer in,
ByteBuffer out)
1 個以上の文字 1 個以上のバイトへエンコードします。 |
CoderResult |
flush(ByteBuffer out)
このエンコーダをフラッシュします。 |
protected CoderResult |
implFlush(ByteBuffer out)
このエンコーダをフラッシュします。 |
protected void |
implOnMalformedInput(CodingErrorAction newAction)
不正入力エラーに対する、このエンコーダのアクションが変更されたことを報告します。 |
protected void |
implOnUnmappableCharacter(CodingErrorAction newAction)
マップ不可文字エラーに対する、このエンコーダのアクションが変更されたことを報告します。 |
protected void |
implReplaceWith(byte[] newReplacement)
このエンコーダの置換値が変更されたことを報告します。 |
protected void |
implReset()
このエンコーダをリセットし、文字セット固有の内部の状態をクリアします。 |
boolean |
isLegalReplacement(byte[] repl)
指定されたバイト配列が、このエンコーダの置換値として正当かどうかを判断します。 |
CodingErrorAction |
malformedInputAction()
不正入力エラーに対する、このエンコーダの現在のアクションを返します。 |
float |
maxBytesPerChar()
入力文字ごとに生成される最大バイト数を返します。 |
CharsetEncoder |
onMalformedInput(CodingErrorAction newAction)
不正入力エラーに対する、このエンコーダのアクションを変更します。 |
CharsetEncoder |
onUnmappableCharacter(CodingErrorAction newAction)
マップ不可文字エラーに対する、このエンコーダのアクションを変更します。 |
byte[] |
replacement()
このエンコーダの置換値を返します。 |
CharsetEncoder |
replaceWith(byte[] newReplacement)
このエンコーダの置換値を変更します。 |
CharsetEncoder |
reset()
このエンコーダをリセットし、内部の状態をクリアします。 |
CodingErrorAction |
unmappableCharacterAction()
マップ不可文字エラーに対する、このエンコーダの現在のアクションを返します。 |
| クラス java.lang.Object から継承されたメソッド |
|---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
| コンストラクタの詳細 |
|---|
protected CharsetEncoder(Charset cs,
float averageBytesPerChar,
float maxBytesPerChar,
byte[] replacement)
averageBytesPerChar - 入力文字ごとに生成されるバイト数の期待値を示す正の float 値maxBytesPerChar - 入力文字ごとに生成されるバイト数の最大値を示す正の float 値replacement - 置換の初期値。null でなく、長さは 1 以上 maxBytesPerChar 以下であり、IllegalArgumentException - 上記のパラメータの前提条件が満たされていない場合
protected CharsetEncoder(Charset cs,
float averageBytesPerChar,
float maxBytesPerChar)
averageBytesPerChar - 入力文字ごとに生成されるバイト数の期待値を示す正の float 値maxBytesPerChar - 入力文字ごとに生成されるバイト数の最大値を示す正の float 値
IllegalArgumentException - 上記のパラメータの前提条件が満たされていない場合| メソッドの詳細 |
|---|
public final Charset charset()
public final byte[] replacement()
public final CharsetEncoder replaceWith(byte[] newReplacement)
このメソッドは、新しい置換値が条件に合っていることを確認したうえで、その値を指定して implReplaceWith メソッドを呼び出します。
newReplacement - 新しい置換値。null でなく、長さは 1 以上かつ maxBytesPerChar メソッドの戻り値以下であり、正当IllegalArgumentException - 上記のパラメータの前提条件が満たされていない場合protected void implReplaceWith(byte[] newReplacement)
このメソッドのデフォルト実装では何の処理も行われません。置換値の変更通知を必要とするエンコーダでは、このメソッドをオーバーライドする必要があります。
newReplacement - public boolean isLegalReplacement(byte[] repl)
置換値は、このエンコーダの文字セットで表現できる正当なバイトシーケンスである場合に限り正当です。すなわち、この値を 1 個以上の 16 ビット Unicode 文字にデコードできる必要があります。
このメソッドのデフォルト実装は効率があまりよくありません。通常、この性能を改善するためには、オーバーライドが必要です。
repl - テストするバイト配列
public CodingErrorAction malformedInputAction()
public final CharsetEncoder onMalformedInput(CodingErrorAction newAction)
このメソッドは、新しいアクションを指定して implOnMalformedInput メソッドを呼び出します。
newAction - 新しいアクション (null 以外)
IllegalArgumentException - 上記のパラメータの前提条件が満たされていない場合protected void implOnMalformedInput(CodingErrorAction newAction)
このメソッドのデフォルト実装では何の処理も行われません。不正入力エラーに対するアクションの変更通知を必要とするエンコーダでは、このメソッドをオーバーライドする必要があります。
public CodingErrorAction unmappableCharacterAction()
public final CharsetEncoder onUnmappableCharacter(CodingErrorAction newAction)
このメソッドは、新しいアクションを指定して implOnUnmappableCharacter メソッドを呼び出します。
newAction - 新しいアクション (null 以外)
IllegalArgumentException - 上記のパラメータの前提条件が満たされていない場合protected void implOnUnmappableCharacter(CodingErrorAction newAction)
このメソッドのデフォルト実装では何の処理も行われません。マップ不可文字エラーに対するアクションの変更通知を必要とするエンコーダでは、このメソッドをオーバーライドする必要があります。
public final float averageBytesPerChar()
public final float maxBytesPerChar()
public final CoderResult encode(CharBuffer in,
ByteBuffer out,
boolean endOfInput)
バッファに対する読み書きは、各バッファの現在位置から行われます。読み取られる文字数は多くて in.remaining() バイト、書き込まれるバイト数は多くて out.remaining() 文字です。バッファの位置は、読み取られた文字数または書き込まれたバイト数に従って増加しますが、マークとリミットはそのままです。
このメソッドは、入力バッファからの文字の読み込みと出力バッファへのバイトの書き込みに加え、終了の理由を説明する次のような CoderResult オブジェクトを返します。
CoderResult.UNDERFLOW。入力バッファ内のバイトが最大限エンコードされたことを示す。入力バッファ内に文字が残っておらず、呼び出し元からの新たな入力もなければエンコード処理は完了する。完了できない場合は、入力不足により処理が続行できなかったということなので、さらに入力データを準備したうえでこのメソッドを再度呼び出す必要がある
CoderResult.OVERFLOW。出力バッファに空きがなくなったことを示す。まだ空きのある出力バッファを指定してこのメソッドを再度呼び出す必要がある
不正入力length メソッドを呼び出すことで特定できる。ただし、これが当てはまるのは、このデコーダの 不正入力エラーに対するアクションCodingErrorAction.REPORT である場合にかぎられる。それ以外の場合、不正入力は要求に応じて無視されるか、別の値に置換される
マップ不可文字length メソッドを呼び出すことで特定できる。ただし、これが当てはまるのは、このエンコーダの マップ不可文字エラーに対するアクションCodingErrorAction.REPORT である場合にかぎられる。それ以外の場合、不正入力は要求に応じて無視されるか、別の値に置換される
endOfInput パラメータは、指定された入力バッファに呼び出し元からの新たな入力があるかどうかをこのメソッドに通知します。まだ入力の可能性がある場合、呼び出し元はこのパラメータに false を渡す必要があります。これ以上入力の可能性がない場合は true を渡します。呼び出し元から false を渡したあとで入力がなかったとしても、問題はありません。しかし、呼び出しシーケンスにおける最後の呼び出しでは、true を渡さなければなりません。これ以降、まだエンコードされていない入力は「不正」と見なされるようになります。
このメソッドは、まず encodeLoop メソッドを呼び出します。その後、その結果を解釈し、エラー条件の処理を済ませたあと、必要に応じて再度そのメソッドを呼び出します。
in - 入力 char バッファout - 出力 byte バッファendOfInput - 呼び出し元が指定されたバッファにこれ以上の入力文字を追加する可能性がない場合に限り true
IllegalStateException - エンコード処理がすでに進行中であり、その直前の処理が reset メソッドの呼び出しでも、endOfInput パラメータに false を指定したこのメソッドの呼び出しでも、endOfInput パラメータに true を指定したこのメソッドの呼び出しでもないのに、エンコード処理が不完全であることを示す戻り値が返された場合
CoderMalfunctionError - encodeLoop メソッドの呼び出しによって予想外の例外がスローされた場合public final CoderResult flush(ByteBuffer out)
内部の状態を保持する一部のエンコーダは、入力シーケンスの読み込みが完了した時点で、出力バッファに終端バイトを書き込む必要があります。
追加の出力は、出力バッファの現在位置に書き込まれます。書き込まれるバイト数は多くて out.remaining() バイトです。バッファの位置はこのバイト数に従って増加しますが、マークとリミットはそのままです。
このメソッドは、正常に終了した場合 CoderResult.UNDERFLOW を返します。出力バッファの容量が不足した場合は CoderResult.OVERFLOW を返します。CoderResult.OVERFLOW が返された場合は、より多くの空き領域を持つ出力バッファを指定してこのメソッドを再度呼び出し、このエンコード処理を完了させる必要があります。
このメソッドは、implFlush メソッドを呼び出すことで、実際のフラッシュ処理を行います。
out - 出力 byte バッファ
CoderResult.UNDERFLOW、CoderResult.OVERFLOW のいずれか
IllegalStateException - 現在のエンコード処理の直前の処理が、reset メソッドの呼び出しでも、endOfInput パラメータに true を指定した 3 つの引数を持つ encode メソッドの呼び出しでもない場合protected CoderResult implFlush(ByteBuffer out)
このメソッドのデフォルト実装は、何の処理も行わず、常に CoderResult.UNDERFLOW を返します。入力シーケンスの読み込み完了後に出力バッファに最後のバイトを書き込む必要があるエンコーダでは、このメソッドをオーバーライドする必要があります。
out - 出力 byte バッファ
CoderResult.UNDERFLOW、CoderResult.OVERFLOW のいずれかpublic final CharsetEncoder reset()
このメソッドは、文字セットに依存しない状態をリセットします。また、文字セット固有のリセットアクションを実行するために、 implReset メソッドも呼び出します。
protected void implReset()
このメソッドのデフォルト実装では何の処理も行われません。内部状態を保持するエンコーダでは、このメソッドをオーバーライドする必要があります。
protected abstract CoderResult encodeLoop(CharBuffer in,
ByteBuffer out)
このメソッドは、基本的なエンコードループをカプセル化し、入力がなくなるか、出力バッファの容量が不足するか、またはエンコードエラーが発生するまで最大限の文字をエンコードします。このメソッドは、結果解釈とエラー復旧を行う encode メソッドによって呼び出されます。
バッファに対する読み書きは、各バッファの現在位置から行われます。読み取られる文字数は多くて in.remaining() バイト、書き込まれるバイト数は多くて out.remaining() 文字です。バッファの位置は、読み取られた文字数または書き込まれたバイト数に従って増加しますが、マークとリミットはそのままです。
このメソッドは、encode メソッドと同様に、終了の理由を記述した CoderResult オブジェクトを返します。このメソッドの実装の大部分は、encode メソッドでの解釈に必要な結果オブジェクトを返すことで、エンコードエラーを処理します。これに対し、最適化された実装は、関連エラーアクションを調べ、そのアクションを自身で実行する可能性もあります。
このメソッドの実装によっては、十分な量の入力を受け取るまで任意の前方検索を行い、CoderResult.UNDERFLOW を返し続ける可能性があります。
in - 入力 char バッファout - 出力 byte バッファ
public final ByteBuffer encode(CharBuffer in)
throws CharacterCodingException
このメソッドは、エンコード処理全体を実装しています。つまり、このメソッドは、このエンコーダをリセットしたあと、指定された char バッファ内の文字をエンコードし、最後にこのエンコーダをフラッシュします。したがって、エンコード処理がすでに進行中の場合は、このメソッドを呼び出さないでください。
in - 入力 char バッファ
IllegalStateException - エンコード処理がすでに進行中である場合
MalformedInputException - 入力バッファの現在位置から始まる文字シーケンスが正当な 16 ビット Unicode シーケンスでなく、不正入力エラーに対するアクションが CodingErrorAction.REPORT である場合
UnmappableCharacterException - 入力バッファの現在位置から始まる文字シーケンスを同等のバイトシーケンスにマップすることができず、マップ不可文字エラーに対するアクションが CodingErrorAction.REPORT である場合
CharacterCodingExceptionpublic boolean canEncode(char c)
指定された文字がサロゲート文字である場合、このメソッドは false を返します。サロゲート文字を解釈できるのは、上位サロゲートのあとに下位サロゲートが続くかたちのペアになっている場合だけです。文字シーケンスのエンコードが可能であるかどうかは、canEncode(CharSequence) メソッドを使ってテストできます。
このメソッドは、このエンコーダの状態を変更します。すでにエンコード処理が進行している場合は、このメソッドを呼び出さないでください。
このメソッドのデフォルト実装はあまり効率がよくありません。通常、この性能を改善するためには、オーバーライドが必要です。
IllegalStateException - エンコード処理がすでに進行中である場合public boolean canEncode(CharSequence cs)
このメソッドが特定の文字シーケンスに対して false を返す場合は、エンコード処理をすべて実行すれば、シーケンスがエンコードされない理由を詳しく調べることができます。
このメソッドは、このエンコーダの状態を変更します。すでにエンコード処理が進行している場合は、このメソッドを呼び出さないでください。
このメソッドのデフォルト実装はあまり効率がよくありません。通常、この性能を改善するためには、オーバーライドが必要です。
IllegalStateException - エンコード処理がすでに進行中である場合
|
JavaTM 2 Platform Standard Ed. 5.0 |
|||||||||
| 前のクラス 次のクラス | フレームあり フレームなし | |||||||||
| 概要: 入れ子 | フィールド | コンストラクタ | メソッド | 詳細: フィールド | コンストラクタ | メソッド | |||||||||
Copyright 2004 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms. Documentation Redistribution Policy も参照してください。