1   /**
2    * Distribution License:
3    * JSword is free software; you can redistribute it and/or modify it under
4    * the terms of the GNU Lesser General Public License, version 2.1 or later
5    * as published by the Free Software Foundation. This program is distributed
6    * in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even
7    * the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
8    * See the GNU Lesser General Public License for more details.
9    *
10   * The License is available on the internet at:
11   *      http://www.gnu.org/copyleft/lgpl.html
12   * or by writing to:
13   *      Free Software Foundation, Inc.
14   *      59 Temple Place - Suite 330
15   *      Boston, MA 02111-1307, USA
16   *
17   * © CrossWire Bible Society, 2012 - 2016
18   *
19   */
20  package org.crosswire.jsword.book.sword;
21  
22  import java.io.IOException;
23  
24  import org.crosswire.jsword.book.BookException;
25  import org.crosswire.jsword.book.sword.state.OpenFileState;
26  import org.crosswire.jsword.passage.Key;
27  
28  /**
29   * Indicates that there is a stateful backend
30   *
31   *
32   * @param <T> The type of the OpenFileState that this class extends.
33   * @see gnu.lgpl.License The GNU Lesser General Public License for details.
34   * @author DM Smith
35   */
36  public interface StatefulFileBackedBackend<T extends OpenFileState> {
37      /**
38       * Initialises the state required to read from files, specific to each
39       * different backend
40       * 
41       * @return the state that has been initialised
42       * @throws BookException
43       */
44       T initState() throws BookException;
45  
46      /**
47       * 
48       * @param state
49       *            the state object containing all the open random access files
50       * @param key
51       *            the verse that is sought
52       * @return the raw text
53       * @throws BookException 
54       * @throws IOException
55       *             something went wrong when reading the verse
56       */
57       String readRawContent(T state, Key key) throws BookException, IOException;
58  
59       /**
60        * Set the text allotted for the given verse
61        * 
62        * @param state
63        *            TODO
64        * @param key
65        *            The key to set text to
66        * @param text
67        *            The text to be set for key
68        * 
69        * @throws BookException
70        *             If the data can not be set.
71        * @throws IOException
72        *             If the module data path could not be created.
73        */
74       void setRawText(T state, Key key, String text) throws BookException, IOException;
75  
76       /**
77        * Sets alias for a comment on a verse range I.e. setRawText() was for verse
78        * range Gen.1.1-3 then setAliasKey should be called for Gen.1.1.2 and
79        * Gen.1.1.3
80        * 
81        * @param state 
82        *            the open file state
83        * @param alias
84        *            Alias Key
85        * @param source
86        *            Source Key
87        * @throws IOException
88        *             Exception when anything goes wrong on writing the alias
89        */
90       void setAliasKey(T state, Key alias, Key source) throws IOException;
91  }
92