|
JavaTM 2 Platform Std. Ed. v1.4.0 |
||||||||||
前のクラス 次のクラス | フレームあり フレームなし | ||||||||||
概要: 入れ子 | フィールド | コンストラクタ | メソッド | 詳細: フィールド | コンストラクタ | メソッド |
java.lang.Object | +--java.nio.charset.CharsetEncoder
16 ビット Unicode 文字のシーケンスを特定の文字セットで表現されたバイトシーケンスに変換するエンジンです。
入力バイトシーケンスは、char バッファなどのバッファから渡されます。出力文字シーケンスは、byte バッファなどのバッファに書き込まれます。エンコーダは、必ず次のメソッド呼び出しシーケンス (以下「エンコード処理」) のあとで使用してください。
エンコードエラーには一般的な 2 種類のエラーがあります。入力文字シーケンスが正当な 16 ビット Unicode シーケンスでない場合は、「不正入力エラー」が発生します。入力文字シーケンスは正当でも、これを有効なバイトシーケンスにマップできない場合は、「マップ不可文字エラー」が発生します。
エンコードエラーは、その種類のエラーに対して要求されたアクションに従って処理されます。こうしたアクションは、 不正入力エラーやマップ不可文字エラーが発生した場合、デフォルトのアクションとして、これらのエラーの このクラスは、エラーアクションの実装をはじめとするエンコード処理のさまざまな部分を処理するように設計されています。特定の文字セット用のエンコーダは、このクラスの具象サブクラスなので、標準エンコードループをカプセル化する抽象メソッド、 このクラスのインスタンスを複数の並行スレッドで安全に使用することはできません。
encode
メソッドを呼び出すたびに、入力バッファ内の文字がエンコードされ、出力バッファにバイトが書き込まれます。新たな入力要求を受け取ったり、出力バッファの容量が不足したり、エンコードエラーが発生したりすると、encode
メソッドは終了し、終了の原因を示す CoderResult
オブジェクトを返します。呼び出し元は、このオブジェクトを確認して、入力バッファを格納するか、出力バッファをフラッシュするか、エンコードエラーからの回復処理を実行して、呼び出しを再試行します。
CodingErrorAction
クラスのインスタンスに記述されています。たとえば、不正入力の
、無視
CoderResult
オブジェクトによる呼び出し元への
、不正入力内容を代替バイト配列の現在値へ報告
といったアクションがあります。代替値は最初、エンコーダのデフォルトの値に設定されています。この値は、多くの場合、{ (byte)'?' } という初期値を持っていますが、置き換え
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 以外、ゼロでない長さかつ 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 以外、ゼロ以外の長さかつ 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
である場合
CharacterCodingException
public boolean canEncode(char c)
指定された文字がサロゲート文字である場合、このメソッドは false を返します。サロゲート文字は、上位サロゲートと下位サロゲートの組み合わせがそろわなければ解釈できません。文字シーケンスのエンコードが可能であるかどうかは、canEncode(CharSequence)
メソッドを使ってテストできます。
このメソッドは、このエンコーダの状態を変更します。すでにエンコード処理が進行している場合は、このメソッドを呼び出さないでください。
このメソッドのデフォルト実装はあまり効率がよくありません。通常、この性能を改善するためには、オーバーライドが必要です。
IllegalStateException
- エンコード処理がすでに進行中である場合public boolean canEncode(CharSequence cs)
このメソッドが特定の文字シーケンスに対して false を返す場合は、エンコード処理をすべて実行すれば、シーケンスがエンコードされない理由を詳しく調べることができます。
このメソッドは、このエンコーダの状態を変更します。すでにエンコード処理が進行している場合は、このメソッドを呼び出さないでください。
このメソッドのデフォルト実装はあまり効率がよくありません。通常、この性能を改善するためには、オーバーライドが必要です。
IllegalStateException
- エンコード処理がすでに進行中である場合
|
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.