4.3. CharsetEncoderクラス

CharsetEncoderクラスはUnicode文字列を各種文字セットの文字列に変換するためのクラスです。CharsetEncoderインスタンスは、対応するCharsetインスタンスのnewEncoder()メソッドを呼び出すことによって取得できます。

文字列のエンコードを行うためのメソッドは、以下の2つ存在します。

• CoderResult encode(CharBuffer in, ByteBuffer out, boolean endOfInput)
• ByteBuffer encode(CharBuffer in)
  

まず、1番目の3つの引数を持った encode メソッドを使用した場合のエンコード手順を説明します。

• resetメソッドを呼び出し、エンコーダをリセットする。
• 入力がなくなるまで繰り返しencodeメソッドを呼び出す。encodeメソッドのendOfInput引数は通常はfalseとし、最後の呼び出し時のみtrueとする。
• flushメソッドを呼び出し、エンコーダをフラッシュする。

3つの引数をもつ encode メソッドは、in に入力用の CharBuffer、out に出力用の ByteBuffer を指定します。endOfInput は、入力用バッファに今後入力が追加されないことを示すフラグです。

エンコード処理を行う際にはエンコードエラーが発生することがありますが、エラーが発生した際にどのような動作をするかを制御することができます。動作を制御することの出来るエラーは2種類あります。

onMalformedInputメソッドおよびonUnmappableCharacterメソッドは、CodingErrorAction型の引数1つを指定します。引数にはCodingErrorActionクラスで定義されている3つのstaticなインスタンスのいずれかを指定します。

encode メソッドの戻り値は CoderResult のインスタンスです。CoderResult クラスは、エンコーダやデコーダの結果を表すクラスです。CoderResult の持つ値の意味は、後の節で説明します。

引数が1つの encode メソッドは簡易メソッドです。in パラメータに入力用の CharBuffer を指定し、戻り値にはエンコード結果を表す ByteBuffer が返されます。このメソッドの1回の呼び出しで、エンコーダのリセットからエンコード、フラッシュまでの処理をすべて行います。CoderResult は返されないので、エラー発生時のアクションを CodingErrorAction.REPORT と指定している状態でエンコード中にエラーが発生すると、例外として通知されます。

なお、Charset クラスの簡易エンコードメソッドの呼び出し、

ByteBuffer byteBuf = charset.encode(charBuf);

は、次の処理とほぼ同等です(charset は Charset 型のインスタンスとします)。

ByteBuffer byteBuf = charset.newEncoder()
                            .onMalformedInput(CodingErrorAction.REPLACE)
                            .onUnmappableCharacter(CodingErrorAction.REPLACE)
                            .encode(charBuf); 

（onMalformedInput や onUnmappableCharacter メソッドは、戻り値として CharsetEncoder 自分自身を返します。）
不正入力エラーやマップ不可文字エラーが発生した文字は「?」に置換します。