org.crosswire.jsword.book.basic

## Class AbstractBook

- java.lang.Object
- - org.crosswire.jsword.book.basic.AbstractBook

- All Implemented Interfaces:
    Comparable<Book>, Activatable, Book
  Direct Known Subclasses:
    AbstractPassageBook, ReadingsBook, SwordDictionary, SwordGenBook

      public abstract class AbstractBook
      extends Object
      implements Book

  AbstractBook implements a few of the more generic methods of Book. This class does a lot of work in helping make search easier, and implementing some basic write methods.
  Author:
    Joe Walker
  See Also:
    `The GNU Lesser General Public License for details.`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `private Backend` | `backend` To read the data from the Book
    `private BookMetaData` | `bmd` The meta data for this book
    `private List<IndexStatusListener>` | `listeners` The list of property change listeners
    `private Searcher` | `searcher` How do we perform searches

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `AbstractBook(BookMetaData bmd, Backend backend)` Construct an AbstractBook given the BookMetaData and the AbstractBackend.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `activate(Lock lock)` Called to indicate that the Book should initialize itself, and consume whatever system resources it needs to be able to respond to other queries.
    `void` | `addIndexStatusListener(IndexStatusListener listener)` Adds a `IndexStatusListener` to the listener list.
    `int` | `compareTo(Book obj)`
    `void` | `deactivate(Lock lock)` Called to indicate that the Book should release whatever system resources it can to make way for other uses.
    `boolean` | `equals(Object obj)`
    `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.
    `protected void` | `firePropertyChange(IndexStatus oldStatus, IndexStatus newStatus)` Reports bound property changes.
    `String` | `getAbbreviation()` The abbreviation of this book - how people familiar with this book will know it, for example "NIV", "KJV".
    `Backend` | `getBackend()`
    `Book` | `getBook()` Get this book.
    `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.
    `IndexStatus` | `getIndexStatus()` Has anyone generated a search index for this Book?
    `String` | `getInitials()` The internal name of this book.
    `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".
    `protected abstract List<org.jdom2.Content>` | `getOsis(Key key, RawTextToXmlProcessor noOpRawTextProcessor)`
    `String` | `getOsisID()` Calculated field: Get an OSIS identifier for the OsisText.setOsisIDWork() and the Work.setOsisWork() methods.
    `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.
    `Key` | `getScope()` Get a complete list of entries.
    `String` | `getUnlockKey()` Gets the unlock key for the module.
    `boolean` | `hasFeature(FeatureType feature)` Return whether the feature is supported by the book.
    `int` | `hashCode()`
    `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.
    `private boolean` | `isUnlockKeyValid()` This is a heuristic that tries out the key.
    `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 listener)` Removes a `IndexStatusListener` from the listener list.
    `void` | `setBookMetaData(BookMetaData bmd)` Set the meta-information for this book.
    `void` | `setIndexStatus(IndexStatus newStatus)` This method does not alter the index status, however it is for Indexers that are responsible for indexing and have changed the status themselves.
    `org.jdom2.Document` | `toOSIS()` Get an OSIS representation of information concerning this Book.
    `String` | `toString()`
    `boolean` | `unlock(String unlockKey)` Unlocks a book with the given key.

    - ### Methods inherited from class java.lang.Object

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

    - ### Methods inherited from interface org.crosswire.jsword.book.Book

      `contains, createEmptyKeyList, getGlobalKeyList, getKey, getOsisIterator, getRawText, getValidKey, isWritable, setAliasKey, setRawText`

- - ### Field Detail

    - #### searcher

          private Searcher searcher

      How do we perform searches

    - #### bmd

          private BookMetaData bmd

      The meta data for this book

    - #### backend

          private Backend backend

      To read the data from the Book

    - #### listeners

          private List<IndexStatusListener> listeners

      The list of property change listeners

  - ### Constructor Detail

    - #### AbstractBook

          public AbstractBook(BookMetaData bmd,
                      Backend backend)

      Construct an AbstractBook given the BookMetaData and the AbstractBackend.
      Parameters:
        `bmd` - the metadata that describes the book
        `backend` - the means by which the resource is accessed

  - ### Method Detail

    - #### getScope

          public Key getScope()

      Description copied from interface: `Book`
      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 `Book.getGlobalKeyList()`, however for a Bible, it will get the references that are actually in the book.
      Specified by:
        `getScope` in interface `Book`
      Returns:
        A Key that includes all of the existing Keys

    - #### getBookMetaData

          public final BookMetaData getBookMetaData()

      Description copied from interface: `Book`
      Meta-Information: What version of the Bible is this?
      Specified by:
        `getBookMetaData` in interface `Book`
      Returns:
        A Version for this Bible

    - #### setBookMetaData

          public final void setBookMetaData(BookMetaData bmd)

      Description copied from interface: `Book`
      Set the meta-information for this book.
      Specified by:
        `setBookMetaData` in interface `Book`
      Parameters:
        `bmd` - the BookMetaData that describes this book.

    - #### getBackend

          public final Backend getBackend()

    - #### activate

          public void activate(Lock lock)

      Description copied from interface: `Activatable`
      Called to indicate that the Book should initialize itself, and consume whatever system resources it needs to be able to respond to other queries.
      Specified by:
        `activate` in interface `Activatable`
      Parameters:
        `lock` - An attempt to ensure that only the Activator calls this method

    - #### deactivate

          public void deactivate(Lock lock)

      Description copied from interface: `Activatable`
      Called to indicate that the Book should release whatever system resources it can to make way for other uses.
      Specified by:
        `deactivate` in interface `Activatable`
      Parameters:
        `lock` - An attempt to ensure that only the Activator calls this method

    - #### find

          public Key find(String request)
                   throws BookException

      Description copied from interface: `Book`
      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.
      Specified by:
        `find` in interface `Book`
      Parameters:
        `request` - The search spec.
      Returns:
        the key that matches the search or null
      Throws:
        `BookException` - If anything goes wrong with this method

    - #### find

          public Key find(SearchRequest request)
                   throws BookException

      Description copied from interface: `Book`
      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.
      Specified by:
        `find` in interface `Book`
      Parameters:
        `request` - The search spec.
      Returns:
        the key that matches the search or null
      Throws:
        `BookException` - If anything goes wrong with this method

    - #### getBook

          public Book getBook()

      Get this book.
      Returns:
        this book

    - #### getDriver

          public BookDriver getDriver()

      Description copied from interface: `Book`
      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.
      Specified by:
        `getDriver` in interface `Book`
      Returns:
        the book's driver

    - #### getDriverName

          public String getDriverName()

      Description copied from interface: `Book`
      Calculated field: The name of the name, which could be helpful to distinguish similar Books available through 2 BookDrivers.
      Specified by:
        `getDriverName` in interface `Book`
      Returns:
        The driver name

    - #### match

          public boolean match(String name)

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

    - #### getIndexStatus

          public IndexStatus getIndexStatus()

      Description copied from interface: `Book`
      Has anyone generated a search index for this Book?
      Specified by:
        `getIndexStatus` in interface `Book`
      Returns:
        the status of the index for this book.
      See Also:
        `IndexManager`

    - #### setIndexStatus

          public void setIndexStatus(IndexStatus newStatus)

      Description copied from interface: `Book`
      This method does not alter the index status, however it is for Indexers that are responsible for indexing and have changed the status themselves.
      Specified by:
        `setIndexStatus` in interface `Book`
      Parameters:
        `newStatus` - the status to set for this book
      See Also:
        `IndexManager`

    - #### getAbbreviation

          public String getAbbreviation()

      Description copied from interface: `Book`
      The abbreviation of this book - how people familiar with this book will know it, for example "NIV", "KJV".
      Specified by:
        `getAbbreviation` in interface `Book`
      Returns:
        The book's initials

    - #### getInitials

          public String getInitials()

      Description copied from interface: `Book`
      The internal name of this book.
      Specified by:
        `getInitials` in interface `Book`
      Returns:
        The book's internal name

    - #### getLanguage

          public Language getLanguage()

      Description copied from interface: `Book`
      The language of the book.
      Specified by:
        `getLanguage` in interface `Book`
      Returns:
        the common name for the language

    - #### getName

          public String getName()

      Description copied from interface: `Book`
      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.
      Specified by:
        `getName` in interface `Book`
      Returns:
        The name of this book

    - #### getOsisID

          public String getOsisID()

      Description copied from interface: `Book`
      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
      Specified by:
        `getOsisID` in interface `Book`
      Returns:
        The OSIS id of this book

    - #### getPropertyKeys

          public Set<String> getPropertyKeys()

      Description copied from interface: `Book`
      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.
      Specified by:
        `getPropertyKeys` in interface `Book`
      Returns:
        the read-only properties for this book.

    - #### getProperty

          public String getProperty(String key)

      Description copied from interface: `Book`
      Retrieve a single property for this book.
      Specified by:
        `getProperty` in interface `Book`
      Parameters:
        `key` - the key of the property.
      Returns:
        the value of the property

    - #### putProperty

          public void putProperty(String key,
                         String value)

      Description copied from interface: `Book`
      Set a property for this book.
      Specified by:
        `putProperty` in interface `Book`
      Parameters:
        `key` - the key of the property.
        `value` - the value of the property

    - #### putProperty

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

      Description copied from interface: `Book`
      Saves an entry to a particular configuration file.
      Specified by:
        `putProperty` in interface `Book`
      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

    - #### getBookCategory

          public BookCategory getBookCategory()

      Description copied from interface: `Book`
      What category of content is this, a Bible or a reference work like a Dictionary or Commentary.
      Specified by:
        `getBookCategory` in interface `Book`
      Returns:
        The category of book

    - #### isLeftToRight

          public boolean isLeftToRight()

      Description copied from interface: `Book`
      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.
      Specified by:
        `isLeftToRight` in interface `Book`
      Returns:
        true if the orientation for the dominate script is LeftToRight.

    - #### isSupported

          public boolean isSupported()

      Description copied from interface: `Book`
      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.
      Specified by:
        `isSupported` in interface `Book`
      Returns:
        true if the book is supported

    - #### isEnciphered

          public boolean isEnciphered()

      Description copied from interface: `Book`
      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.
      Specified by:
        `isEnciphered` in interface `Book`
      Returns:
        true if the book is enciphered

    - #### isLocked

          public boolean isLocked()

      Description copied from interface: `Book`
      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.
      Specified by:
        `isLocked` in interface `Book`
      Returns:
        true if the book is locked

    - #### unlock

          public boolean unlock(String unlockKey)

      Description copied from interface: `Book`
      Unlocks a book with the given key.
      Specified by:
        `unlock` in interface `Book`
      Parameters:
        `unlockKey` - the key to try
      Returns:
        true if the unlock key worked.

    - #### isUnlockKeyValid

          private boolean isUnlockKeyValid()

      This is a heuristic that tries out the key.
      Returns:
        true if there were no exceptions in reading the enciphered module.

    - #### getOsis

          protected abstract List<org.jdom2.Content> getOsis(Key key,
                                        RawTextToXmlProcessor noOpRawTextProcessor)
                                                      throws BookException

      Throws:
        `BookException`

    - #### getUnlockKey

          public String getUnlockKey()

      Description copied from interface: `Book`
      Gets the unlock key for the module.
      Specified by:
        `getUnlockKey` in interface `Book`
      Returns:
        the unlock key, if any, null otherwise.

    - #### isQuestionable

          public boolean isQuestionable()

      Description copied from interface: `Book`
      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.
      Specified by:
        `isQuestionable` in interface `Book`
      Returns:
        true if the book is questionable

    - #### hasFeature

          public boolean hasFeature(FeatureType feature)

      Description copied from interface: `Book`
      Return whether the feature is supported by the book.
      Specified by:
        `hasFeature` in interface `Book`
      Parameters:
        `feature` - the type of the Feature to check
      Returns:
        whether the feature is supported

    - #### addIndexStatusListener

          public void addIndexStatusListener(IndexStatusListener listener)

      Description copied from interface: `Book`
      Adds a `IndexStatusListener` to the listener list.

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

      Specified by:
        `addIndexStatusListener` in interface `Book`
      Parameters:
        `listener` - the `IndexStatusListener` to be added

    - #### removeIndexStatusListener

          public void removeIndexStatusListener(IndexStatusListener listener)

      Description copied from interface: `Book`
      Removes a `IndexStatusListener` from the listener list.
      Specified by:
        `removeIndexStatusListener` in interface `Book`
      Parameters:
        `listener` - the `IndexStatusListener` to be removed

    - #### firePropertyChange

          protected void firePropertyChange(IndexStatus oldStatus,
                                IndexStatus newStatus)

      Reports bound property changes. If `oldValue` and `newValue` are not equal and the `PropertyChangeEvent` listener list isn't empty, then fire a `PropertyChange` event to each listener.
      Parameters:
        `oldStatus` - the old value of the property (as an Object)
        `newStatus` - the new value of the property (as an Object)

    - #### toOSIS

          public org.jdom2.Document toOSIS()

      Description copied from interface: `Book`
      Get an OSIS representation of information concerning this Book.
      Specified by:
        `toOSIS` in interface `Book`
      Returns:
        information for this book represented as OSIS

    - #### equals

          public boolean equals(Object obj)

      Overrides:
        `equals` in class `Object`

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `Object`

    - #### compareTo

          public int compareTo(Book obj)

      Specified by:
        `compareTo` in interface `Comparable<Book>`

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`