| 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 * 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