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

   1 /*
   2  * basic handler for XHTML
   3  *
   4  * License : The MIT License
   5  * Copyright(c) 2009 olyutorskii
   6  */
   7
   8 package jp.sourceforge.jindolf.parser;
   9
  10 import jp.sourceforge.jindolf.corelib.PeriodType;
  11 import jp.sourceforge.jindolf.corelib.VillageState;
  12
  13 /**
  14  * 人狼BBSの各種XHTMLの基本的な構造をパースするためのハンドラ。
  15  * このハンドラの全メソッドはパーサ{@link HtmlParser}により呼ばれる。
  16  *
  17  * <p>
  18  * パーサはパース開始時に{@link #startParse(DecodedContent)}を呼び、
  19  * パース終了直前に{@link #endParse()}を呼ぶ。
  20  * その間に他の様々なメソッドが呼び出される。
  21  * </p>
  22  *
  23  * <p>
  24  * 一部のメソッドに渡される{@link DecodedContent}文字列オブジェクトは
  25  * mutableである。
  26  * 後々で内容が必要になるならば、ハンドラはSeqRangeで示されたこの内容の
  27  * 必要な箇所をコピーして保存しなければならない。
  28  * </p>
  29  *
  30  * <p>
  31  * フラグメントや属性値中の文字参照記号列の解釈はハンドラ側の責務とする。
  32  * </p>
  33  *
  34  * <p>
  35  * 各メソッドは、各々の判断で{@link HtmlParseException}をスローする
  36  * ことにより、パース作業を中断させることができる。
  37  * </p>
  38  */
  39 public interface BasicHandler{
  40
  41     /**
  42      * パース開始の通知を受け取る。
  43      * @param content これからパースを始めるXHTML文字列
  44      * @throws HtmlParseException パースエラー
  45      */
  46     void startParse(DecodedContent content) throws HtmlParseException;
  47
  48     /**
  49      * titleタグの内容の通知を受け取る。
  50      * 例：「人狼BBS:F F2019 新緑の村」。
  51      * @param content パース対象文字列
  52      * @param titleRange タイトルの範囲
  53      * @throws HtmlParseException パースエラー
  54      */
  55     void pageTitle(DecodedContent content, SeqRange titleRange)
  56             throws HtmlParseException;
  57
  58     /**
  59      * ログイン名(ID)の通知を受け取る。
  60      * ログインせずに得られたページがパース対象であるなら、呼ばれない。
  61      * F国のみで動作確認。
  62      * @param content パース対象文字列
  63      * @param loginRange ログイン名の範囲
  64      * @throws HtmlParseException パースエラー
  65      */
  66     void loginName(DecodedContent content, SeqRange loginRange)
  67             throws HtmlParseException;
  68
  69     /**
  70      * 読み込んだページ種別を自動認識した結果を伝える。
  71      * ページタイトルもしくはログイン名の通知の後に呼ばれうる。
  72      * @param type ページ種別
  73      * @throws HtmlParseException パースエラー
  74      */
  75     void pageType(PageType type)
  76             throws HtmlParseException;
  77
  78     /**
  79      * 村の名前の通知を受け取る。
  80      * 国名と番号と愛称に分解するのはハンドラ側の責務。
  81      * 例：「F2019 新緑の村」。
  82      * @param content パース対象文字列
  83      * @param villageRange 村名の範囲
  84      * @throws HtmlParseException パースエラー
  85      */
  86     void villageName(DecodedContent content, SeqRange villageRange)
  87             throws HtmlParseException;
  88
  89     /**
  90      * 次回更新時刻の通知を受け取る。
  91      * 既に終了した村がパース対象の場合、あまり月日に意味はないかも。
  92      * @param month 更新月
  93      * @param day 更新日
  94      * @param hour 更新時
  95      * @param minute 更新分
  96      * @throws HtmlParseException パースエラー
  97      */
  98     void commitTime(int month, int day, int hour, int minute)
  99             throws HtmlParseException;
 100
 101     /**
 102      * 他の日へのリンクの通知を受け取る。
 103      * 複数回呼ばれる場合がある。
 104      * @param content パース対象文字列
 105      * @param anchorRange aタグhref属性値の範囲
 106      * @param periodType 日のタイプ。「終了」ならnull。
 107      * @param day 日にち。「プロローグ」、「エピローグ」、「終了」では-1。
 108      * @throws HtmlParseException パースエラー
 109      */
 110     void periodLink(DecodedContent content,
 111                      SeqRange anchorRange,
 112                      PeriodType periodType, int day)
 113             throws HtmlParseException;
 114
 115     /**
 116      * 村一覧リスト内の個別の村情報の通知を受け取る。
 117      * @param content パース対象文字列
 118      * @param anchorRange URLの範囲
 119      * @param villageRange 村名の範囲
 120      * @param hour 更新時。不明なら負の数。
 121      * @param minute 更新分。不明なら負の数。
 122      * @param state 村の状態
 123      * @throws HtmlParseException パースエラー
 124      */
 125     void villageRecord(DecodedContent content,
 126                          SeqRange anchorRange,
 127                          SeqRange villageRange,
 128                          int hour, int minute,
 129                          VillageState state )
 130             throws HtmlParseException;
 131
 132     /**
 133      * パースの終了の通知を受け取る。
 134      * @throws HtmlParseException パースエラー
 135      */
 136     void endParse() throws HtmlParseException;
 137
 138 }