java.nio.charset

クラス CharsetEncoder

java.lang.Object

java.nio.charset.CharsetEncoder

public abstract class CharsetEncoder
extends Object

16 ビット Unicode 文字のシーケンスを特定の文字セットで表現されたバイトシーケンスに変換するエンジンです。

入力文字シーケンスは、単一の文字バッファーまたは一連の文字バッファーとして提供されます。出力バイトシーケンスは、単一の byte バッファーまたは一連の byte バッファーに書き込まれます。エンコーダを使用する際には、必ず次のメソッド呼び出し手順 (以下、エンコード処理) に従ってください。

1. エンコーダをはじめて使用する場合以外は、reset メソッドを使用してエンコーダをリセットします。

2. 追加入力がある限り encode メソッドを 0 回以上呼び出し、各呼び出しの間に endOfInput 引数に false を渡し、入力バッファーにデータを格納し、出力バッファーをフラッシュします。

3. encode メソッドを最後に 1 回呼び出し、endOfInput 引数に true を渡します。

4. エンコーダが内部状態を出力バッファーへフラッシュできるように、flush メソッドを呼び出します。

encode メソッドを呼び出すたびに、入力バッファー内の文字がバイトにエンコードされ、出力バッファーに書き込まれます。新たな入力要求を受け取ったり、出力バッファーの容量が不足したり、エンコードエラーが発生したりすると、encode メソッドは終了します。いずれの場合でも、終了の理由を説明するために CoderResult オブジェクトが返されます。呼び出し元は、このオブジェクトを確認して、入力バッファーをいっぱいにするか、出力バッファーをフラッシュするか、エンコードエラーからの回復処理を実行して、呼び出しを再試行します。

エンコードエラーには一般的な 2 種類のエラーがあります。入力文字シーケンスが正当な 16 ビット Unicode シーケンスでない場合は、不正入力エラーが発生します。入力文字シーケンスは正当でも、これを指定された文字セット内の有効なバイトシーケンスにマップできない場合は、マップ不可文字エラーが発生します。

特定のエンコードエラーがどのように処理されるかは、そのエラーに対して要求されるアクションによって決まります。これらのアクションは、CodingErrorAction クラスのインスタンスによって記述されます。利用可能なエラーアクションは、エラー入力の無視、戻り値の CoderResult オブジェクトを経由した呼び出し元へのエラーの報告、または現在の置換バイト配列値によるエラー入力の置換です。置換 値は、まずエンコーダのデフォルトの置換値に設定されます。その初期値は通常、{ (byte)'?' } ですが、そうならない場合もあります。 この値は、replaceWith メソッドを使って変更できます。

入力形式が正しくないエラーやマップ不可文字エラーが発生した場合、デフォルトのアクションとして、これらのエラーの 報告 が行われます。入力形式が正しくないエラーに対するアクションを変更する場合はonMalformedInput メソッドを、マップ不可文字エラーに対するアクションを変更する場合はonUnmappableCharacter メソッドを、それぞれ使用します。

このクラスは、エラーアクションの実装をはじめとするエンコード処理の詳細の多くを処理するように設計されています。特定の文字セットに対するエンコーダ (このクラスの具象サブクラス) が実装する必要があるのは、標準エンコードループをカプセル化する抽象メソッド encodeLoop だけです。これに加え、内部状態を保持するサブクラスは、implFlush メソッドと implReset メソッドをオーバーライドする必要があります。

このクラスのインスタンスは、複数のスレッドで並行して使用することはできません。

導入されたバージョン:

1.4

関連項目:

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() マップ不可文字エラーに対する、このエンコーダの現在のアクションを返します。

クラス java.lang.Object から継承されたメソッド

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

コンストラクタの詳細

CharsetEncoder

protected CharsetEncoder(Charset cs,
              float averageBytesPerChar,
              float maxBytesPerChar,
              byte[] replacement)

新しいエンコーダを初期化します。新しいエンコーダには、指定された 1 文字当たりのバイト数と置換の値が格納されます。

パラメータ:

averageBytesPerChar - 入力文字ごとに生成される予想バイト数を示す正の float 値

maxBytesPerChar - 入力文字ごとに生成される最大バイト数を示す正の float 値

