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

Copyright ยจ 2003-2015