org.crosswire.jsword.book.sword

## Class AbstractBackend<T extends OpenFileState>

- java.lang.Object
- - org.crosswire.jsword.book.sword.AbstractBackend<T>

- Type Parameters:
    `T` - The type of the OpenFileState that this class extends.
  All Implemented Interfaces:
    Backend<T>, StatefulFileBackedBackend<T>
  Direct Known Subclasses:
    AbstractKeyBackend, GenBookBackend, RawBackend, ZVerseBackend

      public abstract class AbstractBackend<T extends OpenFileState>
      extends Object
      implements StatefulFileBackedBackend<T>, Backend<T>

  A generic way to read data from disk for later formatting.
  Author:
    Joe Walker, DM Smith
  See Also:
    `The GNU Lesser General Public License for details.`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `private SwordBookMetaData` | `bmd`
    `private static org.slf4j.Logger` | `LOGGER`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `AbstractBackend()` Default constructor for the sake of serialization.
    `AbstractBackend(SwordBookMetaData sbmd)` Construct a minimal backend

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `abstract boolean` | `contains(Key key)` Determine whether this Book contains the key in question
    `void` | `create()` Create the directory to hold the Book if it does not exist.
    `void` | `decipher(byte[] data)` Decipher the data in place, if it is enciphered and there is a key to unlock it.
    `void` | `encipher(byte[] data)` Encipher the data in place, if there is a key to unlock it.
    `BookMetaData` | `getBookMetaData()`
    `Key` | `getGlobalKeyList()` Gets the fast global key list, and if this operation is not supported, throws a `UnsupportedOperationException`
    `String` | `getRawText(Key key)` Get the text as it is found in the Book for the given key
    `int` | `getRawTextLength(Key key)` Determine the size of the raw data for the key in question.
    `boolean` | `isSupported()` Returns whether this AbstractBackend is implemented.
    `boolean` | `isWritable()` A Backend is writable if the file system allows the underlying files to be opened for writing and if the backend has implemented writing.
    `Key` | `readIndex()` Initialize a AbstractBackend before use.
    `private void` | `readNormalOsis(Key key, RawTextToXmlProcessor processor, List<org.jdom2.Content> content, T openFileState)`
    `private void` | `readNormalOsisSingleKey(Key key, RawTextToXmlProcessor processor, List<org.jdom2.Content> content, T openFileState)` Avoid using iterator for GenBook TreeKeys which would cause a GenBook nodes children to be appended to their parent e.g.
    `private Verse` | `readPassageOsis(Key key, RawTextToXmlProcessor processor, List<org.jdom2.Content> content, T openFileState)` Reads a passage as OSIS
    `List<org.jdom2.Content>` | `readToOsis(Key key, RawTextToXmlProcessor processor)` Get the text allotted for the given entry
    `void` | `setAliasKey(Key alias, Key source)`
    `private void` | `throwFailedKeyException(Key masterKey, Key currentKey, IOException e)` If non-null, currentKey is used to throw the exception, other, masterKey is used instead, which will be more general.

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

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

    - ### Methods inherited from interface org.crosswire.jsword.book.sword.StatefulFileBackedBackend

      `initState, readRawContent, setAliasKey, setRawText`

