org.crosswire.jsword.book

## Interface Book

- All Superinterfaces:
    Activatable, Comparable<Book>
  All Known Implementing Classes:
    AbstractBook, AbstractPassageBook, ReadingsBook, SwordBook, SwordDailyDevotion, SwordDictionary, SwordGenBook

      public interface Book
      extends Activatable, Comparable<Book>

  Book is the most basic store of textual data - It can retrieve data either as an XML document or as plain text - It uses Keys to refer to parts of itself, and can search for words (returning Keys).
  Author:
    Joe Walker
  See Also:
    `The GNU Lesser General Public License for details.`

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addIndexStatusListener(IndexStatusListener li)` Adds a `IndexStatusListener` to the listener list.
    `boolean` | `contains(Key key)` Returns `true` if this book contains the specified element.
    `Key` | `createEmptyKeyList()` Fetch an empty Key to which we can add Keys.
    `Key` | `find(SearchRequest request)` Retrieval: For a given search spec find a list of references to it.
    `Key` | `find(String request)` Retrieval: For a given search spec find a list of references to it.
    `String` | `getAbbreviation()` The abbreviation 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.
    `BookMetaData` | `getBookMetaData()` Meta-Information: What version of the Bible is this?
    `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.
    `Key` | `getGlobalKeyList()` Get a complete list of index entries.
    `IndexStatus` | `getIndexStatus()` Has anyone generated a search index for this Book?
    `String` | `getInitials()` The internal name of this book.
    `Key` | `getKey(String name)` Someone has typed in a reference to find, but we need a Key to actually look it up.
    `Language` | `getLanguage()` The language of the book.
    `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.
    `Iterator<org.jdom2.Content>` | `getOsisIterator(Key key, boolean allowEmpty, boolean allowGenTitles)` Return an iterator that returns each key's OSIS in turn.
    `String` | `getProperty(String key)` Retrieve a single property for this book.
    `Set<String>` | `getPropertyKeys()` Get a list of all the properties available to do with this Book.
    `String` | `getRawText(Key key)` Returns the raw text that getData(Key key) builds into OSIS.
    `Key` | `getScope()` Get a complete list of entries.
    `String` | `getUnlockKey()` Gets the unlock key for the module.
    `Key` | `getValidKey(String name)` Get a Key for the name, if possible.
    `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.
    `boolean` | `isWritable()` A Book is writable if the file system allows the underlying files to be opened for writing and if the driver for the book allows writing.
    `boolean` | `match(String name)` Return the likelihood that we have a match.
    `void` | `putProperty(String key, String value)` Set a property for this book.
    `void` | `putProperty(String key, String value, boolean forFrontend)` Saves an entry to a particular configuration file.
    `void` | `removeIndexStatusListener(IndexStatusListener li)` Removes a `IndexStatusListener` from the listener list.
    `void` | `setAliasKey(Key alias, Key source)` Store an alias of one key to another.
    `void` | `setBookMetaData(BookMetaData bmd)` Set the meta-information for this book.
    `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` | `setRawText(Key key, String rawData)` Store the raw text for the given key.
    `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 org.crosswire.common.activate.Activatable

      `activate, deactivate`

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

      `compareTo`

- - ### Method Detail

    - #### getGlobalKeyList

          Key getGlobalKeyList()

      Get a complete list of index entries. Create a Key that encompasses all of the known valid keys for the given context. For a dictionary this will include all of the entries in the dictionary, for a Bible this will probably include all the verses in the Bible, but a commentary may well miss some out.
      Returns:
        A Key that includes all of the known Keys

    - #### getScope

          Key getScope()

      Get a complete list of entries. Create a Key that encompasses all of the existing entries in the book. For most modules this will be the same as `getGlobalKeyList()`, however for a Bible, it will get the references that are actually in the book.
      Returns:
        A Key that includes all of the existing Keys

    - #### getValidKey

          Key getValidKey(String name)

      Get a Key for the name, if possible. Otherwise return an empty Key.
      Parameters:
        `name` - The string to translate into a Key
      Returns:
        a valid key.

    - #### getKey

          Key getKey(String name)
                     throws NoSuchKeyException

      Someone has typed in a reference to find, but we need a Key to actually look it up. So we create a Key from the string if such a translation is possible. The returned Key may be a BranchKey if the string represents more than one Key.
      Parameters:
        `name` - The string to translate into a Key
      Returns:
        The Key corresponding to the input text
      Throws:
        `NoSuchKeyException` - If the name can not be parsed.

    - #### createEmptyKeyList

          Key createEmptyKeyList()

      Fetch an empty Key to which we can add Keys. Not all implementations of Key are able to hold any type of Key, It isn't reasonable to expect a Key of Bible verses (=Passage) to hold a dictionary Key. So each KeyFactory must be able to create you an empty Key to which you can safely add other Keys it generates.
      Returns:
        An empty Key that can hold other Keys from this factory.

    - #### getBookMetaData

          BookMetaData getBookMetaData()

      Meta-Information: What version of the Bible is this?
      Returns:
        A Version for this Bible

    - #### setBookMetaData

          void setBookMetaData(BookMetaData bmd)

      Set the meta-information for this book.
      Parameters:
        `bmd` - the BookMetaData that describes this book.

    - #### getOsisIterator

          Iterator<org.jdom2.Content> getOsisIterator(Key key,
                                                    boolean allowEmpty,
                                                    boolean allowGenTitles)
                                                      throws BookException

      Return an iterator that returns each key's OSIS in turn.
      Parameters:
        `key` - the Items to locate
        `allowEmpty` - indicates whether empty keys should be present.
        `allowGenTitles` - indicates whether to generate titles
      Returns:
        an iterator over the OSIS Content
      Throws:
        `BookException` - If anything goes wrong with this method

    - #### contains

          boolean contains(Key key)

      Returns `true` if this book contains the specified element.
      Parameters:
        `key` - element whose presence in this book is to be tested.
      Returns:
        `true` if this book contains the specified element.

    - #### getRawText

          String getRawText(Key key)
                            throws BookException

      Returns the raw text that getData(Key key) builds into OSIS.
      Parameters:
        `key` - The item to locate
      Returns:
        The found Book data
      Throws:
        `BookException` - If anything goes wrong with this method

    - #### isWritable

          boolean isWritable()

      A Book is writable if the file system allows the underlying files to be opened for writing and if the driver for the book allows writing. Ultimately, all drivers should allow writing. At this time writing is not supported by drivers, so abstract implementations should return false and let specific implementations return true otherwise.
      Returns:
        true if the book is writable

    - #### setRawText

          void setRawText(Key key,
                        String rawData)
                          throws BookException

      Store the raw text for the given key. This will replace/hide any raw text that already is present. Note: it is the responsibility of the calling program to ensure that the raw text matches the character set encoding and markup of the module.
      Parameters:
        `key` - The item to locate
        `rawData` - The text to store
      Throws:
        `BookException` - If anything goes wrong with this method

    - #### setAliasKey

          void setAliasKey(Key alias,
                         Key source)
                           throws BookException

      Store an alias of one key to another. Some Bibles do not have a verse by verse numbering system but rather meld several verses into one. Thus, any verse in the range refers to the same verse. Also it may apply to biblical commentaries that are indexed by Book, Chapter, Verse and that discuss the Bible at a verse range level. For a dictionary, it may be used for synonyms.

      It should be an exception to set an alias when that alias already has raw text. Also, it should be an exception to set an alias to an alias. However, getRawText(Key) must be able to handle alias chains.

      Parameters:
        `alias` - the key that aliases another
        `source` - the key that holds the text
      Throws:
        `BookException` - If anything goes wrong with this method

    - #### find

          Key find(SearchRequest request)
                   throws BookException

      Retrieval: For a given search spec find a list of references to it. If there are no matches then null should be returned, otherwise a valid Key.
      Parameters:
        `request` - The search spec.
      Returns:
        the key that matches the search or null
      Throws:
        `BookException` - If anything goes wrong with this method

    - #### find

          Key find(String request)
                   throws BookException

      Retrieval: For a given search spec find a list of references to it. If there are no matches then null should be returned, otherwise a valid Key.
      Parameters:
        `request` - The search spec.
      Returns:
        the key that matches the search or null
      Throws:
        `BookException` - If anything goes wrong with this method

    - #### getName

          String getName()

      The name of the book, for example "King James Version" or "Bible in Basic English" or "Greek". In general it should be possible to deduce the initials from the name by removing all the non-capital letters. Although this is only a generalization. This method should not return null or a blank string.
      Returns:
        The name 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 book's driver

    - #### getLanguage

          Language getLanguage()

      The language of the book.
      Returns:
        the common name for the language

    - #### getAbbreviation

          String getAbbreviation()

      The abbreviation 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

    - #### match

          boolean match(String name)

      Return the likelihood that we have a match. This allows for calling the book different things and still be found.
      Parameters:
        `name` - one of many ways to name this book.
      Returns:
        true if we have a match.

    - #### 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 not encrypted, 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 type of the Feature to check
      Returns:
        whether the feature is supported

    - #### 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)

      Retrieve a single property for this book.
      Parameters:
        `key` - the key of the property.
      Returns:
        the value of the property

    - #### putProperty

          void putProperty(String key,
                         String value)

      Set a property for this book.
      Parameters:
        `key` - the key of the property.
        `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 of the index for 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 to set for this book
      See Also:
        `IndexManager`

    - #### toOSIS

          org.jdom2.Document toOSIS()

      Get an OSIS representation of information concerning this Book.
      Returns:
        information for this book represented as OSIS

    - #### addIndexStatusListener

          void addIndexStatusListener(IndexStatusListener li)

      Adds a `IndexStatusListener` to the listener list.

      A `IndexStatusEvent` will get fired in response to `setIndexStatus`.

      Parameters:
        `li` - the `IndexStatusListener` to be added

    - #### removeIndexStatusListener

          void removeIndexStatusListener(IndexStatusListener li)

      Removes a `IndexStatusListener` from the listener list.
      Parameters:
        `li` - the `IndexStatusListener` to be removed