replacement - 置換の初期値。null でなく、長さが 1 以上 maxBytesPerChar 以下の正当な値でなければならない

例外:

IllegalArgumentException - 上記のパラメータの前提条件が満たされていない場合

CharsetEncoder

protected CharsetEncoder(Charset cs,
              float averageBytesPerChar,
              float maxBytesPerChar)

新しいエンコーダを初期化します。新しいエンコーダには指定された 1 文字当たりのバイト数値が格納され、その置換バイト配列は { (byte)'?' } になります。

パラメータ:

averageBytesPerChar - 入力文字ごとに生成される予想バイト数を示す正の float 値

maxBytesPerChar - 入力文字ごとに生成される最大バイト数を示す正の float 値

例外:

IllegalArgumentException - 上記のパラメータの前提条件が満たされていない場合

メソッドの詳細

charset

public final Charset charset()

このエンコーダを作成した文字セットを返します。

戻り値:

このエンコーダの文字セット

replacement

public final byte[] replacement()

このエンコーダの置換値を返します。

戻り値:

このエンコーダの現在の置換値 (null 以外、空の値以外)

replaceWith

public final CharsetEncoder replaceWith(byte[] newReplacement)

このエンコーダの置換値を変更します。

このメソッドは、新しい置換値が条件に合っていることを確認したうえで、その値を渡して implReplaceWith メソッドを呼び出します。

パラメータ:

newReplacement - 新しい置換値。null でなく、長さが 1 以上で maxBytesPerChar メソッドの戻り値以下の正当な値でなければならない

戻り値:

このエンコーダ

例外:

IllegalArgumentException - 上記のパラメータの前提条件が満たされていない場合

implReplaceWith

protected void implReplaceWith(byte[] newReplacement)

このエンコーダの置換値が変更されたことを報告します。

このメソッドのデフォルト実装では何の処理も行われません。置換値の変更通知を必要とするエンコーダでは、このメソッドをオーバーライドする必要があります。

パラメータ:

newReplacement -

isLegalReplacement

public boolean isLegalReplacement(byte[] repl)

指定されたバイト配列が、このエンコーダの置換値として正当かどうかを判断します。

置換値は、このエンコーダの文字セットで表現できる正当なバイトシーケンスである場合、すなわち、この値を 1 個以上の 16 ビット Unicode 文字にデコードできる場合にかぎり正当です。

このメソッドのデフォルト実装はあまり効率がよくありません。 通常、この性能を改善するためには、オーバーライドが必要です。

パラメータ:

repl - テストするバイト配列

戻り値:

指定されたバイト配列がこのエンコーダにとって正当な置換値である場合に限り true

malformedInputAction

public CodingErrorAction malformedInputAction()

不正入力エラーに対する、このエンコーダの現在のアクションを返します。

戻り値:

入力形式が正しくないエラーに対する現在のアクション (null 以外)

onMalformedInput

public final CharsetEncoder onMalformedInput(CodingErrorAction newAction)

不正入力エラーに対する、このエンコーダのアクションを変更します。

このメソッドは、新しいアクションを渡して implOnMalformedInput メソッドを呼び出します。

パラメータ:

newAction - 新しいアクション (null 以外)

戻り値:

このエンコーダ

例外:

IllegalArgumentException - 上記のパラメータの前提条件が満たされていない場合

implOnMalformedInput

protected void implOnMalformedInput(CodingErrorAction newAction)

不正入力エラーに対する、このエンコーダのアクションが変更されたことを報告します。

このメソッドのデフォルト実装では何の処理も行われません。不正入力エラーに対するアクションの変更通知を必要とするエンコーダでは、このメソッドをオーバーライドする必要があります。

unmappableCharacterAction

public CodingErrorAction unmappableCharacterAction()

マップ不可文字エラーに対する、このエンコーダの現在のアクションを返します。

戻り値:

マップ不可文字エラーに対する現在のアクション (null 以外)

onUnmappableCharacter

public final CharsetEncoder onUnmappableCharacter(CodingErrorAction newAction)

マップ不可文字エラーに対する、このエンコーダのアクションを変更します。

このメソッドは、新しいアクションを渡して implOnUnmappableCharacter メソッドを呼び出します。

パラメータ:

newAction - 新しいアクション (null 以外)

戻り値:

このエンコーダ

