JavaTM 2
Platform
Std. Ed. v1.4.0

java.nio.charset
クラス CharsetEncoder

java.lang.Object
  |
  +--java.nio.charset.CharsetEncoder

public abstract class CharsetEncoder
extends Object

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

入力バイトシーケンスは、char バッファなどのバッファから渡されます。出力文字シーケンスは、byte バッファなどのバッファに書き込まれます。エンコーダは、必ず次のメソッド呼び出しシーケンス (以下「エンコード処理」) のあとで使用してください。

  1. 初めて使用するときは、reset メソッドを使ってエンコーダをリセットします。

  2. 追加の入力がなくなるまで、繰り返し encode メソッドを呼び出します。endOfInput 引数に false を渡し、入力バッファを格納して、次の呼び出しの前に出力バッファをフラッシュします。

  3. encode メッソドの呼び出しを終了するときは、endOfInput 引数に true を渡します。

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

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

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

エンコードエラーは、その種類のエラーに対して要求されたアクションに従って処理されます。こうしたアクションは、CodingErrorAction クラスのインスタンスに記述されています。たとえば、不正入力の無視CoderResult オブジェクトによる呼び出し元への報告、不正入力内容を代替バイト配列の現在値へ置き換えといったアクションがあります。代替値は最初、エンコーダのデフォルトの値に設定されています。この値は、多くの場合、{ (byte)'?' } という初期値を持っていますが、replaceWith メソッドを使って別の値に変更することもできます。

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

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

このクラスのインスタンスを複数の並行スレッドで安全に使用することはできません。

導入されたバージョン:
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)
          単一の入力 char バッファのコンテンツを新しく割り当てられた 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)
新しいエンコーダを初期化します。新しいエンコーダは、指定された文字ごとのバイトと代替値を保持します。

パラメータ:
averageBytesPerChar - 入力文字ごとに生成される期待バイト数を示す正の float 値
maxBytesPerChar - 入力文字ごとに生成されるバイト数の最大値を示す正の float 値
replacement - 代替値の初期値 (null 以外、ゼロでない長さかつ maxBytesPerChar 以下の正当な値)
例外:
IllegalArgumentException - 上記のパラメータの前提条件が満たされていない場合

CharsetEncoder

protected CharsetEncoder(Charset cs,
                         float averageBytesPerChar,
                         float maxBytesPerChar)
新しいエンコーダを初期化します。新しいエンコーダは、文字ごとに生成されたバイトの値と代替バイト配列 { (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 以外、ゼロ以外の長さかつ 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 オブジェクトを返します。

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

endOfInput パラメータは、指定された入力バッファに呼び出し元からの新たな入力があるかどうかをこのメソッドに通知します。まだ入力の可能性がある場合、呼び出し元はこのパラメータに false を渡す必要があります。これ以上入力の可能性がない場合は true を渡します。呼び出し元から false を渡したあとで入力がなかったとしても、問題はありません。しかし、呼び出しシーケンスにおける最後の呼び出しでは、true を渡さなければなりません。これ以降、まだエンコードされていない入力は「不正」と見なされるようになります。

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

パラメータ:
in - 入力 char バッファ
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 を返します。CoderResult.OVERFLOW が返された場合は、容量に空きのある出力バッファを指定してこのメソッドを再度呼び出し、このエンコード処理を完了させる必要があります。

このメソッドは、implFlush メソッドを呼び出して、実際にフラッシュを行います。

パラメータ:
out - 出力 byte バッファ
戻り値:
Coder Result オブジェクト (CoderResult.UNDERFLOW または CoderResult.OVERFLOW)
例外:
IllegalStateException - 現在のエンコード処理の直前の処理が reset メソッドの呼び出しでも、endOfInput パラメータに true を指定した 3 つの引数を持つ encode メソッドの呼び出しでもない場合

implFlush

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

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

パラメータ:
out - 出力 byte バッファ
戻り値:
Coder Result オブジェクト (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 - 入力 char バッファ
out - 出力 byte バッファ
戻り値:
終了の原因を説明する Coder Result オブジェクト

encode

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

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

パラメータ:
in - 入力 char バッファ
戻り値:
エンコード処理の結果を格納する、新しく割り当てられた 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 - エンコード処理がすでに進行中である場合

JavaTM 2
Platform
Std. Ed. v1.4.0

バグの報告と機能のリクエスト
これ以外の API リファレンスおよび開発者用ドキュメントについては、 Java 2 SDK SE 開発者用ドキュメントを参照してください。 開発者向けの詳細な解説、概念の概要、用語の定義、バグの回避策、 およびコード実例が含まれています。

Java、Java 2D、および JDBC は米国ならびにその他の国における米国 Sun Microsystems, Inc. の商標もしくは登録商標です。
Copyright 1993-2002 Sun Microsystems, Inc. 901 San Antonio Road
Palo Alto, California, 94303, U.S.A. All Rights Reserved.