| 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 as published by
5 * the Free Software Foundation. This program is distributed in the hope
6 * that it will be useful, but WITHOUT ANY WARRANTY; without even the
7 * 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
18 * The copyright to this program is held by it's authors.
19 *
20 * ID: $Id: BookMetaData.java 2221 2012-01-25 21:32:57Z dmsmith $
21 */
22 package org.crosswire.jsword.book;
23
24 import java.net.URI;
25 import java.util.Map;
26
27 import org.crosswire.common.util.Language;
28 import org.crosswire.jsword.index.IndexStatus;
29 import org.jdom.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 */
201 void setLibrary(URI library);
202
203 /**
204 * Get the base URI for relative URIs in the document.
205 *
206 * @return the base URI or null if there is none
207 */
208 URI getLocation();
209
210 /**
211 * Set the base URI for relative URIs in the document.
212 *
213 * @param library
214 * the base URI or null if there is none
215 */
216 void setLocation(URI library);
217
218 /**
219 * Get a list of all the properties available to do with this Book. The
220 * returned Properties will be read-only so any attempts to alter it will
221 * fail.
222 */
223 Map<String, Object> getProperties();
224
225 /**
226 * @param key
227 * the key of the property.
228 * @return the value of the property
229 */
230 Object getProperty(String key);
231
232 /**
233 * @param key
234 * the key of the property to set
235 * @param value
236 * the value of the property
237 */
238 void putProperty(String key, Object value);
239
240 /**
241 * Has anyone generated a search index for this Book?
242 *
243 * @see org.crosswire.jsword.index.IndexManager
244 */
245 IndexStatus getIndexStatus();
246
247 /**
248 * This method does not alter the index status, however it is for Indexers
249 * that are responsible for indexing and have changed the status themselves.
250 *
251 * @see org.crosswire.jsword.index.IndexManager
252 */
253 void setIndexStatus(IndexStatus status);
254
255 /**
256 * Get an OSIS representation of information concerning this Book.
257 */
258 Document toOSIS();
259
260 /**
261 * The key for the type in the properties map
262 */
263 String KEY_CATEGORY = "Category";
264
265 /**
266 * The key for the book in the properties map
267 */
268 String KEY_BOOK = "Book";
269
270 /**
271 * The key for the driver in the properties map
272 */
273 String KEY_DRIVER = "Driver";
274
275 /**
276 * The key for the name in the properties map
277 */
278 String KEY_NAME = "Description";
279
280 /**
281 * The key for the language in the properties map
282 */
283 String KEY_XML_LANG = "Lang";
284
285 /**
286 * The key for the font in the properties map
287 */
288 String KEY_FONT = "Font";
289
290 /**
291 * The key for the initials in the properties map
292 */
293 String KEY_INITIALS = "Initials";
294
295 /**
296 * The key for the URI locating where this book is installed
297 */
298 String KEY_LIBRARY_URI = "LibraryURI";
299
300 /**
301 * The key for the URI locating this book
302 */
303 String KEY_LOCATION_URI = "LocationURI";
304
305 /**
306 * The key for the indexed status in the properties map
307 */
308 String KEY_INDEXSTATUS = "IndexStatus";
309
310 /**
311 * The key for the Versification property.
312 */
313 String KEY_VERSIFICATION = "Versification";
314 }
315