- - ### Field Detail

    - #### bmd

          private SwordBookMetaData bmd

    - #### LOGGER

          private static final org.slf4j.Logger LOGGER

  - ### Constructor Detail

    - #### AbstractBackend

          public AbstractBackend()

      Default constructor for the sake of serialization.

    - #### AbstractBackend

          public AbstractBackend(SwordBookMetaData sbmd)

      Construct a minimal backend
      Parameters:
        `sbmd` -

  - ### Method Detail

    - #### getBookMetaData

          public BookMetaData getBookMetaData()

      Specified by:
        `getBookMetaData` in interface `Backend<T extends OpenFileState>`
      Returns:
        Returns the Sword BookMetaData.

    - #### decipher

          public void decipher(byte[] data)

      Description copied from interface: `Backend`
      Decipher the data in place, if it is enciphered and there is a key to unlock it.
      Specified by:
        `decipher` in interface `Backend<T extends OpenFileState>`
      Parameters:
        `data` - the data to unlock

    - #### encipher

          public void encipher(byte[] data)

      Description copied from interface: `Backend`
      Encipher the data in place, if there is a key to unlock it.
      Specified by:
        `encipher` in interface `Backend<T extends OpenFileState>`

    - #### readIndex

          public Key readIndex()

      Description copied from interface: `Backend`
      Initialize a AbstractBackend before use. This method needs to call addKey() a number of times on GenBookBackend
      Specified by:
        `readIndex` in interface `Backend<T extends OpenFileState>`
      Returns:
        the list of all keys for the book

    - #### contains

          public abstract boolean contains(Key key)

      Description copied from interface: `Backend`
      Determine whether this Book contains the key in question
      Specified by:
        `contains` in interface `Backend<T extends OpenFileState>`
      Parameters:
        `key` - The key whose presence is desired.
      Returns:
        true if the Book contains the key

    - #### getRawText

          public String getRawText(Key key)
                            throws BookException

      Description copied from interface: `Backend`
      Get the text as it is found in the Book for the given key
      Specified by:
        `getRawText` in interface `Backend<T extends OpenFileState>`
      Parameters:
        `key` - the key for which the raw text is desired.
      Returns:
        the text from the module
      Throws:
        `BookException`

    - #### setAliasKey

          public void setAliasKey(Key alias,
                         Key source)
                           throws BookException

      Specified by:
        `setAliasKey` in interface `Backend<T extends OpenFileState>`
      Throws:
        `BookException`

    - #### getRawTextLength

          public int getRawTextLength(Key key)

      Description copied from interface: `Backend`
      Determine the size of the raw data for the key in question. This method may not be faster than getting the raw text and getting its size.
      Specified by:
        `getRawTextLength` in interface `Backend<T extends OpenFileState>`
      Parameters:
        `key` - The key whose raw data length is desired.
      Returns:
        The length of the raw data, 0 if not a valid key.

    - #### getGlobalKeyList

          public Key getGlobalKeyList()
                               throws BookException

      Description copied from interface: `Backend`
      Gets the fast global key list, and if this operation is not supported, throws a `UnsupportedOperationException`
      Specified by:
        `getGlobalKeyList` in interface `Backend<T extends OpenFileState>`
      Returns:
        the fast global key list
      Throws:
        `BookException` - the book exception if for some reason the book failed to be read properly.

    - #### readToOsis

          public List<org.jdom2.Content> readToOsis(Key key,
                                           RawTextToXmlProcessor processor)
                                             throws BookException

      Description copied from interface: `Backend`
      Get the text allotted for the given entry
      Specified by:
        `readToOsis` in interface `Backend<T extends OpenFileState>`
      Parameters:
        `key` - The key to fetch
        `processor` - processor that executes before/after the content is read from disk or another kind of backend
      Returns:
        String The data for the verse in question
      Throws:
        `BookException` - If the data can not be read.

    - #### readNormalOsis

          private void readNormalOsis(Key key,
                            RawTextToXmlProcessor processor,
                            List<org.jdom2.Content> content,
                            T openFileState)
                               throws BookException

      Throws:
        `BookException`

    - #### readNormalOsisSingleKey

          private void readNormalOsisSingleKey(Key key,
                                     RawTextToXmlProcessor processor,
                                     List<org.jdom2.Content> content,
                                     T openFileState)
                                        throws BookException

      Avoid using iterator for GenBook TreeKeys which would cause a GenBook nodes children to be appended to their parent e.g. the top level page would include the whole book and result in OOM error
      Throws:
        `BookException`

    - #### readPassageOsis

          private Verse readPassageOsis(Key key,
                              RawTextToXmlProcessor processor,
                              List<org.jdom2.Content> content,
                              T openFileState)
                                 throws BookException

      Reads a passage as OSIS
      Parameters:
        `key` - the given key
        `processor` - a processor for which to do things with
        `content` - a list of content to be appended to (i.e. the OSIS data)
        `openFileState` - the open file state, from which we read things
      Throws:
        `BookException` - a book exception if we failed to read the book

    - #### throwFailedKeyException

          private void throwFailedKeyException(Key masterKey,
                                     Key currentKey,
                                     IOException e)
                                        throws BookException

      If non-null, currentKey is used to throw the exception, other, masterKey is used instead, which will be more general.
      Parameters:
        `masterKey` - the key containing currentKey
        `currentKey` - the currentKey
        `e` - the exception that occured
      Throws:
        `BookException` - always thrown, a `BookException`

    - #### create

          public void create()
                      throws IOException,
                             BookException

      Description copied from interface: `Backend`
      Create the directory to hold the Book if it does not exist.
      Specified by:
        `create` in interface `Backend<T extends OpenFileState>`
      Throws:
        `IOException`
        `BookException`

    - #### isSupported

          public boolean isSupported()

      Description copied from interface: `Backend`
      Returns whether this AbstractBackend is implemented.
      Specified by:
        `isSupported` in interface `Backend<T extends OpenFileState>`
      Returns:
        true if this AbstractBackend is implemented.

    - #### isWritable

          public boolean isWritable()

      Description copied from interface: `Backend`
      A Backend is writable if the file system allows the underlying files to be opened for writing and if the backend has implemented writing. Ultimately, all drivers should allow writing. At this time writing is not supported by most backends, so abstract implementations should return false and let specific implementations return true otherwise.
      Specified by:
        `isWritable` in interface `Backend<T extends OpenFileState>`
      Returns:
        true if the book is writable