Source code: com/eireneh/bible/book/Book.java
1
2 package com.eireneh.bible.book;
3
4 /**
5 * Book is the most basic store of textual data - It can retrieve data
6 * either as an XML document or as plain text - It uses Bookmarks to refer
7 * to parts of itself, and can search for words (returning Bookmarks).
8 *
9 * <p>All Books should have an no-arg constructor. This restriction is
10 * important because without this the config package can not create an
11 * instance of this class from a string in an options file.</p>
12 *
13 * <p>What type should we use to describe a part of a book that we want to
14 * wiew? This question is made more complex because a find() operation
15 * needs to be able to return a collection of pointers.</p>
16 * <ul>
17 * <li>String: This is simple, however the requirement to allow
18 * transfer of several pointers in a single String means using
19 * delimitters, which make Books un-necessarily more complex.</li>
20 * <li>String[]: This may be a simpler solution, however it does not
21 * work well with Passage, and it specifies the collection method</li>
22 * <li>Collection: Enforces JDK 1.2 dependancy, and is not clearly typed
23 * which means that to work with Passage we would need somthing like
24 * <code>Vector find()</code> and <code>Passage findRef()</code>.</li>
25 * <li>Bookmark[]: See problems for String[]</li>
26 * <li>Bookmarks: Works well with Passage (Passage extends Bookmarks and
27 * Verse and VerseRange extend Bookmark) and it lets the implementor
28 * choose the implementation. This is the best method</li>
29 * </ul>
30 * <p>What type should we use to pass around DOM Documents? The options
31 * seem to be:
32 * <ul>
33 * <li>Document: Just use the basic <code>org.w3c.dom.Document</code> type
34 * This is fairly simple, although it increases dependacies on outside
35 * code (slightly) It is effectively a weak type, since a Document
36 * could contain anything.</ul>
37 * <li>BlahDOM: This biggest problem with this is that it makes access to
38 * the data more complex. It could allow is to store a 'current node'
39 * pointer which could be useful. This is the best method</ul>
40 * </ul>
41 *
42 * <p>Each Book needs a GUI to select a Bookmark for viewing. The GUI
43 * layout is very Book dependant however, we do not want to put GUI
44 * dependancies into non-GUI code, so there is no Component getSelector()
45 * interface. Maybe a Class getGUISelector() interface would be better? or
46 * we could have a convention like <book_class_path>.swing.Selector</p>
47 *
48 * <p>We also need to consider handling DOMs
49 * <pre>
50 * interface BaseDOM
51 * {
52 * public Document getDom();
53 *
54 * public DTD getDTD();
55 * public void setDTD(DTD dtd);
56 * }
57 *
58 * // Consider THML when thinking about the DTD
59 * class BookDOM extends BaseDOM
60 * {
61 * public String getText();
62 * }
63 * </pre></p>
64 *
65 * <table border='1' cellPadding='3' cellSpacing='0' width="100%">
66 * <tr><td bgColor='white'class='TableRowColor'><font size='-7'>
67 * Distribution Licence:<br />
68 * Project B is free software; you can redistribute it
69 * and/or modify it under the terms of the GNU General Public License,
70 * version 2 as published by the Free Software Foundation.<br />
71 * This program is distributed in the hope that it will be useful,
72 * but WITHOUT ANY WARRANTY; without even the implied warranty of
73 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
74 * General Public License for more details.<br />
75 * The License is available on the internet
76 * <a href='http://www.gnu.org/copyleft/gpl.html'>here</a>, by writing to
77 * <i>Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
78 * MA 02111-1307, USA</i>, Or locally at the Licence link below.<br />
79 * The copyright to this program is held by it's authors.
80 * </font></td></tr></table>
81 * @see <a href='http://www.eireneh.com/servlets/Web'>Project B Home</a>
82 * @see docs.Licence
83 * @author Joe Walker
84 * @version D0.I0.T0
85 * @stereotype role
86 */
87 public interface Book
88 {
89 /*
90 * Create an String for the specified Verses. There is some debate in
91 * my mind as to whether this should be more like:
92 * <code>String getText(Verse v)</code>. The problem with this version
93 * is that it doesn't tell you about where the verse ends. It is just
94 * raw text, so if you want to know about verse endings you will need
95 * to call this several times (as you would have to with the
96 * alternative) however means there is more Object creation to be done
97 * @param range The verses to search for
98 * @return The Bible text
99 *
100 public String getText(String bookmark) throws BookException;
101 */
102
103 /*
104 * Create an XML document for the specified Verses
105 * @param doc The XML document
106 * @param ele The Element to start adding at. null if the doc is empty
107 * @param ref The verses to search for
108 *
109 public void getDocument(Document doc, Element ele, String bookmark) throws BookException;
110 */
111
112 /*
113 * For a given word find a list of references to it
114 * @param word The text to search for
115 * @return The references to the word
116 *
117 public String find(String word) throws BookException;
118 */
119 }