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   * Copyright: 2005-2013
18   *     The copyright to this program is held by it's authors.
19   *
20   */
21  package org.crosswire.jsword.book;
22  
23  import java.net.URI;
24  import java.util.Map;
25  
26  import org.crosswire.common.util.Language;
27  import org.crosswire.jsword.book.sword.MissingDataFilesException;
28  import org.crosswire.jsword.index.IndexStatus;
29  import org.jdom2.Document;
30  
31  /**
32   * A BookMetaData represents a method of translating the Bible. All Books with
33   * the same BookMetaData should return identical text for any call to
34   * <code>Bible.getText(VerseRange)</code>. The implication of this is that there
35   * may be many instances of the Version "NIV", as there are several different
36   * versions of the NIV - Original American-English, Anglicized, and Inclusive
37   * Language editions at least.
38   * 
39   * <p>
40   * BookMetaData like Strings must be compared using <code>.equals()<code>
41   * instead of ==. A Bible must have the ability to handle a book unknown to
42   * JSword. So Books must be able to add versions to the system, and the system
43   * must cope with books that already exist.
44   * </p>
45   * 
46   * @see gnu.lgpl.License for license details.<br>
47   *      The copyright to this program is held by it's authors.
48   * @author Joe Walker [joe at eireneh dot com]
49   */
50  public interface BookMetaData extends Comparable<BookMetaData> {
51      /**
52       * The name of the book, for example "King James Version" or
53       * "Bible in Basic English" or "Greek". In general it should be possible to
54       * deduce the initials from the name by removing all the non-capital
55       * letters. Although this is only a generalization. This method should not
56       * return null or a blank string.
57       * 
58       * @return The name of this book
59       */
60      String getName();
61  
62      /**
63       * How this Book organizes it's keys.
64       * 
65       * @return the organization of keys of this Book
66       */
67      KeyType getKeyType();
68  
69      /**
70       * What category of content is this, a Bible or a reference work like a
71       * Dictionary or Commentary.
72       * 
73       * @return The category of book
74       */
75      BookCategory getBookCategory();
76  
77      /**
78       * Accessor for the driver that runs this Book. Note this method should only
79       * be used to delete() Books. Everything else you should want to do to a
80       * Book should be available in other ways.
81       */
82      BookDriver getDriver();
83  
84      /**
85       * The language of the book.
86       * 
87       * @return the book's language
88       */
89      Language getLanguage();
90  
91      /**
92       * The initials of this book - how people familiar with this book will know
93       * it, for example "NIV", "KJV".
94       * 
95       * @return The book's initials
96       */
97      String getInitials();
98  
99      /**
100      * Calculated field: Get an OSIS identifier for the OsisText.setOsisIDWork()
101      * and the Work.setOsisWork() methods. The response will generally be of the
102      * form [Bible][Dict..].getInitials
103      * 
104      * @return The osis id of this book
105      */
106     String getOsisID();
107 
108     /**
109      * Indicate whether this book is supported by JSword. Since the expectation
110      * is that all books are supported, abstract implementations should return
111      * true and let specific implementations return false if they cannot support
112      * the book.
113      * 
114      * @return true if the book is supported
115      */
116     boolean isSupported();
117 
118     /**
119      * Indicate whether this book is enciphered. Since the expectation is that
120      * most books are unenciphered, abstract implementations should return false
121      * and let specific implementations return true otherwise.
122      * 
123      * @return true if the book is enciphered
124      */
125     boolean isEnciphered();
126 
127     /**
128      * Indicate whether this book is enciphered and without a key. Since the
129      * expectation is that most books are unenciphered, abstract implementations
130      * should return false and let specific implementations return true
131      * otherwise.
132      * 
133      * @return true if the book is locked
134      */
135     boolean isLocked();
136 
137     /**
138      * Unlocks a book with the given key.
139      * 
140      * @param unlockKey
141      *            the key to try
142      * @return true if the unlock key worked.
143      */
144     boolean unlock(String unlockKey);
145 
146     /**
147      * Gets the unlock key for the module.
148      * 
149      * @return the unlock key, if any, null otherwise.
150      */
151     String getUnlockKey();
152 
153     /**
154      * Indicate whether this book is questionable. A book may be deemed
155      * questionable if it's quality or content has not been confirmed. Since the
156      * expectation is that all books are not questionable, abstract
157      * implementations should return false and let specific implementations
158      * return true if the book is questionable.
159      * 
160      * @return true if the book is questionable
161      */
162     boolean isQuestionable();
163 
164     /**
165      * Calculated field: The name of the name, which could be helpful to
166      * distinguish similar Books available through 2 BookDrivers.
167      * 
168      * @return The driver name
169      */
170     String getDriverName();
171 
172     /**
173      * Return the orientation of the script of the Book. If a book contains more
174      * than one script, it refers to the dominate script of the book. This will
175      * be used to present Arabic and Hebrew in their proper orientation. Note:
176      * some languages have multiple scripts which don't have the same
177      * directionality.
178      * 
179      * @return true if the orientation for the dominate script is LeftToRight.
180      */
181     boolean isLeftToRight();
182 
183     /**
184      * Return whether the feature is supported by the book.
185      */
186     boolean hasFeature(FeatureType feature);
187 
188     /**
189      * Get the base URI for library of this module.
190      * 
191      * @return the base URI or null if there is none
192      */
193     URI getLibrary();
194 
195     /**
196      * Set the base URI for library of this module.
197      * 
198      * @param library
199      *            the base URI or null if there is none
200      * @throws MissingDataFilesException  indicates missing data files
201      */
202     void setLibrary(URI library) throws MissingDataFilesException;
203 
204     /**
205      * Get the base URI for relative URIs in the document.
206      * 
207      * @return the base URI or null if there is none
208      */
209     URI getLocation();
210 
211     /**
212      * Set the base URI for relative URIs in the document.
213      * 
214      * @param library
215      *            the base URI or null if there is none
216      */
217     void setLocation(URI library);
218 
219     /**
220      * Get a list of all the properties available to do with this Book. The
221      * returned Properties will be read-only so any attempts to alter it will
222      * fail.
223      */
224     Map<String, Object> getProperties();
225 
226     /**
227      * @param key
228      *            the key of the property.
229      * @return the value of the property
230      */
231     Object getProperty(String key);
232 
233     /**
234      * @param key
235      *            the key of the property to set
236      * @param value
237      *            the value of the property
238      */
239     void putProperty(String key, Object value);
240 
241     /**
242      * Has anyone generated a search index for this Book?
243      * 
244      * @see org.crosswire.jsword.index.IndexManager
245      */
246     IndexStatus getIndexStatus();
247 
248     /**
249      * This method does not alter the index status, however it is for Indexers
250      * that are responsible for indexing and have changed the status themselves.
251      * 
252      * @see org.crosswire.jsword.index.IndexManager
253      */
254     void setIndexStatus(IndexStatus status);
255 
256     /**
257      * Get an OSIS representation of information concerning this Book.
258      */
259     Document toOSIS();
260 
261     /**
262      * The key for the type in the properties map
263      */
264     String KEY_CATEGORY = "Category";
265 
266     /**
267      * The key for the book in the properties map
268      */
269     String KEY_BOOK = "Book";
270 
271     /**
272      * The key for the driver in the properties map
273      */
274     String KEY_DRIVER = "Driver";
275 
276     /**
277      * The key for the name in the properties map
278      */
279     String KEY_NAME = "Description";
280 
281     /**
282      * The key for the language in the properties map
283      */
284     String KEY_XML_LANG = "Lang";
285 
286     /**
287      * The key for the font in the properties map
288      */
289     String KEY_FONT = "Font";
290 
291     /**
292      * The key for the initials in the properties map
293      */
294     String KEY_INITIALS = "Initials";
295 
296     /**
297      * The key for the URI locating where this book is installed
298      */
299     String KEY_LIBRARY_URI = "LibraryURI";
300 
301     /**
302      * The key for the URI locating this book
303      */
304     String KEY_LOCATION_URI = "LocationURI";
305 
306     /**
307      * The key for the indexed status in the properties map
308      */
309     String KEY_INDEXSTATUS = "IndexStatus";
310 
311     /**
312      * The key for the Versification property.
313      */
314     String KEY_VERSIFICATION = "Versification";
315 }
316