例外:

IllegalArgumentException - 上記のパラメータの前提条件が満たされていない場合

implOnUnmappableCharacter

protected void implOnUnmappableCharacter(CodingErrorAction newAction)

マップ不可文字エラーに対する、このエンコーダのアクションが変更されたことを報告します。

このメソッドのデフォルト実装では何の処理も行われません。マップ不可文字エラーに対するアクションの変更通知を必要とするエンコーダでは、このメソッドをオーバーライドする必要があります。

averageBytesPerChar

public final float averageBytesPerChar()

入力文字ごとに生成される平均バイト数を返します。この値から、指定された入力シーケンスに必要な出力バッファーサイズの見積りができます。

戻り値:

入力文字ごとに生成される平均バイト数

maxBytesPerChar

public final float maxBytesPerChar()

入力文字ごとに生成される最大バイト数を返します。この値から、指定された入力シーケンスで必要とされる最大出力バッファーサイズの見積りができます。

戻り値:

入力文字ごとに生成される最大バイト数

encode

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 - 呼び出し元が指定されたバッファーにこれ以上の入力文字を追加する可能性がない場合に限り true

戻り値:

終了の原因を説明する coder-result オブジェクト

例外:

IllegalStateException - エンコード処理がすでに進行中であり、その直前の処理が reset メソッドの呼び出しでも、endOfInput パラメータに false を指定したこのメソッドの呼び出しでも、endOfInput パラメータに true を指定したこのメソッドの呼び出しでもないのに、エンコード処理が不完全であることを示す戻り値が返された場合

CoderMalfunctionError - encodeLoop メソッドの呼び出しによって予期しない例外がスローされた場合

flush

public final CoderResult flush(ByteBuffer out)

このエンコーダをフラッシュします。

内部の状態を保持する一部のエンコーダは、入力シーケンスの読み込みが完了した時点で、出力バッファーに終端バイトを書き込む必要があります。

追加の出力は、出力バッファーの現在位置に書き込まれます。書き込まれるバイト数は多くて out.remaining() バイトです。バッファーの位置はこのバイト数に従って増加しますが、マークとリミットはそのままです。

このメソッドは、正常に終了した場合 CoderResult.UNDERFLOW を返します。出力バッファーの容量が不足した場合は CoderResult.OVERFLOW を返します。この場合は、より多くの空き領域を持つ出力バッファーを指定してこのメソッドを再度呼び出し、このエンコード処理を完了させる必要があります。

このエンコーダのフラッシュ後にこのメソッドを呼び出しても、何の効果もありません。

このメソッドは、implFlush メソッドを呼び出すことで、実際のフラッシュ処理を行います。

パラメータ:

out - 出力 byte バッファー

戻り値:

CoderResult オブジェクト。CoderResult.UNDERFLOW または CoderResult.OVERFLOW

例外:

IllegalStateException - 現在のエンコード処理の直前の処理が、flush メソッドの呼び出しでも、endOfInput パラメータに true を指定した 3 つの引数を持つ encode メソッドの呼び出しでもない場合

implFlush

protected CoderResult implFlush(ByteBuffer out)

このエンコーダをフラッシュします。

このメソッドのデフォルト実装では何の処理も行われず、常に CoderResult.UNDERFLOW を返します。入力シーケンスの読み込み完了後に出力バッファーに最後のバイトを書き込む必要があるエンコーダでは、このメソッドをオーバーライドする必要があります。

パラメータ:

out - 出力 byte バッファー

戻り値:

CoderResult オブジェクト。CoderResult.UNDERFLOW または CoderResult.OVERFLOW

reset

public final CharsetEncoder reset()

このエンコーダをリセットし、内部の状態をクリアします。

このメソッドは、文字セットに依存しない状態をリセットします。また、文字セット固有のリセットアクションを実行するために、implReset メソッドも呼び出します。

戻り値:

このエンコーダ

implReset

protected void implReset()

このエンコーダをリセットし、文字セット固有の内部の状態をクリアします。

このメソッドのデフォルト実装では何の処理も行われません。内部状態を保持するエンコーダでは、このメソッドをオーバーライドする必要があります。

encodeLoop

protected abstract CoderResult encodeLoop(CharBuffer in,
                     ByteBuffer out)

