reader/Reader.java

   1 package be.nikiroo.fanfix.reader;
   2
   3 import java.io.IOException;
   4 import java.net.URL;
   5
   6 import be.nikiroo.fanfix.data.MetaData;
   7 import be.nikiroo.fanfix.data.Story;
   8 import be.nikiroo.fanfix.library.BasicLibrary;
   9 import be.nikiroo.fanfix.supported.SupportType;
  10 import be.nikiroo.utils.Progress;
  11
  12 /**
  13  * A {@link Reader} is a class that will handle {@link Story} reading and
  14  * browsing.
  15  *
  16  * @author niki
  17  */
  18 public interface Reader {
  19         /**
  20          * A type of {@link BasicReader}.
  21          *
  22          * @author niki
  23          */
  24         public enum ReaderType {
  25                 /** Simple reader that outputs everything on the console */
  26                 CLI,
  27                 /** Reader that starts local programs to handle the stories */
  28                 GUI,
  29                 /** A text (UTF-8) reader with menu and text windows */
  30                 TUI,
  31                 /** A GUI reader implemented with the Android framework */
  32                 ANDROID,
  33
  34                 ;
  35
  36                 /**
  37                  * Return the full class name of a type that implements said
  38                  * {@link ReaderType}.
  39                  *
  40                  * @return the class name
  41                  */
  42                 public String getTypeName() {
  43                         String pkg = "be.nikiroo.fanfix.reader.";
  44                         switch (this) {
  45                         case CLI:
  46                                 return pkg + "cli.CliReader";
  47                         case TUI:
  48                                 return pkg + "tui.TuiReader";
  49                         case GUI:
  50                                 return pkg + "ui.GuiReader";
  51                         case ANDROID:
  52                                 return pkg + "android.AndroidReader";
  53                         }
  54
  55                         return null;
  56                 }
  57         }
  58
  59         /**
  60          * Return the current target {@link MetaData}.
  61          *
  62          * @return the meta
  63          */
  64         public MetaData getMeta();
  65
  66         /**
  67          * Return the current {@link Story} as described by the current
  68          * {@link MetaData}.
  69          *
  70          * @param pg
  71          *            the optional progress
  72          *
  73          * @return the {@link Story}
  74          *
  75          * @throws IOException
  76          *             in case of I/O error
  77          *
  78          */
  79         public Story getStory(Progress pg) throws IOException;
  80
  81         /**
  82          * The {@link BasicLibrary} to load the stories from (by default, takes the
  83          * default {@link BasicLibrary}).
  84          *
  85          * @return the {@link BasicLibrary}
  86          */
  87         public BasicLibrary getLibrary();
  88
  89         /**
  90          * Change the {@link BasicLibrary} that will be managed by this
  91          * {@link BasicReader}.
  92          *
  93          * @param lib
  94          *            the new {@link BasicLibrary}
  95          */
  96         public void setLibrary(BasicLibrary lib);
  97
  98         /**
  99          * Set a {@link Story} from the current {@link BasicLibrary} into the
 100          * {@link Reader}.
 101          *
 102          * @param luid
 103          *            the {@link Story} ID
 104          *
 105          * @throws IOException
 106          *             in case of I/O error
 107          */
 108         public void setMeta(String luid) throws IOException;
 109
 110         /**
 111          * Set a {@link Story} from the current {@link BasicLibrary} into the
 112          * {@link Reader}.
 113          *
 114          * @param meta
 115          *            the meta
 116          *
 117          * @throws IOException
 118          *             in case of I/O error
 119          */
 120         public void setMeta(MetaData meta) throws IOException;
 121
 122         /**
 123          * Set an external {@link Story} into this {@link Reader}.
 124          *
 125          * @param source
 126          *            the {@link Story} {@link URL}
 127          * @param pg
 128          *            the optional progress reporter
 129          *
 130          * @throws IOException
 131          *             in case of I/O error
 132          */
 133         public void setMeta(URL source, Progress pg) throws IOException;
 134
 135         /**
 136          * Start the {@link Story} Reading.
 137          *
 138          * @param sync
 139          *            execute the process synchronously (wait until it is terminated
 140          *            before returning)
 141          *
 142          * @throws IOException
 143          *             in case of I/O error or if the {@link Story} was not
 144          *             previously set
 145          */
 146         public void read(boolean sync) throws IOException;
 147
 148         /**
 149          * The selected chapter to start reading at (starting at 1, 0 = description,
 150          * -1 = none).
 151          *
 152          * @return the chapter, or -1 for "no chapter"
 153          */
 154         public int getChapter();
 155
 156         /**
 157          * The selected chapter to start reading at (starting at 1, 0 = description,
 158          * -1 = none).
 159          *
 160          * @param chapter
 161          *            the chapter, or -1 for "no chapter"
 162          */
 163         public void setChapter(int chapter);
 164
 165         /**
 166          * Start the reader in browse mode for the given source (or pass NULL for
 167          * all sources).
 168          * <p>
 169          * Note that this must be a <b>synchronous</b> action.
 170          *
 171          * @param source
 172          *            the type of {@link Story} to take into account, or NULL for
 173          *            all
 174          *
 175          * @throws IOException
 176          *             in case of I/O error
 177          */
 178         public void browse(String source) throws IOException;
 179
 180         /**
 181          * Display all supports that allow search operations.
 182          *
 183          * @param sync
 184          *            execute the process synchronously (wait until it is terminated
 185          *            before returning)
 186          *
 187          * @throws IOException
 188          *             in case of I/O error
 189          */
 190         public void search(boolean sync) throws IOException;
 191
 192         /**
 193          * Search for the given terms and find stories that correspond if possible.
 194          *
 195          * @param searchOn
 196          *            the website to search on
 197          * @param keywords
 198          *            the words to search for (cannot be NULL)
 199          * @param page
 200          *            the page of results to show (0 = request the maximum number of
 201          *            pages, pages start at 1)
 202          * @param item
 203          *            the item to select (0 = do not select a specific item but show
 204          *            all the page, items start at 1)
 205          * @param sync
 206          *            execute the process synchronously (wait until it is terminated
 207          *            before returning)
 208          *
 209          * @throws IOException
 210          *             in case of I/O error
 211          */
 212         public void search(SupportType searchOn, String keywords, int page,
 213                         int item, boolean sync) throws IOException;
 214
 215         /**
 216          * Search based upon a hierarchy of tags, or search for (sub)tags.
 217          * <p>
 218          * We use the tags <tt>DisplayName</tt>.
 219          * <p>
 220          * If no tag is given, the main tags will be shown.
 221          * <p>
 222          * If a non-leaf tag is given, the subtags will be shown.
 223          * <p>
 224          * If a leaf tag is given (or a full hierarchy ending with a leaf tag),
 225          * stories will be shown.
 226          * <p>
 227          * You can select the story you want with the <tt>item</tt> number.
 228          *
 229          * @param searchOn
 230          *            the website to search on
 231          * @param page
 232          *            the page of results to show (0 = request the maximum number of
 233          *            pages, pages <b>start at 1</b>)
 234          * @param item
 235          *            the item to select (0 = do not select a specific item but show
 236          *            all the page, items <b>start at 1</b>)
 237          * @param sync
 238          *            execute the process synchronously (wait until it is terminated
 239          *            before returning)
 240          * @param tags
 241          *            the tags indices to search for (this is a tag
 242          *            <b>hierarchy</b>, <b>NOT</b> a multiple tags choice)
 243          *
 244          * @throws IOException
 245          *             in case of I/O error
 246          */
 247         public void searchTag(SupportType searchOn, int page, int item,
 248                         boolean sync, Integer... tags) throws IOException;
 249
 250         /**
 251          * Open the {@link Story} with an external reader (the program should be
 252          * passed the main file associated with this {@link Story}).
 253          *
 254          * @param lib
 255          *            the {@link BasicLibrary} to select the {@link Story} from
 256          * @param luid
 257          *            the {@link Story} LUID
 258          * @param sync
 259          *            execute the process synchronously (wait until it is terminated
 260          *            before returning)
 261          *
 262          * @throws IOException
 263          *             in case of I/O error
 264          */
 265         public void openExternal(BasicLibrary lib, String luid, boolean sync)
 266                         throws IOException;
 267 }