Difference between revisions of "DevTools:JSword"

Revision as of 13:43, 3 August 2009

About JSword

JSword is an implementation of the SWORD API.

That said, it should be noted that it is not a port.

The JSword Project is a group of free programs that work together to bring Bible study to a wide range of people using the Java platform. Applications using JSword include BibleDesktop, a free desktop based Bible study tool, FireBible and Alkitab Bible Study.

Since it is written in Java (JDK 1.4) it will run on most computers. Currently we regularly test on Windows, Linux and MacOS X, but it ought to work on Solaris and other places where JDK 1.4 or higher is available, and could be easily extended to work on set-top boxes and PDAs.

The software produced by the JSword project is open source software so it is freely available to anyone. It is licensed under the LGPL for the libraries and GPL for the application.

There are several components to the JSword project, the most commonly used is BibleDesktop. The core API is called JSword and there are two generic libraries of useful utilities called common and common-swing. For a complete listing see instructions on getting the code

Basic API Functions: APIExamples.java

The structure of the JSword engine, much like the original Sword engine, it is essentially a Library of Books with powerful search, install and output features. If you're a beginner to the Sword project, the APIExamples.api under /src/main/java -> org.crosswire.jsword.examples will be most helpful to you. In this you will find the most basic functioning of the key classes of the JSword engine.

Installer and Install Manager

Before you can use, read and perform any functions on Bible or other texts, you must first obtain the actual text. (However sometimes the KJV Bible text is already bundled with the download) The JSword engine has some abstracted functions which allow you to very cleanly install texts onto your program without knowledge of the acutal install tasks. This is done using the Installer and InstallManager.

InstallManager – A manager to abstract out the non-view specific book installation tasks.

Installer – An interface that allows us to download from a specific source of Bible data. It is important that implementor of this interface define equals() and hashcode() properly.

Looking at API examples you are able to see how these work together to install a text. In installBook() you can see that getInstallers() of InstallManager is used to find all the Installers (sources of Bible Data) online which can be used to obtain texts. Similarly if you already know which installer you want to use eg. the CrossWire server, you can directly put that into the getInstallers("CrossWire") arguement to return the correct installer. Now that an Installer is selected we can now check what books are available on that server.

As you can see the list of books is refreshed by the reloadBookList() and then the list of available books on that installer is obtained by running getBooks() of the installer.

Book- Book is the most basic store of textual data – It can retrieve data either as an XML document or as plain text – It uses Keys to refer to parts of itself, and can search for words (returning Keys).

Here you will find many different versions of the Bible and also commentaries and devotions. The book can then be downloaded and installed with the function install(book) of the installer. This will then automatically download the text from the designated server and install the files to the correct directory so that the text can be viewed and searched by other functions.

How JSword Finds Books

The code is in

o.c.j.book.sword.SwordBookPath

with help from

o.c.c.common.util.OSType to handle OS specific locations.

The OS specific location is (I'll use USER_OS_LOC below for this)

HOME/Application Data/Sword -- Windows

HOME/Library/Application Support/Sword -- Mac

HOME/.sword -- elsewhere that Java runs

JSWORD_HOME defaults to USER_OS_LOC/JSword on Mac and Windows and USER_OS_LOC/.jsword elsewhere.

JSWORD_HOME is used to find user preferences and also program overrides.

There is no default for SWORD_HOME.

Here is the lookup order: The established SWORD download directory. Then the user "augment" paths. Finally the "default" paths.

The SWORD download path is determined by the following rules:

This is either a directory that the user chose

failing that

it is the first default download dir for the application.

The default download dir is

the first writable folder in the "default" paths

failing that

USER_OS_LOC

Note: if the directory does not exist, which is typically the case in a first time use of a SWORD/JSword app, it is not considered and this will establish USER_OS_LOC as the download location.

The "augment" paths are the paths that a user specifies in preferences (aka preferences).

With this they have control.

The default paths are ordered thus:

process CWD/sword.conf

CWD

CWD/../Library

SWORD_HOME

C:\Program Files\CrossWire\The SWORD Project

C:\Program Files\CrossWire

process HOME/sword.conf

process /etc/sword.conf

process /usr/local/etc/sword.conf

USER_OS_LOC

JSWORD_HOME

These are evaluated on startup. PWD is problematic. If the program is run from shell script or equivalent, it is as expected. Otherwise, it is not well defined and entirely unpredictable.

Processing of sword.conf (now that I look at the code, I think this is broken):

Add DATA_PATH

Add AUGMENT_PATH

Two conditions need to be met in order for a path to be added to default paths:

The directory contains a mods.d directory.

The mods.d directory is readable.

Note: The BibleCS installer plays with SWORD_PATH, setting it. And BibleCS default location is in the path early. That's because, it does not play well with any other apps. It's presence supersedes the "proper" behavior. Defaulting SWORD_HOME, like JSWORD_HOME would "fix" that.

We don't do a shared location ALLUSERSPROFILE on Windows. Nor do we do /Users/Shared/Sword on Mac (I'd work with Manfred to determine the right location). If I were to add it, it would be just above USER_OS_LOC in both places in the algorithm.

Regarding the Portable Bible Desktop, we do things just a bit differently. The code above is the same, but we play with how it is called.
The layout:

BibleDesktop -- Contains startup scripts for Windows (BibleDesktopWin.exe), Mac (BibleDesktopMac.app) and Unix (BibleDesktopUnix.sh)

BibleDesktop/lib -- The jar files

BibleDesktop/JSword -- the JSWORD_HOME (add desktop.properties here to set default properties)

Java/win32 -- Java for Windows

Java/linux -- Java for linux

modules

mods.d

Given this the startup scripts set:

SWORD_HOME to the folder containing the BibleDesktop folder.

JSWORD_HOME to the BibleDesktop/JSword folder.

While the installer has all of these in a folder name BD, that name is not at all special. It could just as well be /. This layout follows that of the SWORD cd.

External Links

You can find more about it here: JSword's home page

Java Documentation of all Classes, Interface and Methods of Jsword: JavaDoc

Walkthrough on how to setup the Jsword Code: Guide