org.crosswire.jsword.book

## Interface BookMetaData

- All Superinterfaces:
    Comparable<BookMetaData>
  All Known Implementing Classes:
    AbstractBookMetaData, DefaultBookMetaData, SwordBookMetaData

      public interface BookMetaData
      extends Comparable<BookMetaData>

  A BookMetaData represents a method of translating the Bible. All Books with the same BookMetaData should return identical text for any call to `Bible.getText(VerseRange)`. The implication of this is that there may be many instances of the Version "NIV", as there are several different versions of the NIV - Original American-English, Anglicised, and Inclusive Language editions at least.

  BookMetaData like Strings must be compared using `.equals()` instead of ==. A Bible must have the ability to handle a book unknown to JSword. So Books must be able to add versions to the system, and the system must cope with books that already exist.

  Author:
    Joe Walker
  See Also:
    `The GNU Lesser General Public License for details.`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `KEY_BOOK` The key for the book in the properties map
    `static String` | `KEY_BOOKLIST`
    `static String` | `KEY_CATEGORY` The key for the type in the properties map
    `static String` | `KEY_DRIVER` The key for the driver in the properties map
    `static String` | `KEY_FONT` The key for the font in the properties map
    `static String` | `KEY_LANG` The key for the language in the properties map
    `static String` | `KEY_LANGUAGE` The key for the language in the properties map
    `static String` | `KEY_NAME` The key for the name in the properties map
    `static String` | `KEY_SCOPE`
    `static String` | `KEY_VERSIFICATION` The key for the Versification property.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `String` | `getAbbreviation()` The initials of this book - how people familiar with this book will know it, for example "NIV", "KJV".
    `BookCategory` | `getBookCategory()` What category of content is this, a Bible or a reference work like a Dictionary or Commentary.
    `String` | `getBookCharset()` With which Charset is this Book encoded?
    `BookDriver` | `getDriver()` Accessor for the driver that runs this Book.
    `String` | `getDriverName()` Calculated field: The name of the name, which could be helpful to distinguish similar Books available through 2 BookDrivers.
    `IndexStatus` | `getIndexStatus()` Has anyone generated a search index for this Book?
    `String` | `getInitials()` The internal name of this book.
    `KeyType` | `getKeyType()` How this Book organizes it's keys.
    `Language` | `getLanguage()` The language of the book.
    `URI` | `getLibrary()` Get the base URI for library of this module.
    `URI` | `getLocation()` Get the base URI for relative URIs in the document.
    `String` | `getName()` The name of the book, for example "King James Version" or "Bible in Basic English" or "Greek".
    `String` | `getOsisID()` Calculated field: Get an OSIS identifier for the OsisText.setOsisIDWork() and the Work.setOsisWork() methods.
    `String` | `getProperty(String key)` Get the property or null.
    `Set<String>` | `getPropertyKeys()` Get a list of all the properties available to do with this Book.
    `String` | `getUnlockKey()` Gets the unlock key for the module.
    `boolean` | `hasFeature(FeatureType feature)` Return whether the feature is supported by the book.
    `boolean` | `isEnciphered()` Indicate whether this book is enciphered.
    `boolean` | `isLeftToRight()` Return the orientation of the script of the Book.
    `boolean` | `isLocked()` Indicate whether this book is enciphered and without a key.
    `boolean` | `isQuestionable()` Indicate whether this book is questionable.
    `boolean` | `isSupported()` Indicate whether this book is supported by JSword.
    `void` | `putProperty(String key, String value)` Save to shared storage.
    `void` | `putProperty(String key, String value, boolean forFrontend)` Saves an entry to a particular configuration file.
    `void` | `reload()` If this BookMetaData is partially loaded, reload it fully.
    `void` | `setIndexStatus(IndexStatus status)` This method does not alter the index status, however it is for Indexers that are responsible for indexing and have changed the status themselves.
    `void` | `setLanguage(Language language)` Set the language for this book.
    `void` | `setLibrary(URI library)` Set the base URI for library of this module.
    `void` | `setLocation(URI library)` Set the base URI for relative URIs in the document.
    `void` | `setProperty(String key, String value)` Store a transient property.
    `org.jdom2.Document` | `toOSIS()` Get an OSIS representation of information concerning this Book.
    `boolean` | `unlock(String unlockKey)` Unlocks a book with the given key.

    - ### Methods inherited from interface java.lang.Comparable

      `compareTo`

