[jsword-devel] Jsword development

[DM Smith]

Kurt,
    I have tried the current copies of the 20060409 builds out and they 
work for me. Earlier on Sunday they were broken, but I fixed and 
re-released them about 4:15 EST on Sunday. Could you verify the current 
build? And the current WebStart?

See below to responses to the rest of your questions.

Thanks,
    DM

Kurt Andrews wrote:
> I tried the bible desktop but the installer isn't working quite 
> right.  It will download a jnlp file and clicking on that will quickly 
> open the java cache viewer followed by an instance of com.sun.javaws, 
> but both of those just shutdown without doing anything.  Then I tried 
> downloading the tar ball with the jars in it, uncompressed it into the 
> /Applications sub-directory, modified the jsword.sh shell script so 
> that the Darwin classpath would be set, then ran the shell script from 
> the command line.  Here are the results:
>
> NB:  The Java environment on my Mac is what came from the factory 
> (ver. 1.4.2.09)
> Last login: Sun Apr  9 16:02:52 on ttyp1
> Welcome to Darwin!
> kurt-andrews-computer:~ kandrews$ cd /Applications
> kurt-andrews-computer:/Applications kandrews$ cd jsword-1.0.2-20060409
> kurt-andrews-computer:/Applications/jsword-1.0.2-20060409 kandrews$ 
> ./jsword.sh
> Exception in thread "main" java.lang.UnsupportedClassVersionError: 
> org/crosswire/bibledesktop/desktop/Desktop (Unsupported major.minor 
> version 49.0)
>         at java.lang.ClassLoader.defineClass0(Native Method)
>         at java.lang.ClassLoader.defineClass(ClassLoader.java:539)
>         at 
> java.security.SecureClassLoader.defineClass(SecureClassLoader.java:123)
>         at java.net.URLClassLoader.defineClass(URLClassLoader.java:251)
>         at java.net.URLClassLoader.access$100(URLClassLoader.java:55)
>         at java.net.URLClassLoader$1.run(URLClassLoader.java:194)
>         at java.security.AccessController.doPrivileged(Native Method)
>         at java.net.URLClassLoader.findClass(URLClassLoader.java:187)
>         at java.lang.ClassLoader.loadClass(ClassLoader.java:289)
>         at sun.misc.Launcher$AppClassLoader.loadClass(Launcher.java:274)
>         at java.lang.ClassLoader.loadClass(ClassLoader.java:235)
>         at java.lang.ClassLoader.loadClassInternal(ClassLoader.java:302)
> kurt-andrews-computer:/Applications/jsword-1.0.2-20060409 kandrews$
>
> I've downloaded and installed the subclipse plugin so one I get things 
> running, if there are any todos maybe I could help out.  I don't plan 
> on bailing out of the c/c++ development, but I use eclipse, ant, and 
> clearcase every day at work so that type of environment is more 
> familiar to me and I can probably start contributing faster.
>
> I'm curious about how jsword works with sword modules.  Do the jsword 
> classes use JNI to make calls to the sword module?  I can't seem to 
> find the JNI in the source code anywhere, but I haven't found and 
> information on the gbs format either so how did you figure out how to 
> read it?  May be there's less to the xml2gbs import than I think

Well to make a long story short, JSword is a completely new 
implementation of the SWORD API. The form that it is in is roughly where 
I found it 2 years ago.
It is completely native Java, there are no JNI calls to C++.

Not sure where to start in explaining the architecture, but I'll start 
at the module (the physical file) and work outward. (This is the long 
story!)

There are different kinds of modules (called Book in JSword lingo), 
Bible, Commentary, Devotional, Dictionaries and the like. These are 
encoded in various ways. Bibles and Commentaries share a fundamental 
encoding. Dictionaries and Devotionals share a common one. This is 
because Bibles and Commentaries can be understood as Book, Chapter and 
Verse (BCV). Dictionaries and Devotionals are understood as keyed 
entries. Daily devotionals use some kind of month day notation for their 
keys. Dictionaries use terms.

And for each of these they can be raw or compressed. For Bibles, the 
compression can be by verse, chapter or book (in practice, none are by 
verse, and most, if not all are by book.) Compression can either be LZSS 
or ZIP, but in practice none are LZSS (and JSword does not support LZSS, 
for this reason).

Each module is represented by index files and data files. A key is used 
to do a lookup in the index file, which gives a start and length in the 
data file for that indexed item. Compression adds a layer of complexity.

In JSword, the Java Sword API that BibleDesktop uses, these are 
represented by a Sword Backend (see 
org.crosswire.jsword.book.sword.AbstractBackend)
These are wrapped by a BookDriver (see 
org.crosswire.jsword.book.BookDriver) which represents how a book is 
represented by a system, in this case 
org.crosswire.jsword.book.sword.SwordBoodDriver. A BookDriver, knows how 
to work with Books as a whole. The Backend for LZSS, for GenBooks and 
for one other kind of module (Webster's dictionary) have yet to be written.

Each Book (see org.crosswire.jsword.book.Book) provides the basic 
mechanisms of digging into what a book is, such as getting meta data 
about the book (e.g. name, initials, language, type, ...) and getting 
data from the book (e.g. find).

The meta data for a Book is held in a BookMetaData object (see 
org.crosswire.jsword.book.BookMetaData). In the case of 
SwordBookMetaData, this comes from the conf that describes the module. 
This is loaded via org.crosswire.jsword.book.sword.ConfigEntryTable 
where each line from the conf file is represented as a ConfigEntry 
having a ConfigEntryType.

With this we are able to locate and find a passage of a Bible or 
commentary, or an entry in a Dictionary or Daily Devotional. But, the 
modules may be encoded as PlainText, GBF (General Bible Format), ThML 
(Theological Markup Language, I think), or OSIS. The JSword approach is 
to convert each of these into OSIS (yes, even OSIS is converted, but 
trivially). This is done by filters (see 
org.crosswire.jsword.book.filter.Filter).

To display text we use a widget that is able to render HTML. So we 
convert OSIS to HTML and we use XLST to do this. (See 
bibledesktop/src/main/resources/xsl/cswing/simple.xsl for the stylesheet 
we use).

Most of the above is hidden from the casual user of the JSword API. The 
best example of the typical use of the JSword API can be found at 
org.crosswire.jsword.examples.APIExamples.

The above does not discuss indexing or module installation. To do 
indexing we use Lucene. To do module installation (aka downloading) we 
use http tunneling. See org.crosswire.jsword.index and 
org.crosswire.jsword.install for more details.

Most of our coding is against interfaces. We use a simple plugin 
architecture to load factories with the current implementation of a 
particular interface.

Hope this helps,
    DM