1 個以上の文字 1 個以上のバイトへエンコードします。

このメソッドは、基本的なエンコードループをカプセル化し、入力がなくなるか、出力バッファーの容量が不足するか、またはエンコードエラーが発生するまで最大限の文字をエンコードします。このメソッドは、結果解釈とエラー復旧を行う encode メソッドによって呼び出されます。

バッファーに対する読み書きは、各バッファーの現在位置から行われます。読み取られる文字数は多くて in.remaining() 文字、書き込まれるバイト数は多くて out.remaining() バイトです。バッファーの位置は、読み取られた文字数または書き込まれたバイト数に従って増加しますが、マークとリミットはそのままです。

このメソッドは、encode メソッドと同様に、終了の理由を記述した CoderResult オブジェクトを返します。このメソッドの実装の大部分は、encode メソッドでの解釈に必要な結果オブジェクトを返すことで、エンコードエラーを処理します。これに対し、最適化された実装は、関連エラーアクションを調べ、そのアクションを自身で実行する可能性もあります。

このメソッドの実装によっては、十分な量の入力を受け取るまで任意の前方検索を行い、CoderResult.UNDERFLOW を返し続ける可能性があります。

パラメータ:

in - 入力文字バッファー

out - 出力 byte バッファー

戻り値:

終了の原因を説明する coder-result オブジェクト

encode

public final ByteBuffer encode(CharBuffer in)
                        throws CharacterCodingException

単一の入力文字バッファーのコンテンツを新しく割り当てられた byte バッファー内にエンコードする簡易メソッドです。

このメソッドは、エンコード処理全体を実装しています。つまり、このメソッドは、このエンコーダをリセットしたあと、指定された文字バッファー内の文字をエンコードし、最後にこのエンコーダをフラッシュします。したがって、エンコード処理がすでに進行中の場合は、このメソッドを呼び出さないでください。

パラメータ:

in - 入力文字バッファー

戻り値:

エンコード処理の結果を格納する、新しく割り当てられた byte バッファー。バッファー位置はゼロで、リミットは最後に書き込まれたバイトによって決定される

例外:

IllegalStateException - エンコード処理がすでに進行中である場合

MalformedInputException - 入力バッファーの現在位置から始まる文字シーケンスが正当な 16 ビット Unicode シーケンスでなく、不正入力エラーに対するアクションが CodingErrorAction.REPORT である場合

UnmappableCharacterException - 入力バッファーの現在位置から始まる文字シーケンスを同等のバイトシーケンスにマップすることができず、マップ不可文字エラーに対するアクションが CodingErrorAction.REPORT である場合

CharacterCodingException

canEncode

public boolean canEncode(char c)

このエンコーダが指定された文字をエンコードできるかどうかを判断します。

指定された文字がサロゲート文字である場合、このメソッドは false を返します。サロゲート文字を解釈できるのは、上位サロゲートのあとに下位サロゲートが続く形のペアになっている場合だけです。文字シーケンスのエンコードが可能であるかどうかは、canEncode(CharSequence) メソッドを使ってテストできます。

このメソッドは、このエンコーダの状態を変更します。すでにエンコード処理が進行している場合は、このメソッドを呼び出さないでください。

このメソッドのデフォルト実装はあまり効率がよくありません。 通常、この性能を改善するためには、オーバーライドが必要です。

戻り値:

このエンコーダが指定された文字をエンコードできる場合に限り true

例外:

IllegalStateException - エンコード処理がすでに進行中である場合

canEncode

public boolean canEncode(CharSequence cs)

このエンコーダが指定された文字シーケンスをエンコードできるかどうかを判断します。

このメソッドが特定の文字シーケンスに対して false を返す場合は、エンコード処理をすべて実行すれば、シーケンスがエンコードされない理由を詳しく調べることができます。

このメソッドは、このエンコーダの状態を変更します。すでにエンコード処理が進行している場合は、このメソッドを呼び出さないでください。

このメソッドのデフォルト実装はあまり効率がよくありません。 通常、この性能を改善するためには、オーバーライドが必要です。

戻り値:

このエンコーダが、例外のスローや置換処理の実行なしで指定された文字をエンコードできる場合に限り true

例外:

IllegalStateException - エンコード処理がすでに進行中である場合