- - ### Field Detail

    - #### KEY_CATEGORY

          static final String KEY_CATEGORY

      The key for the type in the properties map
      See Also:
        Constant Field Values

    - #### KEY_BOOK

          static final String KEY_BOOK

      The key for the book in the properties map
      See Also:
        Constant Field Values

    - #### KEY_DRIVER

          static final String KEY_DRIVER

      The key for the driver in the properties map
      See Also:
        Constant Field Values

    - #### KEY_NAME

          static final String KEY_NAME

      The key for the name in the properties map
      See Also:
        Constant Field Values

    - #### KEY_LANG

          static final String KEY_LANG

      The key for the language in the properties map
      See Also:
        Constant Field Values

    - #### KEY_LANGUAGE

          static final String KEY_LANGUAGE

      The key for the language in the properties map
      See Also:
        Constant Field Values

    - #### KEY_FONT

          static final String KEY_FONT

      The key for the font in the properties map
      See Also:
        Constant Field Values

    - #### KEY_VERSIFICATION

          static final String KEY_VERSIFICATION

      The key for the Versification property.
      See Also:
        Constant Field Values

    - #### KEY_BOOKLIST

          static final String KEY_BOOKLIST

      See Also:
        Constant Field Values

    - #### KEY_SCOPE

          static final String KEY_SCOPE

      See Also:
        Constant Field Values

  - ### Method Detail

    - #### getName

          String getName()

      The name of the book, for example "King James Version" or "Bible in Basic English" or "Greek". This method should not return null or a blank string.
      Returns:
        The name of this book

    - #### getBookCharset

          String getBookCharset()

      With which Charset is this Book encoded?
      Returns:
        the encoding of the Book

    - #### getKeyType

          KeyType getKeyType()

      How this Book organizes it's keys.
      Returns:
        the organization of keys of this Book

    - #### getBookCategory

          BookCategory getBookCategory()

      What category of content is this, a Bible or a reference work like a Dictionary or Commentary.
      Returns:
        The category of book

    - #### getDriver

          BookDriver getDriver()

      Accessor for the driver that runs this Book. Note this method should only be used to delete() Books. Everything else you should want to do to a Book should be available in other ways.
      Returns:
        the driver for the book.

    - #### getLanguage

          Language getLanguage()

      The language of the book.
      Returns:
        the book's language

    - #### setLanguage

          void setLanguage(Language language)

      Set the language for this book.
      Parameters:
        `language` - the book's language

    - #### getAbbreviation

          String getAbbreviation()

      The initials of this book - how people familiar with this book will know it, for example "NIV", "KJV".
      Returns:
        The book's initials

    - #### getInitials

          String getInitials()

      The internal name of this book.
      Returns:
        The book's internal name

    - #### getOsisID

          String getOsisID()

      Calculated field: Get an OSIS identifier for the OsisText.setOsisIDWork() and the Work.setOsisWork() methods. The response will generally be of the form [Bible][Dict..].getInitials
      Returns:
        The osis id of this book

    - #### isSupported

          boolean isSupported()

      Indicate whether this book is supported by JSword. Since the expectation is that all books are supported, abstract implementations should return true and let specific implementations return false if they cannot support the book.
      Returns:
        true if the book is supported

    - #### isEnciphered

          boolean isEnciphered()

      Indicate whether this book is enciphered. Since the expectation is that most books are unenciphered, abstract implementations should return false and let specific implementations return true otherwise.
      Returns:
        true if the book is enciphered

    - #### isLocked

          boolean isLocked()

      Indicate whether this book is enciphered and without a key. Since the expectation is that most books are unenciphered, abstract implementations should return false and let specific implementations return true otherwise.
      Returns:
        true if the book is locked

    - #### unlock

          boolean unlock(String unlockKey)

      Unlocks a book with the given key.
      Parameters:
        `unlockKey` - the key to try
      Returns:
        true if the unlock key worked.

    - #### getUnlockKey

          String getUnlockKey()

      Gets the unlock key for the module.
      Returns:
        the unlock key, if any, null otherwise.

    - #### isQuestionable

          boolean isQuestionable()

      Indicate whether this book is questionable. A book may be deemed questionable if it's quality or content has not been confirmed. Since the expectation is that all books are not questionable, abstract implementations should return false and let specific implementations return true if the book is questionable.
      Returns:
        true if the book is questionable

    - #### getDriverName

          String getDriverName()

      Calculated field: The name of the name, which could be helpful to distinguish similar Books available through 2 BookDrivers.
      Returns:
        The driver name

    - #### isLeftToRight

          boolean isLeftToRight()

      Return the orientation of the script of the Book. If a book contains more than one script, it refers to the dominate script of the book. This will be used to present Arabic and Hebrew in their proper orientation. Note: some languages have multiple scripts which don't have the same directionality.
      Returns:
        true if the orientation for the dominate script is LeftToRight.

    - #### hasFeature

          boolean hasFeature(FeatureType feature)

      Return whether the feature is supported by the book.
      Parameters:
        `feature` - the feature in question
      Returns:
        true if the book supports the feature

    - #### getLibrary

          URI getLibrary()

      Get the base URI for library of this module.
      Returns:
        the base URI or null if there is none

    - #### setLibrary

          void setLibrary(URI library)
                          throws BookException

      Set the base URI for library of this module.
      Parameters:
        `library` - the base URI or null if there is none
      Throws:
        `BookException` - indicates missing data files

    - #### getLocation

          URI getLocation()

      Get the base URI for relative URIs in the document.
      Returns:
        the base URI or null if there is none

    - #### setLocation

          void setLocation(URI library)

      Set the base URI for relative URIs in the document.
      Parameters:
        `library` - the base URI or null if there is none

    - #### reload

          void reload()
                      throws BookException

      If this BookMetaData is partially loaded, reload it fully. If it is fully loaded, don't do it again.
      Throws:
        `BookException` - when a problem is encountered loading the file

    - #### getPropertyKeys

          Set<String> getPropertyKeys()

      Get a list of all the properties available to do with this Book. The returned Properties will be read-only so any attempts to alter it will fail.
      Returns:
        the read-only properties for this book

    - #### getProperty

          String getProperty(String key)

      Get the property or null.
      Parameters:
        `key` - the key of the property.
      Returns:
        the value of the property

    - #### setProperty

          void setProperty(String key,
                         String value)

      Store a transient property.
      Parameters:
        `key` - the key of the property to set
        `value` - the value of the property

    - #### putProperty

          void putProperty(String key,
                         String value)

      Save to shared storage.
      Parameters:
        `key` - the key of the property to set
        `value` - the value of the property

    - #### putProperty

          void putProperty(String key,
                         String value,
                         boolean forFrontend)

      Saves an entry to a particular configuration file.
      Parameters:
        `key` - the entry that we are saving
        `value` - the value of the entry
        `forFrontend` - when `true` save to front end storage, else in shared storage

    - #### getIndexStatus

          IndexStatus getIndexStatus()

      Has anyone generated a search index for this Book?
      Returns:
        the status for the index of this book.
      See Also:
        `IndexManager`

    - #### setIndexStatus

          void setIndexStatus(IndexStatus status)

      This method does not alter the index status, however it is for Indexers that are responsible for indexing and have changed the status themselves.
      Parameters:
        `status` - the status for the index of this book
      See Also:
        `IndexManager`

    - #### toOSIS

          org.jdom2.Document toOSIS()

      Get an OSIS representation of information concerning this Book.
      Returns:
        the OSIS representation of information about this book.