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

Interface Book

Method Summary

Methods inherited from interface org.crosswire.common.activate.Activatable

Methods inherited from interface java.lang.Comparable

Method Detail

getGlobalKeyList

getScope

getValidKey

getKey

createEmptyKeyList

getBookMetaData

setBookMetaData

getOsisIterator

contains

getRawText

isWritable

setRawText

setAliasKey

find

find

getName

getBookCategory

getDriver

getLanguage

getAbbreviation

getInitials

getOsisID

match

isSupported

isEnciphered

isLocked

unlock

getUnlockKey

isQuestionable

getDriverName

isLeftToRight

hasFeature

getPropertyKeys

getProperty

putProperty

putProperty

getIndexStatus

setIndexStatus

toOSIS

addIndexStatusListener

removeIndexStatusListener