モジュール java.base
パッケージ java.nio.charset

クラスCharsetDecoder

java.lang.Object
java.nio.charset.CharsetDecoder
public abstract class CharsetDecoder extends Object
特定の文字セットで表現されたバイト・シーケンスを16ビットUnicode文字のシーケンスに変換するエンジンです。

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

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

  2. decodeメソッドを0回以上起動します(追加入力が使用可能であれば、endOfInput引数にfalseを渡し、入力バッファを埋めて、呼出し間で出力バッファをフラッシュします)

  3. decodeメソッドを最後に1回起動し、endOfInput引数のtrueを渡します

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

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

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

特定のデコード・エラーがどのように処理されるかは、その種類のエラーに対して要求されるアクションによって決まります。これらのアクションは、CodingErrorActionクラスのインスタンスによって記述されます。 利用可能なエラー・アクションは、エラー入力の無視、戻り値のCoderResultオブジェクトを経由した呼出し元へのエラーの報告、または現在の置換文字列値によるエラー入力の置換です。 置換には初期値"\uFFFD"があり、その値はreplaceWithメソッドで変更できます。

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

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

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

導入されたバージョン:
1.4
関連項目:

  • コンストラクタのサマリー

    コンストラクタ
    修飾子
    コンストラクタ
    説明
    protected
    CharsetDecoder(Charset cs, float averageCharsPerByte, float maxCharsPerByte)
    新しいデコーダを初期化します。

  • メソッドのサマリー

    修飾子と型
    メソッド
    説明
    final float
    averageCharsPerByte()
    入力バイトごとに生成される平均文字数を返します。
    final Charset
    charset()
    このデコーダを生成した文字セットを返します。
    final CharBuffer
    decode(ByteBuffer in)
    単一の入力byteバッファのコンテンツを新しく割り当てられた文字バッファ内にデコードする簡易メソッドです。
    final CoderResult
    decode(ByteBuffer in, CharBuffer out, boolean endOfInput)
    指定された入力バッファ内のバイトを最大限デコードし、指定された出力バッファに結果を書き込みます。
    protected abstract CoderResult
    decodeLoop(ByteBuffer in, CharBuffer out)
    1個以上のバイトをデコードし、1個以上の文字へデコードします。
    Charset
    detectedCharset()
    このデコーダによって検出された文字セットを取得します  (オプションの操作)。
    final CoderResult
    flush(CharBuffer out)
    このデコーダをフラッシュします。
    protected CoderResult
    implFlush(CharBuffer out)
    このデコーダをフラッシュします。
    protected void
    implOnMalformedInput(CodingErrorAction newAction)
    不正入力エラーに対する、このデコーダのアクションが変更されたことを報告します。
    protected void
    implOnUnmappableCharacter(CodingErrorAction newAction)
    マップできない文字エラーに対する、このデコーダのアクションが変更されたことを報告します。
    protected void
    implReplaceWith(String newReplacement)
    このデコーダの代替値が変更されたことを報告します。
    protected void
    implReset()
    このデコーダをリセットし、文字セット固有の内部の状態をクリアします。
    boolean
    isAutoDetecting()
    このデコーダが自動検出文字セットを実装するかどうかを判断します。
    boolean
    isCharsetDetected()
    このデコーダがすでに文字セットを検出しているかどうかを判断します  (オプションの操作)。
    CodingErrorAction
    malformedInputAction()
    不正入力エラーに対する、このデコーダの現在のアクションを返します。
    final float
    maxCharsPerByte()
    入力バイトごとに生成される最大文字数を返します。
    final CharsetDecoder
    onMalformedInput(CodingErrorAction newAction)
    不正入力エラーに対するこのデコーダのアクションを変更します。
    final CharsetDecoder
    onUnmappableCharacter(CodingErrorAction newAction)
    マップできない文字エラーに対する、このデコーダのアクションを変更します。
    final String
    replacement()
    このデコーダの置換値を返します。
    final CharsetDecoder
    replaceWith(String newReplacement)
    このデコーダの代替値を変更します。
    final CharsetDecoder
    reset()
    このデコーダをリセットし、内部の状態をクリアします。
    CodingErrorAction
    unmappableCharacterAction()
    マップ不可文字エラーに対する、このデコーダの現在のアクションを返します。

    クラス java.lang.Objectで宣言されたメソッド

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

  • コンストラクタの詳細

    • CharsetDecoder

      protected CharsetDecoder(Charset cs, float averageCharsPerByte, float maxCharsPerByte)
      新しいデコーダを初期化します。 新しいデコーダは指定されたバイト単位の文字値を持ち、その置換は文字列"\uFFFD"になります。
      パラメータ:
      cs - このデコーダを生成した文字セット
      averageCharsPerByte - 入力バイトごとに生成される期待文字数を示す正のfloat値
      maxCharsPerByte - 入力バイトごとに生成される最大文字数を示す正のfloat値
      例外:
      IllegalArgumentException - 上記のパラメータの前提条件が満たされていない場合

  • メソッドの詳細

    • charset

      public final Charset charset()
      このデコーダを生成した文字セットを返します。
      戻り値:
      このデコーダの文字セット

    • replacement

      public final String replacement()
      このデコーダの置換値を返します。
      戻り値:
      このデコーダの現在の置換。nullでなく、空でもない

    • replaceWith

      public final CharsetDecoder replaceWith(String newReplacement)
      このデコーダの代替値を変更します。

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

      パラメータ:
      newReplacement - 新しい交換。nullであってはならず、長さがゼロでなくてはならず、maxCharsPerByteメソッドから返された値よりも長くてはいけません
      戻り値:
      このデコーダ
      例外:
      IllegalArgumentException - 上記のパラメータの前提条件が満たされていない場合

    • implReplaceWith

      protected void implReplaceWith(String newReplacement)
      このデコーダの代替値が変更されたことを報告します。

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

      パラメータ:
      newReplacement - 代替値

    • malformedInputAction

      public CodingErrorAction malformedInputAction()
      不正入力エラーに対する、このデコーダの現在のアクションを返します。
      戻り値:
      現在の不正な入力アクション。nullではありません

    • onMalformedInput

      public final CharsetDecoder onMalformedInput(CodingErrorAction newAction)
      不正入力エラーに対するこのデコーダのアクションを変更します。

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

      パラメータ:
      newAction - 新しいアクション。nullにはできません
      戻り値:
      このデコーダ
      例外:
      IllegalArgumentException - 上記のパラメータの前提条件が満たされていない場合

    • implOnMalformedInput

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

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

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

    • unmappableCharacterAction

      public CodingErrorAction unmappableCharacterAction()
      マップ不可文字エラーに対する、このデコーダの現在のアクションを返します。
      戻り値:
      現在のマッピング不可能な文字アクション。nullではありません

    • onUnmappableCharacter

      public final CharsetDecoder onUnmappableCharacter(CodingErrorAction newAction)
      マップできない文字エラーに対する、このデコーダのアクションを変更します。

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

      パラメータ:
      newAction - 新しいアクション。nullにはできません
      戻り値:
      このデコーダ
      例外:
      IllegalArgumentException - 上記のパラメータの前提条件が満たされていない場合

    • implOnUnmappableCharacter

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

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

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

    • averageCharsPerByte

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

    • maxCharsPerByte

      public final float maxCharsPerByte()
      入力バイトごとに生成される最大文字数を返します。 この値から、指定された入力シーケンスで必要とされる最大出力バッファ・サイズの見積りができます。 この値は、必要なコンテンツに依存しないプレフィクスまたはサフィクス文字に対応します。
      戻り値:
      入力バイトごとに生成される最大文字数

    • decode

      public final CoderResult decode(ByteBuffer in, CharBuffer out, boolean endOfInput)
      指定された入力バッファ内のバイトを最大限デコードし、指定された出力バッファに結果を書き込みます。

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

      このメソッドは、入力バッファからのバイトの読み込みと出力バッファへの文字の書込みに加えて、終了の理由を説明する次のようなCoderResultオブジェクトを返します。

      • CoderResult.UNDERFLOWは、入力バッファ内のバイトが最大限デコードされたことを示します。 それ以上入力がない場合、呼出し元はデコード処理の次のステップに進むことができます。 それ以外の場合、さらに入力データを準備して、このメソッドを再度呼び出す必要があります。

      • CoderResult.OVERFLOWは、出力バッファの容量が不足していて、これ以上バイトをデコードできないことを示します。 残りの文字数が多い出力バッファを指定して、このメソッドを再度呼び出す必要があります。 このためには通常、出力バッファに入っているデコード済みの文字を排出します。

      • 入力形式が正しくない結果は、入力形式が正しくないエラーが検出されたことを示します。 形式が不正なバイトは、入力バッファの位置(位置の値が増加している可能性もある)から始まります。形式が不正なバイト数は、結果オブジェクトのlengthメソッドを呼び出すことで特定できます。 ただし、これが当てはまるのは、このデコーダの形式不正入力エラーに対するアクションがCodingErrorAction.REPORTである場合に限られます。それ以外の場合、形式不正入力は要求に応じて無視されるか、別の値に置換されます。

      • マップ不可文字結果は、マップ不可文字エラーが検出されたことを示します。 マップ不可文字をデコードするバイトは、入力バッファの位置(位置の値が増加している可能性もある)から始まります。そのバイト数は、結果オブジェクトのlengthメソッドを呼び出すことで特定できます。 ただし、これが当てはまるのは、このデコーダのマップ不可文字エラーに対するアクションがCodingErrorAction.REPORTである場合に限られます。それ以外の場合、マップ不可文字は要求に応じて無視されるか、別の値に置換されます。

      いずれの場合も、このメソッドを同じデコード処理の中で再度呼び出すときは、次の呼出しで使用できるように、入力バッファ内のバイトを保存する必要があります。

      endOfInputパラメータは、指定された入力バッファに含まれる入力以外に実行者が入力を提供できるかどうかについて、このメソッドにアドバイスします。 追加入力を行う可能性がある場合、実行者はこのパラメータに対してfalseを渡す必要があります。さらに入力を行う可能性がない場合は、実行者はtrueを渡す必要があります。 1回の呼出しでfalseを渡し、後でそれ以上の入力が実際に使用可能でないことを検出することは、誤りではなく、事実上非常に一般的です。 ただし、一連の呼出しでこのメソッドの最終的な呼出しは、常にtrueを渡すため、残りのデコードされていない入力は不正な形式として扱われます。

      このメソッドは、まずdecodeLoopメソッドを呼び出します。その後、その結果を解釈し、エラー条件の処理を済ませたあと、必要に応じて再度そのメソッドを呼び出します。

      パラメータ:
      in - 入力バイト・バッファ
      out - 出力文字バッファ
      endOfInput - trueは、実行者が指定されたバッファ内の入力バイトを超える追加入力バイトを提供できない場合のみ、
      戻り値:
      終了の原因を説明するcoder-resultオブジェクト
      例外:
      IllegalStateException - デコード操作がすでに進行中で、前のステップがresetメソッドの呼出しでも、endOfInputパラメータの値がfalseのこのメソッドの呼出しでも、endOfInputパラメータの値がtrueの戻り値でも、デコード操作が不完全なことを示す戻り値でもない場合
      CoderMalfunctionError - decodeLoopメソッドの呼出しによって予期しない例外がスローされた場合

    • flush

      public final CoderResult flush(CharBuffer out)
      このデコーダをフラッシュします。

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

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

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

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

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

      パラメータ:
      out - 出力文字バッファ
      戻り値:
      CoderResultオブジェクト。CoderResult.UNDERFLOWまたはCoderResult.OVERFLOW
      例外:
      IllegalStateException - 現在のデコード操作の前のステップが、flushメソッドと、endOfInputパラメータの値がtrueの3つの引数のdecodeメソッドのどちらも起動しなかった場合

    • implFlush

      protected CoderResult implFlush(CharBuffer out)
      このデコーダをフラッシュします。

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

      パラメータ:
      out - 出力文字バッファ
      戻り値:
      CoderResultオブジェクト。CoderResult.UNDERFLOWまたはCoderResult.OVERFLOW

    • reset

      public final CharsetDecoder reset()
      このデコーダをリセットし、内部の状態をクリアします。

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

      戻り値:
      このデコーダ

    • implReset

      protected void implReset()
      このデコーダをリセットし、文字セット固有の内部の状態をクリアします。

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

    • decodeLoop

      protected abstract CoderResult decodeLoop(ByteBuffer in, CharBuffer out)
      1個以上のバイトをデコードし、1個以上の文字へデコードします。

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

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

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

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

      パラメータ:
      in - 入力バイト・バッファ
      out - 出力文字バッファ
      戻り値:
      終了の原因を説明するcoder-resultオブジェクト

    • decode

      public final CharBuffer decode(ByteBuffer in) throws CharacterCodingException
      単一の入力byteバッファのコンテンツを新しく割り当てられた文字バッファ内にデコードする簡易メソッドです。

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

      パラメータ:
      in - 入力バイト・バッファ
      戻り値:
      デコード処理の結果を格納する、新しく割り当てられた文字バッファ。 バッファ位置はゼロで、リミットは最後に書き込まれた文字によって決定される
      例外:
      IllegalStateException - デコード処理がすでに進行中である場合
      MalformedInputException - 入力バッファの現在位置から始まるバイト・シーケンスがこの文字セットにとって不正であり、不正入力エラーに対するアクションがCodingErrorAction.REPORTである場合
      UnmappableCharacterException - 入力バッファの現在位置から始まるバイト・シーケンスを同等の文字シーケンスにマップすることができず、マップ不可文字エラーに対するアクションがCodingErrorAction.REPORTである場合
      CharacterCodingException

    • isAutoDetecting

      public boolean isAutoDetecting()
      このデコーダが自動検出文字セットを実装するかどうかを判断します。

      このメソッドのデフォルトの実装は、常にfalseを返します。trueを返すには、デコーダを自動検出することでオーバーライドする必要があります。

      戻り値:
      このデコーダが自動検出文字セットを実装する場合のみ、true

    • isCharsetDetected

      public boolean isCharsetDetected()
      このデコーダがすでに文字セットを検出しているかどうかを判断します  (オプションの操作)。

      このデコーダが自動検出文字セットを実装している場合、デコード操作中に単一のポイントで、このメソッドはtrueを返して、入力バイト・シーケンスで特定の文字セットが検出されたことを示すように開始できます。 それ以降は、detectedCharsetメソッドを呼び出すことで、検出された文字セットを取得できます。

      このメソッドがfalseを返すことは、まだデコードされているバイトがないことを意味しません。 一部の自動検出デコーダは、特定の文字セットを選択しないまま入力バイト・シーケンスの一部または全部をデコードすることができます。

      このメソッドのデフォルトの実装では常にUnsupportedOperationExceptionがスローされます。入力文字セットが決定されると、自動検出デコーダでオーバーライドされ、trueが返されます。

      戻り値:
      このデコーダが特定の文字セットを検出した場合にのみ、true
      例外:
      UnsupportedOperationException - このデコーダが自動検出文字セットを実装していない場合

    • detectedCharset

      public Charset detectedCharset()
      このデコーダによって検出された文字セットを取得します  (オプションの操作)。

      このデコーダが自動検出文字セットを実装している場合、このメソッドは、実際の文字セットが検出された時点でその文字セットを返します。 これ以降、現在のデコード処理が終了するまで同じ値を返します。 読込み入力バイト数が少なすぎて文字セットを特定できていない場合、このメソッドはIllegalStateExceptionをスローします。

      このメソッドのデフォルト実装は、常にUnsupportedOperationExceptionを返します。自動検出デコーダの場合、適切な値を返すようにこのメソッドをオーバーライドする必要があります。

      戻り値:
      この自動検出デコーダで検出された文字セット、または文字セットがまだ決定されていない場合はnull
      例外:
      IllegalStateException - 読込みバイト数の不足のため、文字セットを特定できなかった場合
      UnsupportedOperationException - このデコーダが自動検出文字セットを実装していない場合