update nikiroo-utils
[fanfix.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 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}