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