Coverage Report - org.crosswire.jsword.book.BookMetaData
 
Classes in this File Line Coverage Branch Coverage Complexity
BookMetaData
N/A
N/A
1
 
 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  
 }