Source code: com/eireneh/bible/book/Bible.java
1
2 package com.eireneh.bible.book;
3
4 import java.net.URL;
5 import java.util.Enumeration;
6
7 import org.jdom.*;
8
9 import com.eireneh.config.Config;
10 import com.eireneh.bible.passage.*;
11
12 /**
13 * Bible is the core interface to a Bible store.
14 * <p>The methods of this interface come into 3 categories:
15 * Meta-Information methods return information about the implementation
16 * and its environment. Retrieval methods are the core methods that give
17 * access to the real Biblical text. These are the core of the interface.
18 * Generation methods are there to allow this Version to be generated.
19 * TODO: Generalize this for the Book interface
20 *
21 * <table border='1' cellPadding='3' cellSpacing='0' width="100%">
22 * <tr><td bgColor='white'class='TableRowColor'><font size='-7'>
23 * Distribution Licence:<br />
24 * Project B is free software; you can redistribute it
25 * and/or modify it under the terms of the GNU General Public License,
26 * version 2 as published by the Free Software Foundation.<br />
27 * This program is distributed in the hope that it will be useful,
28 * but WITHOUT ANY WARRANTY; without even the implied warranty of
29 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
30 * General Public License for more details.<br />
31 * The License is available on the internet
32 * <a href='http://www.gnu.org/copyleft/gpl.html'>here</a>, by writing to
33 * <i>Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
34 * MA 02111-1307, USA</i>, Or locally at the Licence link below.<br />
35 * The copyright to this program is held by it's authors.
36 * </font></td></tr></table>
37 * @see <a href='http://www.eireneh.com/servlets/Web'>Project B Home</a>
38 * @see docs.Licence
39 * @author Joe Walker
40 * @version D8.I7.T2
41 * @stereotype role
42 */
43 public interface Bible extends Book
44 {
45 /**
46 * Meta-Information: What driver is controlling this Bible?
47 * @return A BibleDriver relevant to this Bible
48 */
49 public BibleDriver getDriver();
50
51 /**
52 * Meta-Information: What name can I use to get this Bible in a call
53 * to <code>Bibles.getBible(name);</code>. I'm not sure that with the
54 * <code>getVersion()</code> method this makes a huge amount of sense.
55 * Might we be better off making people ask for a Bible by version and
56 * maybe driver rather than by name?
57 * @return The name of this Bible
58 */
59 public String getName();
60
61 /**
62 * Meta-Information: What version of the Bible is this?
63 * @return A Version for this Bible
64 */
65 public Version getVersion();
66
67 /**
68 * Meta-Information: What configuration options are available.
69 * A null return from this IS valid, and means, there aren't options
70 * to configure.
71 * @return A Config set
72 */
73 public Config getProperties() throws BookException;
74
75 /**
76 * Meta-Information: If there is something to configure, and the
77 * config options are worth saving to disk (this may not be the case
78 * for read-only options) then this is where to save the stuff to.
79 * @return URL to save a properties file to
80 */
81 public URL getPropertiesURL();
82
83 /**
84 * Retrieval: Create an String for the specified Verses.
85 * There is a trivial implementation of this (slightly simplified):
86 * <pre>
87 * BibleEle doc = BibleEle.createDocument();
88 * getDocument(doc, range);
89 * return doc.getText();
90 * </pre>
91 * So maybe this is redundant? A simple text-only Book could have a
92 * custom implementation of this that saves going near any XML. This
93 * could be particularly useful for Psion type implementaions
94 * <p>There is some debate in my mind as to whether this should be
95 * more like: <code>String getText(Verse v)</code>. The problem with
96 * this version is that it doesn't tell you about where the verse
97 * ends. It is just raw text, so if you want to know about verse
98 * endings you will need to call this several times (as you would have
99 * to with the alternative) however means there is more Object
100 * creation to be done.
101 * @param range The verses to search for
102 * @return The Bible text
103 */
104 public String getText(VerseRange range) throws BookException;
105
106 /**
107 * Retrieval: Add to the given document some mark-up for the specified
108 * Verses.
109 * @deprecated Use JDOM instead
110 * @param doc The document
111 * @param ref The verses to search for
112 */
113 public void getDocument(BibleEle doc, Passage ref) throws BookException;
114
115 /**
116 * Retrieval: Use JDOM to retrieve some Bible data
117 * @param doc The document
118 * @param ref The verses to search for
119 */
120 public Element getElement(Passage ref) throws BookException;
121
122 /**
123 * Retrieval: For a given word find a list of references to it
124 * @param word The text to search for
125 * @return The references to the word
126 */
127 public Passage findPassage(String word) throws BookException;
128
129 /**
130 * Retrieval: Get a list of the words used by this Version. This is
131 * not vital for normal display, however it is very useful for various
132 * things, not least of which is new Version generation. However if
133 * you are only looking to <i>display</i> from this Bible then you
134 * could skip this one.
135 * <p>I am tempted to make this mandatory since failing to implement
136 * this method will just make your Book harder to generate new Books
137 * from. This needs some thought.
138 * @return The references to the word
139 */
140 public Enumeration listWords() throws BookException;
141
142 /**
143 * Retrieval: Return an array of words that are used by this Bible
144 * that start with the given string. For example calling:
145 * <code>getStartsWith("love")</code> will return something like:
146 * { "love", "loves", "lover", "lovely", ... }
147 * This is only needed to make your this driver play well
148 * in searches it is not vital for normal display. To save yourself
149 * the bother of implementing this properly you could do:
150 * <code>return new String[] { base };</code>
151 * @param base The word to base your word array on
152 * @return An array of words starting with the base
153 */
154 public String[] getStartsWith(String base) throws BookException;
155
156 /**
157 * Generation: Read from the given source version to generate
158 * ourselves. It should periodically call:
159 * <code>Thread.currentThread().isInterrupted()</code>
160 * to check that it is safe to continue, and clear up if not.
161 * @param version The source
162 */
163 public void generate(Bible version) throws BookException;
164
165 /**
166 * Generation: Add a progress listener to the list of things wanting
167 * to know whenever we make some progress
168 * @param li The listener to add
169 */
170 public void addProgressListener(ProgressListener li);
171
172 /**
173 * Generation: Remove a progress listener from the list of things
174 * wanting to know whenever we make some progress
175 * @param li The listener to remove
176 */
177 public void removeProgressListener(ProgressListener li);
178 }