Classes in this File | Line Coverage | Branch Coverage | Complexity | ||||
Book |
|
| 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.util.Iterator; | |
23 | import java.util.Set; | |
24 | ||
25 | import org.crosswire.common.activate.Activatable; | |
26 | import org.crosswire.common.util.Language; | |
27 | import org.crosswire.jsword.index.IndexStatus; | |
28 | import org.crosswire.jsword.index.IndexStatusListener; | |
29 | import org.crosswire.jsword.index.search.SearchRequest; | |
30 | import org.crosswire.jsword.passage.Key; | |
31 | import org.crosswire.jsword.passage.NoSuchKeyException; | |
32 | import org.jdom2.Content; | |
33 | import org.jdom2.Document; | |
34 | ||
35 | /** | |
36 | * Book is the most basic store of textual data - It can retrieve data either as | |
37 | * an XML document or as plain text - It uses Keys to refer to parts of itself, | |
38 | * and can search for words (returning Keys). | |
39 | * | |
40 | * @see gnu.lgpl.License The GNU Lesser General Public License for details. | |
41 | * @author Joe Walker | |
42 | */ | |
43 | public interface Book extends Activatable, Comparable<Book> { | |
44 | /** | |
45 | * Get a complete list of index entries. Create a Key that encompasses all | |
46 | * of the known valid keys for the given context. For a dictionary this will | |
47 | * include all of the entries in the dictionary, for a Bible this will | |
48 | * probably include all the verses in the Bible, but a commentary may well | |
49 | * miss some out. | |
50 | * | |
51 | * @return A Key that includes all of the known Keys | |
52 | */ | |
53 | Key getGlobalKeyList(); | |
54 | ||
55 | /** | |
56 | * Get a complete list of entries. Create a Key that encompasses all | |
57 | * of the existing entries in the book. For most modules this will be the | |
58 | * same as {@link #getGlobalKeyList}, however for a Bible, it will | |
59 | * get the references that are actually in the book. | |
60 | * | |
61 | * @return A Key that includes all of the existing Keys | |
62 | */ | |
63 | Key getScope(); | |
64 | ||
65 | /** | |
66 | * Get a Key for the name, if possible. Otherwise return an empty Key. | |
67 | * | |
68 | * @param name | |
69 | * The string to translate into a Key | |
70 | * @return a valid key. | |
71 | */ | |
72 | Key getValidKey(String name); | |
73 | ||
74 | /** | |
75 | * Someone has typed in a reference to find, but we need a Key to actually | |
76 | * look it up. So we create a Key from the string if such a translation is | |
77 | * possible. The returned Key may be a BranchKey if the string represents | |
78 | * more than one Key. | |
79 | * | |
80 | * @param name | |
81 | * The string to translate into a Key | |
82 | * @return The Key corresponding to the input text | |
83 | * @throws NoSuchKeyException | |
84 | * If the name can not be parsed. | |
85 | */ | |
86 | Key getKey(String name) throws NoSuchKeyException; | |
87 | ||
88 | /** | |
89 | * Fetch an empty Key to which we can add Keys. Not all implementations of | |
90 | * Key are able to hold any type of Key, It isn't reasonable to expect a Key | |
91 | * of Bible verses (=Passage) to hold a dictionary Key. So each KeyFactory | |
92 | * must be able to create you an empty Key to which you can safely add other | |
93 | * Keys it generates. | |
94 | * | |
95 | * @return An empty Key that can hold other Keys from this factory. | |
96 | */ | |
97 | Key createEmptyKeyList(); | |
98 | ||
99 | /** | |
100 | * Meta-Information: What version of the Bible is this? | |
101 | * | |
102 | * @return A Version for this Bible | |
103 | */ | |
104 | BookMetaData getBookMetaData(); | |
105 | ||
106 | /** | |
107 | * Set the meta-information for this book. | |
108 | * | |
109 | * @param bmd the BookMetaData that describes this book. | |
110 | */ | |
111 | void setBookMetaData(BookMetaData bmd); | |
112 | ||
113 | /** | |
114 | * Return an iterator that returns each key's OSIS in turn. | |
115 | * | |
116 | * @param key | |
117 | * the Items to locate | |
118 | * @param allowEmpty | |
119 | * indicates whether empty keys should be present. | |
120 | * @param allowGenTitles | |
121 | * indicates whether to generate titles | |
122 | * @return an iterator over the OSIS Content | |
123 | * @throws BookException | |
124 | * If anything goes wrong with this method | |
125 | */ | |
126 | Iterator<Content> getOsisIterator(Key key, boolean allowEmpty, boolean allowGenTitles) throws BookException; | |
127 | ||
128 | /** | |
129 | * Returns <tt>true</tt> if this book contains the specified element. | |
130 | * | |
131 | * @param key | |
132 | * element whose presence in this book is to be tested. | |
133 | * @return <tt>true</tt> if this book contains the specified element. | |
134 | */ | |
135 | boolean contains(Key key); | |
136 | ||
137 | /** | |
138 | * Returns the raw text that getData(Key key) builds into OSIS. | |
139 | * | |
140 | * @param key | |
141 | * The item to locate | |
142 | * @return The found Book data | |
143 | * @throws BookException | |
144 | * If anything goes wrong with this method | |
145 | */ | |
146 | String getRawText(Key key) throws BookException; | |
147 | ||
148 | /** | |
149 | * A Book is writable if the file system allows the underlying files to be | |
150 | * opened for writing and if the driver for the book allows writing. | |
151 | * Ultimately, all drivers should allow writing. At this time writing is not | |
152 | * supported by drivers, so abstract implementations should return false and | |
153 | * let specific implementations return true otherwise. | |
154 | * | |
155 | * @return true if the book is writable | |
156 | */ | |
157 | boolean isWritable(); | |
158 | ||
159 | /** | |
160 | * Store the raw text for the given key. This will replace/hide any raw text | |
161 | * that already is present. Note: it is the responsibility of the calling | |
162 | * program to ensure that the raw text matches the character set encoding | |
163 | * and markup of the module. | |
164 | * | |
165 | * @param key | |
166 | * The item to locate | |
167 | * @param rawData | |
168 | * The text to store | |
169 | * @throws BookException | |
170 | * If anything goes wrong with this method | |
171 | */ | |
172 | void setRawText(Key key, String rawData) throws BookException; | |
173 | ||
174 | /** | |
175 | * Store an alias of one key to another. Some Bibles do not have a verse by | |
176 | * verse numbering system but rather meld several verses into one. Thus, any | |
177 | * verse in the range refers to the same verse. Also it may apply to | |
178 | * biblical commentaries that are indexed by Book, Chapter, Verse and that | |
179 | * discuss the Bible at a verse range level. For a dictionary, it may be | |
180 | * used for synonyms. | |
181 | * <p> | |
182 | * It should be an exception to set an alias when that alias already has raw | |
183 | * text. Also, it should be an exception to set an alias to an alias. | |
184 | * However, getRawText(Key) must be able to handle alias chains. | |
185 | * </p> | |
186 | * | |
187 | * @param alias | |
188 | * the key that aliases another | |
189 | * @param source | |
190 | * the key that holds the text | |
191 | * @throws BookException | |
192 | * If anything goes wrong with this method | |
193 | */ | |
194 | void setAliasKey(Key alias, Key source) throws BookException; | |
195 | ||
196 | /** | |
197 | * Retrieval: For a given search spec find a list of references to it. If | |
198 | * there are no matches then null should be returned, otherwise a valid Key. | |
199 | * | |
200 | * @param request | |
201 | * The search spec. | |
202 | * @return the key that matches the search or null | |
203 | * @throws BookException | |
204 | * If anything goes wrong with this method | |
205 | */ | |
206 | Key find(SearchRequest request) throws BookException; | |
207 | ||
208 | /** | |
209 | * Retrieval: For a given search spec find a list of references to it. If | |
210 | * there are no matches then null should be returned, otherwise a valid Key. | |
211 | * | |
212 | * @param request | |
213 | * The search spec. | |
214 | * @return the key that matches the search or null | |
215 | * @throws BookException | |
216 | * If anything goes wrong with this method | |
217 | */ | |
218 | Key find(String request) throws BookException; | |
219 | ||
220 | /** | |
221 | * The name of the book, for example "King James Version" or | |
222 | * "Bible in Basic English" or "Greek". In general it should be possible to | |
223 | * deduce the initials from the name by removing all the non-capital | |
224 | * letters. Although this is only a generalization. This method should not | |
225 | * return null or a blank string. | |
226 | * | |
227 | * @return The name of this book | |
228 | */ | |
229 | String getName(); | |
230 | ||
231 | /** | |
232 | * What category of content is this, a Bible or a reference work like a | |
233 | * Dictionary or Commentary. | |
234 | * | |
235 | * @return The category of book | |
236 | */ | |
237 | BookCategory getBookCategory(); | |
238 | ||
239 | /** | |
240 | * Accessor for the driver that runs this Book. Note this method should only | |
241 | * be used to delete() Books. Everything else you should want to do to a | |
242 | * Book should be available in other ways. | |
243 | * | |
244 | * @return the book's driver | |
245 | */ | |
246 | BookDriver getDriver(); | |
247 | ||
248 | /** | |
249 | * The language of the book. | |
250 | * | |
251 | * @return the common name for the language | |
252 | */ | |
253 | Language getLanguage(); | |
254 | ||
255 | /** | |
256 | * The abbreviation of this book - how people familiar with this book will know | |
257 | * it, for example "NIV", "KJV". | |
258 | * | |
259 | * @return The book's initials | |
260 | */ | |
261 | String getAbbreviation(); | |
262 | ||
263 | /** | |
264 | * The internal name of this book. | |
265 | * | |
266 | * @return The book's internal name | |
267 | */ | |
268 | String getInitials(); | |
269 | ||
270 | /** | |
271 | * Calculated field: Get an OSIS identifier for the OsisText.setOsisIDWork() | |
272 | * and the Work.setOsisWork() methods. The response will generally be of the | |
273 | * form [Bible][Dict..].getInitials | |
274 | * | |
275 | * @return The OSIS id of this book | |
276 | */ | |
277 | String getOsisID(); | |
278 | ||
279 | /** | |
280 | * Return the likelihood that we have a match. This allows for calling the | |
281 | * book different things and still be found. | |
282 | * | |
283 | * @param name one of many ways to name this book. | |
284 | * @return true if we have a match. | |
285 | */ | |
286 | boolean match(String name); | |
287 | ||
288 | /** | |
289 | * Indicate whether this book is supported by JSword. Since the expectation | |
290 | * is that all books are supported, abstract implementations should return | |
291 | * true and let specific implementations return false if they cannot support | |
292 | * the book. | |
293 | * | |
294 | * @return true if the book is supported | |
295 | */ | |
296 | boolean isSupported(); | |
297 | ||
298 | /** | |
299 | * Indicate whether this book is enciphered. Since the expectation is that | |
300 | * most books are unenciphered, abstract implementations should return false | |
301 | * and let specific implementations return true otherwise. | |
302 | * | |
303 | * @return true if the book is enciphered | |
304 | */ | |
305 | boolean isEnciphered(); | |
306 | ||
307 | /** | |
308 | * Indicate whether this book is enciphered and without a key. Since the | |
309 | * expectation is that most books are not encrypted, abstract implementations | |
310 | * should return false and let specific implementations return true | |
311 | * otherwise. | |
312 | * | |
313 | * @return true if the book is locked | |
314 | */ | |
315 | boolean isLocked(); | |
316 | ||
317 | /** | |
318 | * Unlocks a book with the given key. | |
319 | * | |
320 | * @param unlockKey | |
321 | * the key to try | |
322 | * @return true if the unlock key worked. | |
323 | */ | |
324 | boolean unlock(String unlockKey); | |
325 | ||
326 | /** | |
327 | * Gets the unlock key for the module. | |
328 | * | |
329 | * @return the unlock key, if any, null otherwise. | |
330 | */ | |
331 | String getUnlockKey(); | |
332 | ||
333 | /** | |
334 | * Indicate whether this book is questionable. A book may be deemed | |
335 | * questionable if it's quality or content has not been confirmed. Since the | |
336 | * expectation is that all books are not questionable, abstract | |
337 | * implementations should return false and let specific implementations | |
338 | * return true if the book is questionable. | |
339 | * | |
340 | * @return true if the book is questionable | |
341 | */ | |
342 | boolean isQuestionable(); | |
343 | ||
344 | /** | |
345 | * Calculated field: The name of the name, which could be helpful to | |
346 | * distinguish similar Books available through 2 BookDrivers. | |
347 | * | |
348 | * @return The driver name | |
349 | */ | |
350 | String getDriverName(); | |
351 | ||
352 | /** | |
353 | * Return the orientation of the script of the Book. If a book contains more | |
354 | * than one script, it refers to the dominate script of the book. This will | |
355 | * be used to present Arabic and Hebrew in their proper orientation. Note: | |
356 | * some languages have multiple scripts which don't have the same | |
357 | * directionality. | |
358 | * | |
359 | * @return true if the orientation for the dominate script is LeftToRight. | |
360 | */ | |
361 | boolean isLeftToRight(); | |
362 | ||
363 | /** | |
364 | * Return whether the feature is supported by the book. | |
365 | * | |
366 | * @param feature the type of the Feature to check | |
367 | * @return whether the feature is supported | |
368 | */ | |
369 | boolean hasFeature(FeatureType feature); | |
370 | ||
371 | /** | |
372 | * Get a list of all the properties available to do with this Book. The | |
373 | * returned Properties will be read-only so any attempts to alter it will | |
374 | * fail. | |
375 | * | |
376 | * @return the read-only properties for this book. | |
377 | */ | |
378 | Set<String> getPropertyKeys(); | |
379 | ||
380 | /** | |
381 | * Retrieve a single property for this book. | |
382 | * | |
383 | * @param key | |
384 | * the key of the property. | |
385 | * @return the value of the property | |
386 | */ | |
387 | String getProperty(String key); | |
388 | ||
389 | /** | |
390 | * Set a property for this book. | |
391 | * | |
392 | * @param key | |
393 | * the key of the property. | |
394 | * @param value | |
395 | * the value of the property | |
396 | */ | |
397 | void putProperty(String key, String value); | |
398 | ||
399 | /** | |
400 | * Saves an entry to a particular configuration file. | |
401 | * | |
402 | * @param key the entry that we are saving | |
403 | * @param value the value of the entry | |
404 | * @param forFrontend when {@code true} save to front end storage, else in shared storage | |
405 | */ | |
406 | void putProperty(String key, String value, boolean forFrontend); | |
407 | ||
408 | /** | |
409 | * Has anyone generated a search index for this Book? | |
410 | * | |
411 | * @return the status of the index for this book. | |
412 | * @see org.crosswire.jsword.index.IndexManager | |
413 | */ | |
414 | IndexStatus getIndexStatus(); | |
415 | ||
416 | /** | |
417 | * This method does not alter the index status, however it is for Indexers | |
418 | * that are responsible for indexing and have changed the status themselves. | |
419 | * | |
420 | * @param status the status to set for this book | |
421 | * @see org.crosswire.jsword.index.IndexManager | |
422 | */ | |
423 | void setIndexStatus(IndexStatus status); | |
424 | ||
425 | /** | |
426 | * Get an OSIS representation of information concerning this Book. | |
427 | * | |
428 | * @return information for this book represented as OSIS | |
429 | */ | |
430 | Document toOSIS(); | |
431 | ||
432 | /** | |
433 | * Adds a <code>IndexStatusListener</code> to the listener list. | |
434 | * <p> | |
435 | * A <code>IndexStatusEvent</code> will get fired in response to | |
436 | * <code>setIndexStatus</code>. | |
437 | * | |
438 | * @param li | |
439 | * the <code>IndexStatusListener</code> to be added | |
440 | */ | |
441 | void addIndexStatusListener(IndexStatusListener li); | |
442 | ||
443 | /** | |
444 | * Removes a <code>IndexStatusListener</code> from the listener list. | |
445 | * | |
446 | * @param li | |
447 | * the <code>IndexStatusListener</code> to be removed | |
448 | */ | |
449 | void removeIndexStatusListener(IndexStatusListener li); | |
450 | } |