Merge branch 'subtree'
[fanfix.git] / src / be / nikiroo / fanfix / reader / Reader.java
CommitLineData
e42573a0
NR
1package be.nikiroo.fanfix.reader;
2
3import java.io.IOException;
4import java.net.URL;
5
bc2ea776 6import be.nikiroo.fanfix.data.MetaData;
e42573a0
NR
7import be.nikiroo.fanfix.data.Story;
8import be.nikiroo.fanfix.library.BasicLibrary;
91b82a5c 9import be.nikiroo.fanfix.supported.SupportType;
e42573a0
NR
10import 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
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,
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}
0bb51c9c
NR
74 *
75 * @throws IOException
76 * in case of I/O error
77 *
e42573a0 78 */
0bb51c9c 79 public Story getStory(Progress pg) throws IOException;
e42573a0
NR
80
81 /**
bc2ea776
NR
82 * The {@link BasicLibrary} to load the stories from (by default, takes the
83 * default {@link BasicLibrary}).
e42573a0 84 *
bc2ea776 85 * @return the {@link BasicLibrary}
e42573a0
NR
86 */
87 public BasicLibrary getLibrary();
88
89 /**
bc2ea776 90 * Change the {@link BasicLibrary} that will be managed by this
e42573a0
NR
91 * {@link BasicReader}.
92 *
93 * @param lib
bc2ea776 94 * the new {@link BasicLibrary}
e42573a0 95 */
bc2ea776 96 public void setLibrary(BasicLibrary lib);
e42573a0
NR
97
98 /**
bc2ea776 99 * Set a {@link Story} from the current {@link BasicLibrary} into the
6322ab64 100 * {@link Reader}.
e42573a0
NR
101 *
102 * @param luid
103 * the {@link Story} ID
e42573a0
NR
104 *
105 * @throws IOException
106 * in case of I/O error
107 */
bc2ea776
NR
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;
e42573a0
NR
121
122 /**
6322ab64 123 * Set an external {@link Story} into this {@link Reader}.
e42573a0
NR
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 */
bc2ea776 133 public void setMeta(URL source, Progress pg) throws IOException;
e42573a0
NR
134
135 /**
136 * Start the {@link Story} Reading.
137 *
350bc060
NR
138 * @param sync
139 * execute the process synchronously (wait until it is terminated
140 * before returning)
141 *
e42573a0
NR
142 * @throws IOException
143 * in case of I/O error or if the {@link Story} was not
144 * previously set
145 */
350bc060 146 public void read(boolean sync) throws IOException;
e42573a0
NR
147
148 /**
bc2ea776
NR
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).
e42573a0
NR
159 *
160 * @param chapter
6322ab64 161 * the chapter, or -1 for "no chapter"
e42573a0 162 */
bc2ea776 163 public void setChapter(int chapter);
e42573a0
NR
164
165 /**
166 * Start the reader in browse mode for the given source (or pass NULL for
167 * all sources).
350bc060
NR
168 * <p>
169 * Note that this must be a <b>synchronous</b> action.
e42573a0
NR
170 *
171 * @param source
172 * the type of {@link Story} to take into account, or NULL for
173 * all
0bb51c9c
NR
174 *
175 * @throws IOException
176 * in case of I/O error
e42573a0 177 */
0bb51c9c 178 public void browse(String source) throws IOException;
16a81ef7 179
b31a0db0
NR
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
91b82a5c
NR
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)
f76de465
NR
205 * @param sync
206 * execute the process synchronously (wait until it is terminated
207 * before returning)
91b82a5c
NR
208 *
209 * @throws IOException
210 * in case of I/O error
211 */
f76de465
NR
212 public void search(SupportType searchOn, String keywords, int page,
213 int item, boolean sync) throws IOException;
91b82a5c
NR
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
8b153400 233 * pages, pages <b>start at 1</b>)
91b82a5c
NR
234 * @param item
235 * the item to select (0 = do not select a specific item but show
8b153400 236 * all the page, items <b>start at 1</b>)
f76de465
NR
237 * @param sync
238 * execute the process synchronously (wait until it is terminated
239 * before returning)
91b82a5c 240 * @param tags
8b153400 241 * the tags indices to search for (this is a tag
91b82a5c
NR
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,
f76de465 248 boolean sync, Integer... tags) throws IOException;
91b82a5c 249
16a81ef7 250 /**
350bc060 251 * Open the {@link Story} with an external reader (the program should be
16a81ef7
NR
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
350bc060
NR
258 * @param sync
259 * execute the process synchronously (wait until it is terminated
260 * before returning)
16a81ef7
NR
261 *
262 * @throws IOException
263 * in case of I/O error
264 */
350bc060
NR
265 public void openExternal(BasicLibrary lib, String luid, boolean sync)
266 throws IOException;
e42573a0 267}