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