src/be/nikiroo/fanfix/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         public Story getStory(Progress pg);
  76
  77         /**
  78          * The {@link BasicLibrary} to load the stories from (by default, takes the
  79          * default {@link BasicLibrary}).
  80          *
  81          * @return the {@link BasicLibrary}
  82          */
  83         public BasicLibrary getLibrary();
  84
  85         /**
  86          * Change the {@link BasicLibrary} that will be managed by this
  87          * {@link BasicReader}.
  88          *
  89          * @param lib
  90          *            the new {@link BasicLibrary}
  91          */
  92         public void setLibrary(BasicLibrary lib);
  93
  94         /**
  95          * Set a {@link Story} from the current {@link BasicLibrary} into the
  96          * {@link Reader}.
  97          *
  98          * @param luid
  99          *            the {@link Story} ID
 100          *
 101          * @throws IOException
 102          *             in case of I/O error
 103          */
 104         public void setMeta(String luid) throws IOException;
 105
 106         /**
 107          * Set a {@link Story} from the current {@link BasicLibrary} into the
 108          * {@link Reader}.
 109          *
 110          * @param meta
 111          *            the meta
 112          *
 113          * @throws IOException
 114          *             in case of I/O error
 115          */
 116         public void setMeta(MetaData meta) throws IOException;
 117
 118         /**
 119          * Set an external {@link Story} into this {@link Reader}.
 120          *
 121          * @param source
 122          *            the {@link Story} {@link URL}
 123          * @param pg
 124          *            the optional progress reporter
 125          *
 126          * @throws IOException
 127          *             in case of I/O error
 128          */
 129         public void setMeta(URL source, Progress pg) throws IOException;
 130
 131         /**
 132          * Start the {@link Story} Reading.
 133          *
 134          * @param sync
 135          *            execute the process synchronously (wait until it is terminated
 136          *            before returning)
 137          *
 138          * @throws IOException
 139          *             in case of I/O error or if the {@link Story} was not
 140          *             previously set
 141          */
 142         public void read(boolean sync) throws IOException;
 143
 144         /**
 145          * The selected chapter to start reading at (starting at 1, 0 = description,
 146          * -1 = none).
 147          *
 148          * @return the chapter, or -1 for "no chapter"
 149          */
 150         public int getChapter();
 151
 152         /**
 153          * The selected chapter to start reading at (starting at 1, 0 = description,
 154          * -1 = none).
 155          *
 156          * @param chapter
 157          *            the chapter, or -1 for "no chapter"
 158          */
 159         public void setChapter(int chapter);
 160
 161         /**
 162          * Start the reader in browse mode for the given source (or pass NULL for
 163          * all sources).
 164          * <p>
 165          * Note that this must be a <b>synchronous</b> action.
 166          *
 167          * @param source
 168          *            the type of {@link Story} to take into account, or NULL for
 169          *            all
 170          */
 171         public void browse(String source);
 172
 173         /**
 174          * Display all supports that allow search operations.
 175          *
 176          * @param sync
 177          *            execute the process synchronously (wait until it is terminated
 178          *            before returning)
 179          *
 180          * @throws IOException
 181          *             in case of I/O error
 182          */
 183         public void search(boolean sync) throws IOException;
 184
 185         /**
 186          * Search for the given terms and find stories that correspond if possible.
 187          *
 188          * @param searchOn
 189          *            the website to search on
 190          * @param keywords
 191          *            the words to search for (cannot be NULL)
 192          * @param page
 193          *            the page of results to show (0 = request the maximum number of
 194          *            pages, pages start at 1)
 195          * @param item
 196          *            the item to select (0 = do not select a specific item but show
 197          *            all the page, items start at 1)
 198          * @param sync
 199          *            execute the process synchronously (wait until it is terminated
 200          *            before returning)
 201          *
 202          * @throws IOException
 203          *             in case of I/O error
 204          */
 205         public void search(SupportType searchOn, String keywords, int page,
 206                         int item, boolean sync) throws IOException;
 207
 208         /**
 209          * Search based upon a hierarchy of tags, or search for (sub)tags.
 210          * <p>
 211          * We use the tags <tt>DisplayName</tt>.
 212          * <p>
 213          * If no tag is given, the main tags will be shown.
 214          * <p>
 215          * If a non-leaf tag is given, the subtags will be shown.
 216          * <p>
 217          * If a leaf tag is given (or a full hierarchy ending with a leaf tag),
 218          * stories will be shown.
 219          * <p>
 220          * You can select the story you want with the <tt>item</tt> number.
 221          *
 222          * @param searchOn
 223          *            the website to search on
 224          * @param page
 225          *            the page of results to show (0 = request the maximum number of
 226          *            pages, pages <b>start at 1</b>)
 227          * @param item
 228          *            the item to select (0 = do not select a specific item but show
 229          *            all the page, items <b>start at 1</b>)
 230          * @param sync
 231          *            execute the process synchronously (wait until it is terminated
 232          *            before returning)
 233          * @param tags
 234          *            the tags indices to search for (this is a tag
 235          *            <b>hierarchy</b>, <b>NOT</b> a multiple tags choice)
 236          *
 237          * @throws IOException
 238          *             in case of I/O error
 239          */
 240         public void searchTag(SupportType searchOn, int page, int item,
 241                         boolean sync, Integer... tags) throws IOException;
 242
 243         /**
 244          * Open the {@link Story} with an external reader (the program should be
 245          * passed the main file associated with this {@link Story}).
 246          *
 247          * @param lib
 248          *            the {@link BasicLibrary} to select the {@link Story} from
 249          * @param luid
 250          *            the {@link Story} LUID
 251          * @param sync
 252          *            execute the process synchronously (wait until it is terminated
 253          *            before returning)
 254          *
 255          * @throws IOException
 256          *             in case of I/O error
 257          */
 258         public void openExternal(BasicLibrary lib, String luid, boolean sync)
 259                         throws IOException;
 260 }