Classes in this File | Line Coverage | Branch Coverage | Complexity | ||||
Backend |
|
| 1.0;1 |
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, 2005 - 2016 | |
18 | * | |
19 | */ | |
20 | package org.crosswire.jsword.book.sword; | |
21 | ||
22 | import java.io.IOException; | |
23 | import java.util.List; | |
24 | ||
25 | import org.crosswire.jsword.book.BookException; | |
26 | import org.crosswire.jsword.book.BookMetaData; | |
27 | import org.crosswire.jsword.book.sword.processing.RawTextToXmlProcessor; | |
28 | import org.crosswire.jsword.book.sword.state.OpenFileState; | |
29 | import org.crosswire.jsword.passage.Key; | |
30 | import org.jdom2.Content; | |
31 | ||
32 | /** | |
33 | * Uniform representation of all Backends. | |
34 | * | |
35 | * @param <T> The type of the OpenFileState that this class extends. | |
36 | * @see gnu.lgpl.License The GNU Lesser General Public License for details. | |
37 | * @author DM Smith | |
38 | */ | |
39 | public interface Backend<T extends OpenFileState> { | |
40 | ||
41 | /** | |
42 | * @return Returns the Sword BookMetaData. | |
43 | */ | |
44 | BookMetaData getBookMetaData(); | |
45 | ||
46 | /** | |
47 | * Decipher the data in place, if it is enciphered and there is a key to | |
48 | * unlock it. | |
49 | * | |
50 | * @param data the data to unlock | |
51 | */ | |
52 | void decipher(byte[] data); | |
53 | ||
54 | /** | |
55 | * Encipher the data in place, if there is a key to unlock it. | |
56 | * | |
57 | * @param data | |
58 | */ | |
59 | void encipher(byte[] data); | |
60 | ||
61 | /** | |
62 | * Initialize a AbstractBackend before use. This method needs to call | |
63 | * addKey() a number of times on GenBookBackend | |
64 | * | |
65 | * @return the list of all keys for the book | |
66 | * @deprecated no replacement | |
67 | */ | |
68 | @Deprecated | |
69 | Key readIndex(); | |
70 | ||
71 | /** | |
72 | * Determine whether this Book contains the key in question | |
73 | * | |
74 | * @param key The key whose presence is desired. | |
75 | * @return true if the Book contains the key | |
76 | */ | |
77 | boolean contains(Key key); | |
78 | ||
79 | /** | |
80 | * Get the text as it is found in the Book for the given key | |
81 | * | |
82 | * @param key the key for which the raw text is desired. | |
83 | * @return the text from the module | |
84 | * @throws BookException | |
85 | */ | |
86 | String getRawText(Key key) throws BookException; | |
87 | ||
88 | void setAliasKey(Key alias, Key source) throws BookException; | |
89 | ||
90 | /** | |
91 | * Determine the size of the raw data for the key in question. | |
92 | * This method may not be faster than getting the raw text and getting its size. | |
93 | * | |
94 | * @param key The key whose raw data length is desired. | |
95 | * @return The length of the raw data, 0 if not a valid key. | |
96 | */ | |
97 | int getRawTextLength(Key key); | |
98 | ||
99 | /** | |
100 | * Gets the fast global key list, and if this operation is not supported, throws a {@link UnsupportedOperationException} | |
101 | * | |
102 | * @return the fast global key list | |
103 | * @throws BookException the book exception if for some reason the book failed to be read properly. | |
104 | */ | |
105 | Key getGlobalKeyList() throws BookException; | |
106 | ||
107 | /** | |
108 | * Get the text allotted for the given entry | |
109 | * | |
110 | * @param key The key to fetch | |
111 | * @param processor processor that executes before/after the content is read from | |
112 | * disk or another kind of backend | |
113 | * @return String The data for the verse in question | |
114 | * @throws BookException If the data can not be read. | |
115 | */ | |
116 | List<Content> readToOsis(Key key, RawTextToXmlProcessor processor) throws BookException; | |
117 | ||
118 | /** | |
119 | * Create the directory to hold the Book if it does not exist. | |
120 | * | |
121 | * @throws IOException | |
122 | * @throws BookException | |
123 | */ | |
124 | void create() throws IOException, BookException; | |
125 | ||
126 | /** | |
127 | * Returns whether this AbstractBackend is implemented. | |
128 | * | |
129 | * @return true if this AbstractBackend is implemented. | |
130 | */ | |
131 | boolean isSupported(); | |
132 | ||
133 | /** | |
134 | * A Backend is writable if the file system allows the underlying files to | |
135 | * be opened for writing and if the backend has implemented writing. | |
136 | * Ultimately, all drivers should allow writing. At this time writing is not | |
137 | * supported by most backends, so abstract implementations should return false | |
138 | * and let specific implementations return true otherwise. | |
139 | * | |
140 | * @return true if the book is writable | |
141 | */ | |
142 | boolean isWritable(); | |
143 | } |