モジュール 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)	新しいエンコーダを初期化します。

メソッドのサマリー

修飾子と型	メソッド	説明
final float	averageBytesPerChar()	入力文字ごとに生成される平均バイト数を返します。
boolean	canEncode(char c)	このエンコーダが指定された文字をエンコードできるかどうかを判断します。
boolean	canEncode(CharSequence cs)	このエンコーダが指定された文字シーケンスをエンコードできるかどうかを判断します。
final Charset	charset()	このエンコーダを作成した文字セットを返します。
final ByteBuffer	encode(CharBuffer in)	単一の入力文字バッファのコンテンツを新しく割り当てられたbyteバッファ内にエンコードする簡易メソッドです。
final CoderResult	encode(CharBuffer in, ByteBuffer out, boolean endOfInput)	指定された入力バッファ内の文字を最大限エンコードし、指定された出力バッファに結果を書き込みます。
protected abstract CoderResult	encodeLoop(CharBuffer in, ByteBuffer out)	1個以上の文字1個以上のバイトへエンコードします。
final 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()	不正入力エラーに対する、このエンコーダの現在のアクションを返します。
final float	maxBytesPerChar()	入力文字ごとに生成される最大バイト数を返します。
final CharsetEncoder	onMalformedInput(CodingErrorAction newAction)	不正入力エラーに対する、このエンコーダのアクションを変更します。
final CharsetEncoder	onUnmappableCharacter(CodingErrorAction newAction)	マップ不可文字エラーに対する、このエンコーダのアクションを変更します。
final byte[]	replacement()	このエンコーダの置換値を返します。
final CharsetEncoder	replaceWith(byte[] newReplacement)	このエンコーダの置換値を変更します。
final 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にしないでください。長さはゼロ以外にする必要があり、maxBytesPerCharより長くしてはなりません。「法的」にする必要があります

例外:

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

CharsetEncoder

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

新しいエンコーダを初期化します。 新しいエンコーダは指定されたバイト/文字の値を持ち、その置換はバイト配列{ (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を渡す必要があります。 1回の呼出しで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 - 入力バッファの現在の位置から始まる文字シーケンスが16ビットの有効なUnicodeシーケンスではなく、現在の不正な入力アクションがCodingErrorAction.REPORTの場合、MalformedInputException。入力バッファの現在の位置から始まる文字シーケンスを同等のバイト・シーケンスにマップできず、現在の適用できない文字アクションがCodingErrorAction.REPORTの場合、UnmappableCharacterException

OutOfMemoryError - 入力文字バッファのリクエスト・サイズに対する出力バイト・バッファを割り当てることができない場合

canEncode

public boolean canEncode(char c)

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

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

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

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

パラメータ:

c - 指定された文字

戻り値:

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

例外:

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

canEncode

public boolean canEncode(CharSequence cs)

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

このメソッドが特定の文字シーケンスに対してfalseを返す場合、完全な「エンコーディング操作」を実行して、シーケンスをエンコードできない理由に関する詳細を取得できます。

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

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

パラメータ:

cs - 指定された文字シーケンス

戻り値:

このエンコーダが、例外をスローせずに置換を実行せずに、指定された文字をエンコードできる場合、true

例外:

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