public abstract class CharsetEncoder extends Object
入力文字シーケンスは、単一の文字バッファまたは一連の文字バッファとして提供されます。出力バイト・シーケンスは、単一のbyteバッファまたは一連のbyteバッファに書き込まれます。エンコーダを使用する際には、必ず次のメソッド呼出し手順(以下、エンコード処理)に従ってください。
エンコーダをはじめて使用する場合以外は、reset
メソッドを使用してエンコーダをリセットします。
追加入力がある限りencode
メソッドを0回以上呼び出し、各呼出しの間にendOfInput引数にfalseを渡し、入力バッファにデータを格納し、出力バッファをフラッシュします。
encode
メソッドを最後に1回呼び出し、endOfInput引数にtrueを渡します。
エンコーダが内部状態を出力バッファへフラッシュできるように、flush
メソッドを呼び出します。
encode
メソッドを呼び出すたびに、入力バッファ内の文字がバイトにエンコードされ、出力バッファに書き込まれます。新たな入力要求を受け取ったり、出力バッファの容量が不足したり、エンコード・エラーが発生したりすると、encode
メソッドは終了します。いずれの場合でも、終了の理由を説明するためにCoderResult
オブジェクトが返されます。呼出し元は、このオブジェクトを確認して、入力バッファをいっぱいにするか、出力バッファをフラッシュするか、エンコード・エラーからの回復処理を実行して、呼出しを再試行します。
エンコード・エラーには一般的な2種類のエラーがあります。入力文字シーケンスが正当な16ビットUnicodeシーケンスでない場合は、不正入力エラーが発生します。入力文字シーケンスは正当でも、これを指定された文字セット内の有効なバイト・シーケンスにマップできない場合は、マップ不可文字エラーが発生します。
特定のエンコード・エラーがどのように処理されるかは、その種類のエラーに対して要求されるアクションによって決まります。これらのアクションは、CodingErrorAction
クラスのインスタンスによって記述されます。利用可能なエラー・アクションは、エラー入力の無視、戻り値のCoderResult
オブジェクトを経由した呼出し元へのエラーの報告、または現在の置換バイト配列値によるエラー入力の置換です。置換値は、まずエンコーダのデフォルトの置換値に設定されます。その初期値は通常、{ (byte)'?' }ですが、そうならない場合もあります。この値は、replaceWith
メソッドを使用して変更できます。
入力形式が正しくないエラーやマップ不可文字エラーが発生した場合、デフォルトのアクションとして、これらのエラーの報告が行われます。入力形式が正しくないエラーに対するアクションを変更する場合はonMalformedInput
メソッドを、マップ不可文字エラーに対するアクションを変更する場合はonUnmappableCharacter
メソッドを、それぞれ使用します。
このクラスは、エラー・アクションの実装をはじめとするエンコード処理の詳細の多くを処理するように設計されています。特定の文字セットに対するエンコーダ(このクラスの具象サブクラス)が実装する必要があるのは、標準エンコード・ループをカプセル化する抽象メソッドencodeLoop
だけです。これに加え、内部状態を保持するサブクラスは、implFlush
メソッドとimplReset
メソッドをオーバーライドする必要があります。
このクラスのインスタンスは、複数のスレッドで並行して使用することはできません。
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)
単一の入力文字バッファのコンテンツを新しく割り当てられた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()
マップ不可文字エラーに対する、このエンコーダの現在のアクションを返します。
|
protected CharsetEncoder(Charset cs, float averageBytesPerChar, float maxBytesPerChar, byte[] replacement)
cs
- このエンコーダを作成した文字セットaverageBytesPerChar
- 入力文字ごとに生成される予想バイト数を示す正のfloat値maxBytesPerChar
- 入力文字ごとに生成される最大バイト数を示す正のfloat値replacement
- 置換の初期値。nullでなく、長さが1以上maxBytesPerChar以下の正当な値でなければならない。IllegalArgumentException
- 上記のパラメータの前提条件が満たされていない場合protected CharsetEncoder(Charset cs, float averageBytesPerChar, float maxBytesPerChar)
cs
- このエンコーダを作成した文字セット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)
このメソッドのデフォルト実装では何の処理も行われません。不正入力エラーに対するアクションの変更通知を必要とするエンコーダでは、このメソッドをオーバーライドする必要があります。
newAction
- 新しいアクションpublic CodingErrorAction unmappableCharacterAction()
public final CharsetEncoder onUnmappableCharacter(CodingErrorAction newAction)
このメソッドは、新しいアクションを渡してimplOnUnmappableCharacter
メソッドを呼び出します。
newAction
- 新しいアクション(null以外)IllegalArgumentException
- 上記のパラメータの前提条件が満たされていない場合protected void implOnUnmappableCharacter(CodingErrorAction newAction)
このメソッドのデフォルト実装では何の処理も行われません。マップ不可文字エラーに対するアクションの変更通知を必要とするエンコーダでは、このメソッドをオーバーライドする必要があります。
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
- 入力文字バッファout
- 出力byteバッファendOfInput
- 呼出し元が指定されたバッファにこれ以上の入力文字を追加する可能性がない場合に限りtrueIllegalStateException
- エンコード処理がすでに進行中であり、その直前の処理がreset
メソッドの呼出しでも、endOfInputパラメータにfalseを指定したこのメソッドの呼出しでも、endOfInputパラメータにtrueを指定したこのメソッドの呼出しでもないのに、エンコード処理が不完全であることを示す戻り値が返された場合CoderMalfunctionError
- encodeLoopメソッドの呼出しによって予期しない例外がスローされた場合public final CoderResult flush(ByteBuffer out)
内部の状態を保持する一部のエンコーダは、入力シーケンスの読込みが完了した時点で、出力バッファに終端バイトを書き込む必要があります。
追加の出力は、出力バッファの現在位置に書き込まれます。書き込まれるバイト数は多くてout.remaining()
バイトです。バッファの位置はこのバイト数に従って増加しますが、マークとリミットはそのままです。
このメソッドは、正常に終了した場合CoderResult.UNDERFLOW
を返します。出力バッファの容量が不足した場合はCoderResult.OVERFLOW
を返します。この場合は、より多くの空き領域を持つ出力バッファを指定してこのメソッドを再度呼び出し、このエンコード処理を完了させる必要があります。
このエンコーダのフラッシュ後にこのメソッドを呼び出しても、何の効果もありません。
このメソッドは、implFlush
メソッドを呼び出すことで、実際のフラッシュ処理を行います。
out
- 出力byteバッファCoderResult.UNDERFLOW
またはCoderResult.OVERFLOW
IllegalStateException
- 現在のエンコード処理の直前の処理が、flush
メソッドの呼出しでも、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
- 入力文字バッファout
- 出力byteバッファpublic final ByteBuffer encode(CharBuffer in) throws CharacterCodingException
このメソッドは、エンコード処理全体を実装しています。つまり、このメソッドは、このエンコーダをリセットしたあと、指定された文字バッファ内の文字をエンコードし、最後にこのエンコーダをフラッシュします。したがって、エンコード処理がすでに進行中の場合は、このメソッドを呼び出さないでください。
in
- 入力文字バッファIllegalStateException
- エンコード処理がすでに進行中である場合MalformedInputException
- 入力バッファの現在位置から始まる文字シーケンスが正当な16ビットUnicodeシーケンスでなく、不正入力エラーに対するアクションがCodingErrorAction.REPORT
である場合UnmappableCharacterException
- 入力バッファの現在位置から始まる文字シーケンスを同等のバイト・シーケンスにマップすることができず、マップ不可文字エラーに対するアクションがCodingErrorAction.REPORT
である場合CharacterCodingException
public boolean canEncode(char c)
指定された文字がサロゲート文字である場合、このメソッドはfalseを返します。サロゲート文字を解釈できるのは、上位サロゲートのあとに下位サロゲートが続く形のペアになっている場合だけです。文字シーケンスのエンコードが可能であるかどうかは、canEncode(CharSequence)
メソッドを使ってテストできます。
このメソッドは、このエンコーダの状態を変更します。すでにエンコード処理が進行している場合は、このメソッドを呼び出さないでください。
このメソッドのデフォルト実装はあまり効率がよくありません。通常、この性能を改善するためには、オーバーライドが必要です。
c
- 指定された文字IllegalStateException
- エンコード処理がすでに進行中である場合public boolean canEncode(CharSequence cs)
このメソッドが特定の文字シーケンスに対してfalseを返す場合は、エンコード処理をすべて実行すれば、シーケンスがエンコードされない理由を詳しく調べることができます。
このメソッドは、このエンコーダの状態を変更します。すでにエンコード処理が進行している場合は、このメソッドを呼び出さないでください。
このメソッドのデフォルト実装はあまり効率がよくありません。通常、この性能を改善するためには、オーバーライドが必要です。
cs
- 指定された文字シーケンスIllegalStateException
- エンコード処理がすでに進行中である場合 バグまたは機能を送信
詳細なAPIリファレンスおよび開発者ドキュメントについては、Java SEのドキュメントを参照してください。そのドキュメントには、概念的な概要、用語の定義、回避方法、有効なコード例などの、開発者を対象にしたより詳細な説明が含まれています。
Copyright© 1993, 2014, Oracle and/or its affiliates. All rights reserved.