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