doc
[nikiroo-utils.git] / 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.utils.Progress;
10
11 /**
12 * A {@link Reader} is a class that will handle {@link Story} reading and
13 * browsing.
14 *
15 * @author niki
16 */
17 public interface Reader {
18 /**
19 * A type of {@link BasicReader}.
20 *
21 * @author niki
22 */
23 public enum ReaderType {
24 /** Simple reader that outputs everything on the console */
25 CLI,
26 /** Reader that starts local programs to handle the stories */
27 GUI,
28 /** A text (UTF-8) reader with menu and text windows */
29 TUI,
30
31 ;
32
33 /**
34 * Return the full class name of a type that implements said
35 * {@link ReaderType}.
36 *
37 * @return the class name
38 */
39 public String getTypeName() {
40 String pkg = "be.nikiroo.fanfix.reader.";
41 switch (this) {
42 case CLI:
43 return pkg + "CliReader";
44 case TUI:
45 return pkg + "TuiReader";
46 case GUI:
47 return pkg + "GuiReader";
48 }
49
50 return null;
51 }
52 }
53
54 /**
55 * Return the current target {@link MetaData}.
56 *
57 * @return the meta
58 */
59 public MetaData getMeta();
60
61 /**
62 * Return the current {@link Story} as described by the current
63 * {@link MetaData}.
64 *
65 * @param pg
66 * the optional progress
67 *
68 * @return the {@link Story}
69 */
70 public Story getStory(Progress pg);
71
72 /**
73 * The {@link BasicLibrary} to load the stories from (by default, takes the
74 * default {@link BasicLibrary}).
75 *
76 * @return the {@link BasicLibrary}
77 */
78 public BasicLibrary getLibrary();
79
80 /**
81 * Change the {@link BasicLibrary} that will be managed by this
82 * {@link BasicReader}.
83 *
84 * @param lib
85 * the new {@link BasicLibrary}
86 */
87 public void setLibrary(BasicLibrary lib);
88
89 /**
90 * Set a {@link Story} from the current {@link BasicLibrary} into the
91 * {@link Reader}.
92 *
93 * @param luid
94 * the {@link Story} ID
95 *
96 * @throws IOException
97 * in case of I/O error
98 */
99 public void setMeta(String luid) throws IOException;
100
101 /**
102 * Set a {@link Story} from the current {@link BasicLibrary} into the
103 * {@link Reader}.
104 *
105 * @param meta
106 * the meta
107 *
108 * @throws IOException
109 * in case of I/O error
110 */
111 public void setMeta(MetaData meta) throws IOException;
112
113 /**
114 * Set an external {@link Story} into this {@link Reader}.
115 *
116 * @param source
117 * the {@link Story} {@link URL}
118 * @param pg
119 * the optional progress reporter
120 *
121 * @throws IOException
122 * in case of I/O error
123 */
124 public void setMeta(URL source, Progress pg) throws IOException;
125
126 /**
127 * Start the {@link Story} Reading.
128 *
129 * @throws IOException
130 * in case of I/O error or if the {@link Story} was not
131 * previously set
132 */
133 public void read() throws IOException;
134
135 /**
136 * The selected chapter to start reading at (starting at 1, 0 = description,
137 * -1 = none).
138 *
139 * @return the chapter, or -1 for "no chapter"
140 */
141 public int getChapter();
142
143 /**
144 * The selected chapter to start reading at (starting at 1, 0 = description,
145 * -1 = none).
146 *
147 * @param chapter
148 * the chapter, or -1 for "no chapter"
149 */
150 public void setChapter(int chapter);
151
152 /**
153 * Start the reader in browse mode for the given source (or pass NULL for
154 * all sources).
155 *
156 * @param source
157 * the type of {@link Story} to take into account, or NULL for
158 * all
159 */
160 public void browse(String source);
161 }