test: improve flag files
[nikiroo-utils.git] / src / be / nikiroo / fanfix / reader / Reader.java
... / ...
CommitLineData
1package be.nikiroo.fanfix.reader;
2
3import java.io.IOException;
4import java.net.URL;
5
6import be.nikiroo.fanfix.data.MetaData;
7import be.nikiroo.fanfix.data.Story;
8import be.nikiroo.fanfix.library.BasicLibrary;
9import be.nikiroo.fanfix.supported.SupportType;
10import 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 */
18public 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}