/**
* 文字デコードハンドラ。
- * {@link StreamDecoder}により呼ばれる。
- * メソッドが呼ばれる順番は
+ * {@link StreamDecoder}により呼び出される。
+ *
+ * <p>デコード処理を通じてメソッドが呼ばれる順番は
* {@link #startDecoding}が最初で
* {@link #endDecoding}が最後。
* その間、{@link #charContent}
* または{@link #decodingError}が複数回呼ばれる。
- * 各メソッドは、{@link DecodeException}をスローすることで
+ *
+ * <p>各メソッドは、{@link DecodeException}をスローすることで
* デコード処理を中止させることができる。
*/
public interface DecodeHandler{
/**
- * デコード開始の通知を受け取る。
- * @param decoder デコーダ
+ * デコード処理開始の通知を受け取る。
+ *
+ * <p>渡された文字デコーダの各種設定を変更してはならない。
+ *
+ * @param decoder 文字デコーダ
* @throws DecodeException デコードエラー
*/
void startDecoding(CharsetDecoder decoder)
/**
* 正常にデコードした文字列の通知を受け取る。
- * seqの内容は、ハンドラ呼び出し元で随時変更されうる。
+ *
+ * <p>seqの内容は、ハンドラ呼び出し元で随時変更されうる。
* seqの内容を後々再利用するつもりなら、
* 制御を呼び出し元に戻すまでの間に必要な箇所をコピーする必要がある。
+ *
* @param seq 文字列
* @throws DecodeException デコードエラー
*/
/**
* デコードエラーの通知を受け取る。
- * errorArrayの内容は、ハンドラ呼び出し元で随時変更されうる。
+ *
+ * <p>errorArrayの内容は、ハンドラ呼び出し元で随時変更されうる。
* errorArrayの内容を後々再利用するつもりなら、
* 制御を呼び出し元に戻すまでの間に必要な箇所をコピーする必要がある。
+ *
* @param errorArray エラーを引き起こした入力バイトシーケンス。
* @param offset errorArrayに含まれるエラーの開始位置。
* @param length errorArrayに含まれるエラーのバイト長。
throws DecodeException;
/**
- * デコード終了の通知を受け取る。
+ * デコード処理終了の通知を受け取る。
+ *
* @throws DecodeException デコードエラー
*/
void endDecoding()
import java.util.Arrays;
/**
- * ã\83\90ã\82¤ã\83\88ã\82¹ã\83\88ã\83ªã\83¼ã\83 ã\81\8bã\82\89ã\81®文字列デコーダ。
+ * ã\83\90ã\82¤ã\83\88ã\82¹ã\83\88ã\83ªã\83¼ã\83 ã\82\92å\85¥å\8a\9bã\81¨ã\81\99ã\82\8b文字列デコーダ。
*
- * <p>入力バイトストリームから文字列をデコードし、
- * デコード結果およびデコードエラーを
- * 文字デコードハンドラ{@link DecodeHandler}に通知する。
+ * <p>入力バイトストリームから文字列(charシーケンス)をデコードし、
+ * デコード結果およびデコード異常系を
+ * 文字デコードハンドラ<code>{@link DecodeHandler}</code>に通知する。
*
- * <p>このクラスは、
- * {@link java.nio.charset.CharsetDecoder}呼び出しの煩雑さを
- * 「制御の反転」を用いて隠蔽するために設計された。
+ * <p>このクラスは、「制御の反転」(Inversion of Control)を用いて
+ * <code>{@link java.nio.charset.CharsetDecoder}</code>呼び出しの
+ * 煩雑さを隠蔽するために設計された。
*
* <p>このクラスは、
- * デコードエラー詳細を察知できない{@link java.io.InputStreamReader}の
+ * デコード異常系詳細を察知できない
+ * <code>{@link java.io.InputStreamReader}</code>の
* 代替品として設計された。
*
- * <p>マルチスレッド対応はしていない。
+ * <p>マルチスレッドからの同一インスタンスへの操作は非対応。
+ *
+ * @see java.nio.charset.CharsetDecoder
*/
public class StreamDecoder{
/**
* コンストラクタ。
*
- * @param decoder 文字列デコーダ
+ * バッファサイズは入出力ともデフォルト値が用いられる。
+ *
+ * @param decoder 文字列デコーダ。
+ * 異常系に関するアクション応答設定は変更される。
+ * @throws NullPointerException デコーダにnullを渡した。
*/
- public StreamDecoder(CharsetDecoder decoder){
+ public StreamDecoder(CharsetDecoder decoder) throws NullPointerException{
this(decoder, BYTEBUF_DEFSZ, CHARBUF_DEFSZ);
return;
}
/**
* コンストラクタ。
*
- * @param decoder 文字列デコーダ
+ * @param decoder 文字列デコーダ。
+ * 異常系に関するアクション応答設定は変更される。
* @param inbufSz 入力バッファサイズ(byte単位)
* @param outbufSz 出力バッファサイズ(char単位)
* @throws NullPointerException デコーダにnullを渡した。
/**
* チャネルからの入力を読み進め入力バッファに詰め込む。
*
- * <p>前回の読み残しはバッファ前方に詰め直される。
+ * <p>前回デコード処理の読み残しはバッファ前方に詰め直される。
+ *
+ * <p>入力バッファに空きがない状態で呼んではいけない。
*
* @return 入力バイト数。
* 入力末端に達したときは負の値。
* ※入力バッファに空きがありチャネルがブロックモードの場合、
* 返り値0はありえない。
- * @throws java.io.IOException å\85¥å\87ºå\8a\9bã\82¨ã\83©ã\83¼
+ * @throws java.io.IOException 入力エラー
*/
protected int fillByteBuffer() throws IOException{
this.byteBuffer.compact();
*
* <p>既に出力バッファが空だった場合、何もしない。
*
- * @throws DecodeException デコードエラー
+ * @throws DecodeException ã\83\8fã\83³ã\83\89ã\83©ã\81«ã\82\88ã\82\8bã\83\87ã\82³ã\83¼ã\83\89ã\82¨ã\83©ã\83¼
*/
protected void notifyText() throws DecodeException{
if(this.charBuffer.position() <= 0){
}
/**
- * デコードハンドラにデコードエラーを渡す。
+ * デコードハンドラにデコードエラーを通知する。
*
* @param result デコード結果
- * @throws DecodeException デコードエラー
+ * @throws DecodeException ã\83\8fã\83³ã\83\89ã\83©ã\81«ã\82\88ã\82\8bã\83\87ã\82³ã\83¼ã\83\89ã\82¨ã\83©ã\83¼
* @throws IOException 入力エラー
*/
protected void notifyError(CoderResult result)
*
* <p>デコード作業の状況に応じてハンドラへの各種通知が行われる。
*
- * <p>ストリーム末端に到達するとデコード作業は終わり、
- * ストリームは閉じられる。
+ * <p>入力ストリーム末端に到達するとデコード作業は終わり、
+ * 入力ストリームは閉じられる。
*
* @param istream 入力ストリーム
- * @throws IOException å\85¥å\87ºå\8a\9bã\82¨ã\83©ã\83¼
- * @throws DecodeException デコードエラー
+ * @throws IOException 入力エラー
+ * @throws DecodeException ã\83\8fã\83³ã\83\89ã\83©ã\81«ã\82\88ã\82\8bã\83\87ã\82³ã\83¼ã\83\89ã\82¨ã\83©ã\83¼
*/
public void decode(InputStream istream)
throws IOException,
/**
* 内部チャネルのデコードを開始する。
*
- * @throws IOException å\85¥å\87ºå\8a\9bã\82¨ã\83©ã\83¼
- * @throws DecodeException デコードエラー
+ * @throws IOException 入力エラー
+ * @throws DecodeException ã\83\8fã\83³ã\83\89ã\83©ã\81«ã\82\88ã\82\8bã\83\87ã\82³ã\83¼ã\83\89ã\82¨ã\83©ã\83¼
*/
protected void decodeChannel()
throws IOException,
}
/**
- * 不適切なバッファサイズ由来の無限ループを検出し例外を投げる。
+ * 不適切な入力バッファサイズ由来の無限ループを検出し例外を投げる。
*
* <p>検出しなければ何もしない。
*