| package-info.java |
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 /** 21 * The Book package provides an interface to a real store of data. 22 * Different sources of data interact with the rest of the code via a 23 * <code>Book</code> interface. An implementation of <code>Book</code> is 24 * expected to be able to retrieve Biblical text for a given 25 * <code>Passage</code>, and to return a <code>Passage</code> of verses that 26 * contain a word. 27 * 28 * <p>A Bible is a specialization of a Book that uses Passages as basic data 29 * types.</p> 30 * 31 * <p>The following is out of date since the Version -> Book/Bible split</p> 32 * 33 * <p>There are several specializations of the <code>Book</code> interface. 34 * A <code>MutableBook</code> is-a <code>Book</code> that can be changed 35 * either to accommodate Verse based notes or for a normal <code>Book</code> 36 * that can be created at run-time. The latter option allows this system to 37 * be installed on a computer that already has OLB installed without 38 * requiring a download of the complete Bible source, but the source is 39 * created either as part of the install or on the fly, and cached here.</p> 40 * 41 * <p>Secondly a <code>Translation</code> is a <code>Book</code> that 42 * understands Strong's numbering and can give information about how words are 43 * translated to and from the original.</p> 44 * 45 * <p>Currently there are 2 basic implementations of the <code>Book</code> 46 * interface - an <code>ODBCBook</code> and a <code>FileBook</code>. The 47 * former acts on an Access database via JBDC and ODBC. The latter on an 48 * experimental serialized data store. Probably neither of these 49 * implementations are of any long term use, however they do help get me up 50 * to speed quickly.</p> 51 * 52 * <p>I envisage at least 2 more production stores - an 53 * <code>OLBBook</code> that reads directly from OLB files exactly as 54 * installed on Windows. (Maybe in reality there needs to be an 55 * <code>OLB7Book</code> and an <code>OLB8Book</code> or something) 56 * and a <code>RemoteBook</code> that uses RMI / CORBA / HTTP or whatever 57 * to retrieve the data from a remote server)</p> 58 * 59 * <p>It is important that multiple data sources are available, to allow a 60 * compact download time. In an ideal world the base download, would be 61 * small enough to place as an applet on a web page, with some kind of 62 * "Save as application functionality" that still uses a remote 63 * data server. A caching Book could then store verses locally, only 64 * using the network for verses not retrieved yet.</p> 65 * 66 * <p>The Biblical text is returned to the application as an XML document. 67 * Allowing <code>Book</code>s to contain data like red-letter markup 68 * that a display module may not want to use. See the display section for 69 * more details.</p> 70 * 71 * <p>More work is needed here to with Strong's numbers and non-Biblical text 72 * sources. (Lexicons and such like)</p> 73 * 74 * 75 * <h3>Startup</h3> 76 * 77 * <p>The startup procedure goes like this. When <code>Books</code> is first called 78 * it looks up the implementations of BookDriver (using Project.resource()) and 79 * calls registerDriver() for each. This calls getBooks() on the new BookDriver 80 * which should return an array of BookMetaData objects.</p> 81 * 82 * <p>Ideally when the BookDriver creates a BookMetaData object it should also 83 * create a Book to go with it, and do everything it can to ensure that future reads 84 * from the Book will be Exception free, but without consuming significant system 85 * resources. So the process of constructing a BookMetaData and associated Book 86 * should check that the index file exists and is readable, but not actually load 87 * it. BookDriver is allowed to complain that it can't do everything it wants, but 88 * it should not hand BookMetaData objects back that are faulty.</p> 89 * 90 * <p>This means that the user can browse through the BookMetaData objects without 91 * causing any stress to the system, and yet be fairly assured that when they do 92 * call getBook() on the BookMetaData that everything will work fine.</p> 93 * 94 * <p>Finally when BookMetaData.getBook() is called, it should ask the Book to load 95 * any system resources that are needed to fulfill the requests.</p> 96 * 97 * 98 * <h3>Caching</h3> 99 * 100 * <p>We used to have a CacheingBookDriver (now deleted) that was designed to allow 101 * data to be cached as it is read. Maybe at some stage we should add it back in 102 * again, but we would need to make Drivers writable before we do that.</p> 103 * 104 * <p>The designed features of CacheingBookDriver are: 105 * <ul> 106 * <li>Ability to cache multiple (possibly remote) sources</li> 107 * <li>Use of JDBC style URL to help cached data to re-connect with source</li> 108 * <li>Can be used with multiple caching schemes (sword, ser, ...)</li> 109 * </ul> 110 * 111 * <p>So it is up to the actual caching scheme to distinguish cached data from 112 * other normal data, and to be able to return a original source URL in case 113 * not all of the data is present.</p> 114 */ 115 package org.crosswire.jsword.book; 116