Coverage Report

Coverage Report - org.crosswire.jsword.book.BookMetaData

Classes in this File

 /**
  * Distribution License:
  * JSword is free software; you can redistribute it and/or modify it under
  * the terms of the GNU Lesser General Public License, version 2.1 or later
  * as published by the Free Software Foundation. This program is distributed
  * in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even
  * the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
  * See the GNU Lesser General Public License for more details.
  *
  * The License is available on the internet at:
  *      http://www.gnu.org/copyleft/lgpl.html
  * or by writing to:
  *      Free Software Foundation, Inc.
  *      59 Temple Place - Suite 330
  *      Boston, MA 02111-1307, USA
  *
  * © CrossWire Bible Society, 2005 - 2016
  *
  */
 package org.crosswire.jsword.book;
 
 import java.net.URI;
 import java.util.Set;
 
 import org.crosswire.common.util.Language;
 import org.crosswire.jsword.index.IndexStatus;
 import org.jdom2.Document;
 
 /**
  * A BookMetaData represents a method of translating the Bible. All Books with
  * the same BookMetaData should return identical text for any call to
  * <code>Bible.getText(VerseRange)</code>. The implication of this is that there
  * may be many instances of the Version "NIV", as there are several different
  * versions of the NIV - Original American-English, Anglicised, and Inclusive
  * Language editions at least.
  * 
  * <p>
  * BookMetaData like Strings must be compared using <code>.equals()</code>
  * instead of ==. A Bible must have the ability to handle a book unknown to
  * JSword. So Books must be able to add versions to the system, and the system
  * must cope with books that already exist.
  * </p>
  * 
  * @see gnu.lgpl.License The GNU Lesser General Public License for details.
  * @author Joe Walker
  */
 public interface BookMetaData extends Comparable<BookMetaData> {
     /**
      * The name of the book, for example "King James Version" or
      * "Bible in Basic English" or "Greek". This method should not
      * return null or a blank string.
      * 
      * @return The name of this book
      */
     String getName();
 
     /**
      * With which Charset is this Book encoded?
      * 
      * @return the encoding of the Book
      */
     String getBookCharset();
 
     /**
      * How this Book organizes it's keys.
      * 
      * @return the organization of keys of this Book
      */
     KeyType getKeyType();
 
     /**
      * What category of content is this, a Bible or a reference work like a
      * Dictionary or Commentary.
      * 
      * @return The category of book
      */
     BookCategory getBookCategory();
 
     /**
      * Accessor for the driver that runs this Book. Note this method should only
      * be used to delete() Books. Everything else you should want to do to a
      * Book should be available in other ways.
      * 
      * @return the driver for the book.
      */
     BookDriver getDriver();
 
     /**
      * The language of the book.
      * 
      * @return the book's language
      */
     Language getLanguage();
 
     /**
      * Set the language for this book.
      * 
      * @param language
      *            the book's language
      */
     void setLanguage(Language language);
 
     /**
      * The initials of this book - how people familiar with this book will know
      * it, for example "NIV", "KJV".
      * 
      * @return The book's initials
      */
     String getAbbreviation();
 
     /**
      * The internal name of this book.
      * 
      * @return The book's internal name
      */
     String getInitials();
 
     /**
      * Calculated field: Get an OSIS identifier for the OsisText.setOsisIDWork()
      * and the Work.setOsisWork() methods. The response will generally be of the
      * form [Bible][Dict..].getInitials
      * 
      * @return The osis id of this book
      */
     String getOsisID();
 
     /**
      * Indicate whether this book is supported by JSword. Since the expectation
      * is that all books are supported, abstract implementations should return
      * true and let specific implementations return false if they cannot support
      * the book.
      * 
      * @return true if the book is supported
      */
     boolean isSupported();
 
     /**
      * Indicate whether this book is enciphered. Since the expectation is that
      * most books are unenciphered, abstract implementations should return false
      * and let specific implementations return true otherwise.
      * 
      * @return true if the book is enciphered
      */
     boolean isEnciphered();
 
     /**
      * Indicate whether this book is enciphered and without a key. Since the
      * expectation is that most books are unenciphered, abstract implementations
      * should return false and let specific implementations return true
      * otherwise.
      * 
      * @return true if the book is locked
      */
     boolean isLocked();
 
     /**
      * Unlocks a book with the given key.
      * 
      * @param unlockKey
      *            the key to try
      * @return true if the unlock key worked.
      */
     boolean unlock(String unlockKey);
 
     /**
      * Gets the unlock key for the module.
      * 
      * @return the unlock key, if any, null otherwise.
      */
     String getUnlockKey();
 
     /**
      * Indicate whether this book is questionable. A book may be deemed
      * questionable if it's quality or content has not been confirmed. Since the
      * expectation is that all books are not questionable, abstract
      * implementations should return false and let specific implementations
      * return true if the book is questionable.
      * 
      * @return true if the book is questionable
      */
     boolean isQuestionable();
 
     /**
      * Calculated field: The name of the name, which could be helpful to
      * distinguish similar Books available through 2 BookDrivers.
      * 
      * @return The driver name
      */
     String getDriverName();
 
     /**
      * Return the orientation of the script of the Book. If a book contains more
      * than one script, it refers to the dominate script of the book. This will
      * be used to present Arabic and Hebrew in their proper orientation. Note:
      * some languages have multiple scripts which don't have the same
      * directionality.
      * 
      * @return true if the orientation for the dominate script is LeftToRight.
      */
     boolean isLeftToRight();
 
     /**
      * Return whether the feature is supported by the book.
      * 
      * @param feature the feature in question
      * @return true if the book supports the feature
      */
     boolean hasFeature(FeatureType feature);
 
     /**
      * Get the base URI for library of this module.
      * 
      * @return the base URI or null if there is none
      */
     URI getLibrary();
 
     /**
      * Set the base URI for library of this module.
      * 
      * @param library
      *            the base URI or null if there is none
      * @throws BookException  indicates missing data files
      */
     void setLibrary(URI library) throws BookException;
 
     /**
      * Get the base URI for relative URIs in the document.
      * 
      * @return the base URI or null if there is none
      */
     URI getLocation();
 
     /**
      * Set the base URI for relative URIs in the document.
      * 
      * @param library
      *            the base URI or null if there is none
      */
     void setLocation(URI library);
 
     /**
      * If this BookMetaData is partially loaded, reload it fully.
      * If it is fully loaded, don't do it again.
      * 
      * @throws BookException when a problem is encountered loading the file
      */
     void reload() throws BookException;
 
     /**
      * Get a list of all the properties available to do with this Book. The
      * returned Properties will be read-only so any attempts to alter it will
      * fail.
      * 
      * @return the read-only properties for this book
      */
     Set<String> getPropertyKeys();
 
     /**
      * Get the property or null.
      * 
      * @param key
      *            the key of the property.
      * @return the value of the property
      */
     String getProperty(String key);
 
     /**
      * Store a transient property.
      * 
      * @param key
      *            the key of the property to set
      * @param value
      *            the value of the property
      */
     void setProperty(String key, String value);
 
     /**
      * Save to shared storage.
      * 
      * @param key
      *            the key of the property to set
      * @param value
      *            the value of the property
      */
     void putProperty(String key, String value);
 
     /**
      * Saves an entry to a particular configuration file.
      * 
      * @param key the entry that we are saving
      * @param value the value of the entry
      * @param forFrontend when {@code true} save to front end storage, else in shared storage
      */
     void putProperty(String key, String value, boolean forFrontend);
 
     /**
      * Has anyone generated a search index for this Book?
      * 
      * @return the status for the index of this book.
      * @see org.crosswire.jsword.index.IndexManager
      */
     IndexStatus getIndexStatus();
 
     /**
      * This method does not alter the index status, however it is for Indexers
      * that are responsible for indexing and have changed the status themselves.
      * 
      * @param status the status for the index of this book
      * @see org.crosswire.jsword.index.IndexManager
      */
     void setIndexStatus(IndexStatus status);
 
     /**
      * Get an OSIS representation of information concerning this Book.
      * 
      * @return the OSIS representation of information about this book.
      */
     Document toOSIS();
 
     /**
      * The key for the type in the properties map
      */
     String KEY_CATEGORY = "Category";
 
     /**
      * The key for the book in the properties map
      */
     String KEY_BOOK = "Book";
 
     /**
      * The key for the driver in the properties map
      */
     String KEY_DRIVER = "Driver";
 
     /**
      * The key for the name in the properties map
      */
     String KEY_NAME = "Description";
 
     /**
      * The key for the language in the properties map
      */
     String KEY_LANG = "Lang";
 
     /**
      * The key for the language in the properties map
      */
     String KEY_LANGUAGE = "Language";
 
     /**
      * The key for the font in the properties map
      */
     String KEY_FONT = "Font";
 
     /**
      * The key for the Versification property.
      */
     String KEY_VERSIFICATION = "Versification";
 
     String KEY_BOOKLIST = "BookList";
 
     String KEY_SCOPE = "Scope";
 }

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		}