src/main/java/jp/sourceforge/jindolf/parser/DecodeHandler.java

   1 /*
   2  * decode handler
   3  *
   4  * License : The MIT License
   5  * Copyright(c) 2009 olyutorskii
   6  */
   7
   8 package jp.sourceforge.jindolf.parser;
   9
  10 import java.nio.charset.CharsetDecoder;
  11
  12 /**
  13  * 文字デコードハンドラ。
  14  * {@link StreamDecoder}により呼び出される。
  15  *
  16  * <p>デコード処理を通じてメソッドが呼ばれる順番は
  17  * {@link #startDecoding}が最初で
  18  * {@link #endDecoding}が最後。
  19  * その間、{@link #charContent}
  20  * または{@link #decodingError}が複数回呼ばれる。
  21  *
  22  * <p>各メソッドは、{@link DecodeException}をスローすることで
  23  * デコード処理を中止させることができる。
  24  */
  25 public interface DecodeHandler{
  26
  27     /**
  28      * デコード処理開始の通知を受け取る。
  29      *
  30      * <p>渡された文字デコーダの各種設定を変更してはならない。
  31      *
  32      * @param decoder 文字デコーダ
  33      * @throws DecodeException デコードエラー
  34      */
  35     void startDecoding(CharsetDecoder decoder)
  36             throws DecodeException;
  37
  38     /**
  39      * 正常にデコードした文字列の通知を受け取る。
  40      *
  41      * <p>seqの内容は、ハンドラ呼び出し元で随時変更されうる。
  42      * seqの内容を後々再利用するつもりなら、
  43      * 制御を呼び出し元に戻すまでの間に必要な箇所をコピーする必要がある。
  44      *
  45      * @param seq 文字列
  46      * @throws DecodeException デコードエラー
  47      */
  48     void charContent(CharSequence seq)
  49             throws DecodeException;
  50
  51     /**
  52      * デコードエラーの通知を受け取る。
  53      *
  54      * <p>errorArrayの内容は、ハンドラ呼び出し元で随時変更されうる。
  55      * errorArrayの内容を後々再利用するつもりなら、
  56      * 制御を呼び出し元に戻すまでの間に必要な箇所をコピーする必要がある。
  57      *
  58      * @param errorArray エラーを引き起こした入力バイトシーケンス。
  59      * @param offset errorArrayに含まれるエラーの開始位置。
  60      * @param length errorArrayに含まれるエラーのバイト長。
  61      * @throws DecodeException デコードエラー
  62      */
  63     void decodingError(byte[] errorArray, int offset, int length)
  64             throws DecodeException;
  65
  66     /**
  67      * デコード処理終了の通知を受け取る。
  68      *
  69      * @throws DecodeException デコードエラー
  70      */
  71     void endDecoding()
  72             throws DecodeException;
  73
  74 }