Classes in this File | Line Coverage | Branch Coverage | Complexity | ||||
BookMetaData |
|
| 1.0;1 |
1 | /** | |
2 | * Distribution License: | |
3 | * JSword is free software; you can redistribute it and/or modify it under | |
4 | * the terms of the GNU Lesser General Public License, version 2.1 or later | |
5 | * as published by the Free Software Foundation. This program is distributed | |
6 | * in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even | |
7 | * the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. | |
8 | * See the GNU Lesser General Public License for more details. | |
9 | * | |
10 | * The License is available on the internet at: | |
11 | * http://www.gnu.org/copyleft/lgpl.html | |
12 | * or by writing to: | |
13 | * Free Software Foundation, Inc. | |
14 | * 59 Temple Place - Suite 330 | |
15 | * Boston, MA 02111-1307, USA | |
16 | * | |
17 | * © CrossWire Bible Society, 2005 - 2016 | |
18 | * | |
19 | */ | |
20 | package org.crosswire.jsword.book; | |
21 | ||
22 | import java.net.URI; | |
23 | import java.util.Set; | |
24 | ||
25 | import org.crosswire.common.util.Language; | |
26 | import org.crosswire.jsword.index.IndexStatus; | |
27 | import org.jdom2.Document; | |
28 | ||
29 | /** | |
30 | * A BookMetaData represents a method of translating the Bible. All Books with | |
31 | * the same BookMetaData should return identical text for any call to | |
32 | * <code>Bible.getText(VerseRange)</code>. The implication of this is that there | |
33 | * may be many instances of the Version "NIV", as there are several different | |
34 | * versions of the NIV - Original American-English, Anglicised, and Inclusive | |
35 | * Language editions at least. | |
36 | * | |
37 | * <p> | |
38 | * BookMetaData like Strings must be compared using <code>.equals()</code> | |
39 | * instead of ==. A Bible must have the ability to handle a book unknown to | |
40 | * JSword. So Books must be able to add versions to the system, and the system | |
41 | * must cope with books that already exist. | |
42 | * </p> | |
43 | * | |
44 | * @see gnu.lgpl.License The GNU Lesser General Public License for details. | |
45 | * @author Joe Walker | |
46 | */ | |
47 | public interface BookMetaData extends Comparable<BookMetaData> { | |
48 | /** | |
49 | * The name of the book, for example "King James Version" or | |
50 | * "Bible in Basic English" or "Greek". This method should not | |
51 | * return null or a blank string. | |
52 | * | |
53 | * @return The name of this book | |
54 | */ | |
55 | String getName(); | |
56 | ||
57 | /** | |
58 | * With which Charset is this Book encoded? | |
59 | * | |
60 | * @return the encoding of the Book | |
61 | */ | |
62 | String getBookCharset(); | |
63 | ||
64 | /** | |
65 | * How this Book organizes it's keys. | |
66 | * | |
67 | * @return the organization of keys of this Book | |
68 | */ | |
69 | KeyType getKeyType(); | |
70 | ||
71 | /** | |
72 | * What category of content is this, a Bible or a reference work like a | |
73 | * Dictionary or Commentary. | |
74 | * | |
75 | * @return The category of book | |
76 | */ | |
77 | BookCategory getBookCategory(); | |
78 | ||
79 | /** | |
80 | * Accessor for the driver that runs this Book. Note this method should only | |
81 | * be used to delete() Books. Everything else you should want to do to a | |
82 | * Book should be available in other ways. | |
83 | * | |
84 | * @return the driver for the book. | |
85 | */ | |
86 | BookDriver getDriver(); | |
87 | ||
88 | /** | |
89 | * The language of the book. | |
90 | * | |
91 | * @return the book's language | |
92 | */ | |
93 | Language getLanguage(); | |
94 | ||
95 | /** | |
96 | * Set the language for this book. | |
97 | * | |
98 | * @param language | |
99 | * the book's language | |
100 | */ | |
101 | void setLanguage(Language language); | |
102 | ||
103 | /** | |
104 | * The initials of this book - how people familiar with this book will know | |
105 | * it, for example "NIV", "KJV". | |
106 | * | |
107 | * @return The book's initials | |
108 | */ | |
109 | String getAbbreviation(); | |
110 | ||
111 | /** | |
112 | * The internal name of this book. | |
113 | * | |
114 | * @return The book's internal name | |
115 | */ | |
116 | String getInitials(); | |
117 | ||
118 | /** | |
119 | * Calculated field: Get an OSIS identifier for the OsisText.setOsisIDWork() | |
120 | * and the Work.setOsisWork() methods. The response will generally be of the | |
121 | * form [Bible][Dict..].getInitials | |
122 | * | |
123 | * @return The osis id of this book | |
124 | */ | |
125 | String getOsisID(); | |
126 | ||
127 | /** | |
128 | * Indicate whether this book is supported by JSword. Since the expectation | |
129 | * is that all books are supported, abstract implementations should return | |
130 | * true and let specific implementations return false if they cannot support | |
131 | * the book. | |
132 | * | |
133 | * @return true if the book is supported | |
134 | */ | |
135 | boolean isSupported(); | |
136 | ||
137 | /** | |
138 | * Indicate whether this book is enciphered. Since the expectation is that | |
139 | * most books are unenciphered, abstract implementations should return false | |
140 | * and let specific implementations return true otherwise. | |
141 | * | |
142 | * @return true if the book is enciphered | |
143 | */ | |
144 | boolean isEnciphered(); | |
145 | ||
146 | /** | |
147 | * Indicate whether this book is enciphered and without a key. Since the | |
148 | * expectation is that most books are unenciphered, abstract implementations | |
149 | * should return false and let specific implementations return true | |
150 | * otherwise. | |
151 | * | |
152 | * @return true if the book is locked | |
153 | */ | |
154 | boolean isLocked(); | |
155 | ||
156 | /** | |
157 | * Unlocks a book with the given key. | |
158 | * | |
159 | * @param unlockKey | |
160 | * the key to try | |
161 | * @return true if the unlock key worked. | |
162 | */ | |
163 | boolean unlock(String unlockKey); | |
164 | ||
165 | /** | |
166 | * Gets the unlock key for the module. | |
167 | * | |
168 | * @return the unlock key, if any, null otherwise. | |
169 | */ | |
170 | String getUnlockKey(); | |
171 | ||
172 | /** | |
173 | * Indicate whether this book is questionable. A book may be deemed | |
174 | * questionable if it's quality or content has not been confirmed. Since the | |
175 | * expectation is that all books are not questionable, abstract | |
176 | * implementations should return false and let specific implementations | |
177 | * return true if the book is questionable. | |
178 | * | |
179 | * @return true if the book is questionable | |
180 | */ | |
181 | boolean isQuestionable(); | |
182 | ||
183 | /** | |
184 | * Calculated field: The name of the name, which could be helpful to | |
185 | * distinguish similar Books available through 2 BookDrivers. | |
186 | * | |
187 | * @return The driver name | |
188 | */ | |
189 | String getDriverName(); | |
190 | ||
191 | /** | |
192 | * Return the orientation of the script of the Book. If a book contains more | |
193 | * than one script, it refers to the dominate script of the book. This will | |
194 | * be used to present Arabic and Hebrew in their proper orientation. Note: | |
195 | * some languages have multiple scripts which don't have the same | |
196 | * directionality. | |
197 | * | |
198 | * @return true if the orientation for the dominate script is LeftToRight. | |
199 | */ | |
200 | boolean isLeftToRight(); | |
201 | ||
202 | /** | |
203 | * Return whether the feature is supported by the book. | |
204 | * | |
205 | * @param feature the feature in question | |
206 | * @return true if the book supports the feature | |
207 | */ | |
208 | boolean hasFeature(FeatureType feature); | |
209 | ||
210 | /** | |
211 | * Get the base URI for library of this module. | |
212 | * | |
213 | * @return the base URI or null if there is none | |
214 | */ | |
215 | URI getLibrary(); | |
216 | ||
217 | /** | |
218 | * Set the base URI for library of this module. | |
219 | * | |
220 | * @param library | |
221 | * the base URI or null if there is none | |
222 | * @throws BookException indicates missing data files | |
223 | */ | |
224 | void setLibrary(URI library) throws BookException; | |
225 | ||
226 | /** | |
227 | * Get the base URI for relative URIs in the document. | |
228 | * | |
229 | * @return the base URI or null if there is none | |
230 | */ | |
231 | URI getLocation(); | |
232 | ||
233 | /** | |
234 | * Set the base URI for relative URIs in the document. | |
235 | * | |
236 | * @param library | |
237 | * the base URI or null if there is none | |
238 | */ | |
239 | void setLocation(URI library); | |
240 | ||
241 | /** | |
242 | * If this BookMetaData is partially loaded, reload it fully. | |
243 | * If it is fully loaded, don't do it again. | |
244 | * | |
245 | * @throws BookException when a problem is encountered loading the file | |
246 | */ | |
247 | void reload() throws BookException; | |
248 | ||
249 | /** | |
250 | * Get a list of all the properties available to do with this Book. The | |
251 | * returned Properties will be read-only so any attempts to alter it will | |
252 | * fail. | |
253 | * | |
254 | * @return the read-only properties for this book | |
255 | */ | |
256 | Set<String> getPropertyKeys(); | |
257 | ||
258 | /** | |
259 | * Get the property or null. | |
260 | * | |
261 | * @param key | |
262 | * the key of the property. | |
263 | * @return the value of the property | |
264 | */ | |
265 | String getProperty(String key); | |
266 | ||
267 | /** | |
268 | * Store a transient property. | |
269 | * | |
270 | * @param key | |
271 | * the key of the property to set | |
272 | * @param value | |
273 | * the value of the property | |
274 | */ | |
275 | void setProperty(String key, String value); | |
276 | ||
277 | /** | |
278 | * Save to shared storage. | |
279 | * | |
280 | * @param key | |
281 | * the key of the property to set | |
282 | * @param value | |
283 | * the value of the property | |
284 | */ | |
285 | void putProperty(String key, String value); | |
286 | ||
287 | /** | |
288 | * Saves an entry to a particular configuration file. | |
289 | * | |
290 | * @param key the entry that we are saving | |
291 | * @param value the value of the entry | |
292 | * @param forFrontend when {@code true} save to front end storage, else in shared storage | |
293 | */ | |
294 | void putProperty(String key, String value, boolean forFrontend); | |
295 | ||
296 | /** | |
297 | * Has anyone generated a search index for this Book? | |
298 | * | |
299 | * @return the status for the index of this book. | |
300 | * @see org.crosswire.jsword.index.IndexManager | |
301 | */ | |
302 | IndexStatus getIndexStatus(); | |
303 | ||
304 | /** | |
305 | * This method does not alter the index status, however it is for Indexers | |
306 | * that are responsible for indexing and have changed the status themselves. | |
307 | * | |
308 | * @param status the status for the index of this book | |
309 | * @see org.crosswire.jsword.index.IndexManager | |
310 | */ | |
311 | void setIndexStatus(IndexStatus status); | |
312 | ||
313 | /** | |
314 | * Get an OSIS representation of information concerning this Book. | |
315 | * | |
316 | * @return the OSIS representation of information about this book. | |
317 | */ | |
318 | Document toOSIS(); | |
319 | ||
320 | /** | |
321 | * The key for the type in the properties map | |
322 | */ | |
323 | String KEY_CATEGORY = "Category"; | |
324 | ||
325 | /** | |
326 | * The key for the book in the properties map | |
327 | */ | |
328 | String KEY_BOOK = "Book"; | |
329 | ||
330 | /** | |
331 | * The key for the driver in the properties map | |
332 | */ | |
333 | String KEY_DRIVER = "Driver"; | |
334 | ||
335 | /** | |
336 | * The key for the name in the properties map | |
337 | */ | |
338 | String KEY_NAME = "Description"; | |
339 | ||
340 | /** | |
341 | * The key for the language in the properties map | |
342 | */ | |
343 | String KEY_LANG = "Lang"; | |
344 | ||
345 | /** | |
346 | * The key for the language in the properties map | |
347 | */ | |
348 | String KEY_LANGUAGE = "Language"; | |
349 | ||
350 | /** | |
351 | * The key for the font in the properties map | |
352 | */ | |
353 | String KEY_FONT = "Font"; | |
354 | ||
355 | /** | |
356 | * The key for the Versification property. | |
357 | */ | |
358 | String KEY_VERSIFICATION = "Versification"; | |
359 | ||
360 | String KEY_BOOKLIST = "BookList"; | |
361 | ||
362 | String KEY_SCOPE = "Scope"; | |
363 | } |