Commit | Line | Data |
---|---|---|
e42573a0 NR |
1 | package be.nikiroo.fanfix.reader; |
2 | ||
3 | import java.io.IOException; | |
4 | import java.net.URL; | |
5 | ||
bc2ea776 | 6 | import be.nikiroo.fanfix.data.MetaData; |
e42573a0 NR |
7 | import be.nikiroo.fanfix.data.Story; |
8 | import be.nikiroo.fanfix.library.BasicLibrary; | |
91b82a5c | 9 | import be.nikiroo.fanfix.supported.SupportType; |
e42573a0 NR |
10 | import be.nikiroo.utils.Progress; |
11 | ||
bc2ea776 NR |
12 | /** |
13 | * A {@link Reader} is a class that will handle {@link Story} reading and | |
14 | * browsing. | |
15 | * | |
16 | * @author niki | |
17 | */ | |
e42573a0 NR |
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, | |
b4f9071c NR |
31 | /** A GUI reader implemented with the Android framework */ |
32 | ANDROID, | |
e42573a0 NR |
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: | |
16a81ef7 | 46 | return pkg + "cli.CliReader"; |
e42573a0 | 47 | case TUI: |
16a81ef7 | 48 | return pkg + "tui.TuiReader"; |
e42573a0 | 49 | case GUI: |
16a81ef7 | 50 | return pkg + "ui.GuiReader"; |
b4f9071c NR |
51 | case ANDROID: |
52 | return pkg + "android.AndroidReader"; | |
e42573a0 NR |
53 | } |
54 | ||
55 | return null; | |
56 | } | |
211f7ddb | 57 | } |
e42573a0 NR |
58 | |
59 | /** | |
bc2ea776 NR |
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 | |
e42573a0 NR |
72 | * |
73 | * @return the {@link Story} | |
74 | */ | |
bc2ea776 | 75 | public Story getStory(Progress pg); |
e42573a0 NR |
76 | |
77 | /** | |
bc2ea776 NR |
78 | * The {@link BasicLibrary} to load the stories from (by default, takes the |
79 | * default {@link BasicLibrary}). | |
e42573a0 | 80 | * |
bc2ea776 | 81 | * @return the {@link BasicLibrary} |
e42573a0 NR |
82 | */ |
83 | public BasicLibrary getLibrary(); | |
84 | ||
85 | /** | |
bc2ea776 | 86 | * Change the {@link BasicLibrary} that will be managed by this |
e42573a0 NR |
87 | * {@link BasicReader}. |
88 | * | |
89 | * @param lib | |
bc2ea776 | 90 | * the new {@link BasicLibrary} |
e42573a0 | 91 | */ |
bc2ea776 | 92 | public void setLibrary(BasicLibrary lib); |
e42573a0 NR |
93 | |
94 | /** | |
bc2ea776 | 95 | * Set a {@link Story} from the current {@link BasicLibrary} into the |
6322ab64 | 96 | * {@link Reader}. |
e42573a0 NR |
97 | * |
98 | * @param luid | |
99 | * the {@link Story} ID | |
e42573a0 NR |
100 | * |
101 | * @throws IOException | |
102 | * in case of I/O error | |
103 | */ | |
bc2ea776 NR |
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; | |
e42573a0 NR |
117 | |
118 | /** | |
6322ab64 | 119 | * Set an external {@link Story} into this {@link Reader}. |
e42573a0 NR |
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 | */ | |
bc2ea776 | 129 | public void setMeta(URL source, Progress pg) throws IOException; |
e42573a0 NR |
130 | |
131 | /** | |
132 | * Start the {@link Story} Reading. | |
133 | * | |
350bc060 NR |
134 | * @param sync |
135 | * execute the process synchronously (wait until it is terminated | |
136 | * before returning) | |
137 | * | |
e42573a0 NR |
138 | * @throws IOException |
139 | * in case of I/O error or if the {@link Story} was not | |
140 | * previously set | |
141 | */ | |
350bc060 | 142 | public void read(boolean sync) throws IOException; |
e42573a0 NR |
143 | |
144 | /** | |
bc2ea776 NR |
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). | |
e42573a0 NR |
155 | * |
156 | * @param chapter | |
6322ab64 | 157 | * the chapter, or -1 for "no chapter" |
e42573a0 | 158 | */ |
bc2ea776 | 159 | public void setChapter(int chapter); |
e42573a0 NR |
160 | |
161 | /** | |
162 | * Start the reader in browse mode for the given source (or pass NULL for | |
163 | * all sources). | |
350bc060 NR |
164 | * <p> |
165 | * Note that this must be a <b>synchronous</b> action. | |
e42573a0 NR |
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); | |
16a81ef7 | 172 | |
91b82a5c NR |
173 | /** |
174 | * Search for the given terms and find stories that correspond if possible. | |
175 | * | |
176 | * @param searchOn | |
177 | * the website to search on | |
178 | * @param keywords | |
179 | * the words to search for (cannot be NULL) | |
180 | * @param page | |
181 | * the page of results to show (0 = request the maximum number of | |
182 | * pages, pages start at 1) | |
183 | * @param item | |
184 | * the item to select (0 = do not select a specific item but show | |
185 | * all the page, items start at 1) | |
f76de465 NR |
186 | * @param sync |
187 | * execute the process synchronously (wait until it is terminated | |
188 | * before returning) | |
91b82a5c NR |
189 | * |
190 | * @throws IOException | |
191 | * in case of I/O error | |
192 | */ | |
f76de465 NR |
193 | public void search(SupportType searchOn, String keywords, int page, |
194 | int item, boolean sync) throws IOException; | |
91b82a5c NR |
195 | |
196 | /** | |
197 | * Search based upon a hierarchy of tags, or search for (sub)tags. | |
198 | * <p> | |
199 | * We use the tags <tt>DisplayName</tt>. | |
200 | * <p> | |
201 | * If no tag is given, the main tags will be shown. | |
202 | * <p> | |
203 | * If a non-leaf tag is given, the subtags will be shown. | |
204 | * <p> | |
205 | * If a leaf tag is given (or a full hierarchy ending with a leaf tag), | |
206 | * stories will be shown. | |
207 | * <p> | |
208 | * You can select the story you want with the <tt>item</tt> number. | |
209 | * | |
210 | * @param searchOn | |
211 | * the website to search on | |
212 | * @param page | |
213 | * the page of results to show (0 = request the maximum number of | |
8b153400 | 214 | * pages, pages <b>start at 1</b>) |
91b82a5c NR |
215 | * @param item |
216 | * the item to select (0 = do not select a specific item but show | |
8b153400 | 217 | * all the page, items <b>start at 1</b>) |
f76de465 NR |
218 | * @param sync |
219 | * execute the process synchronously (wait until it is terminated | |
220 | * before returning) | |
91b82a5c | 221 | * @param tags |
8b153400 | 222 | * the tags indices to search for (this is a tag |
91b82a5c NR |
223 | * <b>hierarchy</b>, <b>NOT</b> a multiple tags choice) |
224 | * | |
225 | * @throws IOException | |
226 | * in case of I/O error | |
227 | */ | |
228 | public void searchTag(SupportType searchOn, int page, int item, | |
f76de465 | 229 | boolean sync, Integer... tags) throws IOException; |
91b82a5c | 230 | |
16a81ef7 | 231 | /** |
350bc060 | 232 | * Open the {@link Story} with an external reader (the program should be |
16a81ef7 NR |
233 | * passed the main file associated with this {@link Story}). |
234 | * | |
235 | * @param lib | |
236 | * the {@link BasicLibrary} to select the {@link Story} from | |
237 | * @param luid | |
238 | * the {@link Story} LUID | |
350bc060 NR |
239 | * @param sync |
240 | * execute the process synchronously (wait until it is terminated | |
241 | * before returning) | |
16a81ef7 NR |
242 | * |
243 | * @throws IOException | |
244 | * in case of I/O error | |
245 | */ | |
350bc060 NR |
246 | public void openExternal(BasicLibrary lib, String luid, boolean sync) |
247 | throws IOException; | |
e42573a0 | 248 | } |