モジュール java.base
パッケージ 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文字当たりのバイト数と置換の値が格納されます。
      パラメータ:
      cs - このエンコーダを作成した文字セット
      averageBytesPerChar - 入力文字ごとに生成される予想バイト数を示す正のfloat値
      maxBytesPerChar - 入力文字ごとに生成される最大バイト数を示す正のfloat値
      replacement - 置換の初期値。nullでなく、長さが1以上maxBytesPerChar以下の正当な値でなければならない。
      例外:
      IllegalArgumentException - 上記のパラメータの前提条件が満たされていない場合

    • CharsetEncoder

      protected CharsetEncoder​(Charset cs, float averageBytesPerChar, float maxBytesPerChar)
      新しいエンコーダを初期化します。 新しいエンコーダには指定された1文字当たりのバイト数値が格納され、その置換バイト配列は{ (byte)'?' }になります。
      パラメータ:
      cs - このエンコーダを作成した文字セット
      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であってはならず、長さがゼロでなくてはならず、maxBytesPerCharメソッドから返された値よりも長くてはいけません。また、legalでなければなりません
      戻り値:
      このエンコーダ
      例外:
      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)
      不正入力エラーに対する、このエンコーダのアクションが変更されたことを報告します。

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

      パラメータ:
      newAction - 新しいアクション

    • unmappableCharacterAction

      public CodingErrorAction unmappableCharacterAction()
      マップ不可文字エラーに対する、このエンコーダの現在のアクションを返します。
      戻り値:
      マップ不可文字エラーに対する現在のアクション(null以外)

    • onUnmappableCharacter

      public final CharsetEncoder onUnmappableCharacter​(CodingErrorAction newAction)
      マップ不可文字エラーに対する、このエンコーダのアクションを変更します。

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

      パラメータ:
      newAction - 新しいアクション(null以外)
      戻り値:
      このエンコーダ
      例外:
      IllegalArgumentException - 上記のパラメータの前提条件が満たされていない場合

    • implOnUnmappableCharacter

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

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

      パラメータ:
      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)メソッドを使ってテストできます。

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

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

      パラメータ:
      c - 指定された文字
      戻り値:
      このエンコーダが指定された文字をエンコードできる場合に限りtrue
      例外:
      IllegalStateException - エンコード処理がすでに進行中である場合

    • canEncode

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

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

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

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

      パラメータ:
      cs - 指定された文字シーケンス
      戻り値:
      このエンコーダが、例外のスローや置換処理の実行なしで指定された文字をエンコードできる場合に限りtrue
      例外:
      IllegalStateException - エンコード処理がすでに進行中である場合