| BookMetaData.java |
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 }
364