[jsword-devel] Sidecar module confs

[DM Smith]

Thought that I'd reply here rather than on the github thread which many don't get. I haven't looked at the implementation there yet. Below is a description of what we currently have and a few thoughts on how to get from here to there.

Current Design:
The BookMetaData is an abstraction that exposes those properties of a module that are required/useful for a Book to work. The remaining are accessible through a get/put property API. SwordBookMetaData exists to provide a concrete implementation that ties the SWORD module conf to the BookMetaData interface.

SBMD started out as a parser for INI-like files that stored it's data in a map like Properties except that some keys could be repeated.

There were a couple of web pages that defined what was allowed in a SWORD config file. These have been consolidated into the CrossWire Wiki. We made the parser a validating parser. To do this we had to know the following:
	The allowed keys.
	The nature of the value for each key:
		Single line or multi-line.
		Type of markup allowed for the value: plain text, RTF or HTML.
		Type of value: text, numeric, date, pick from a fixed list.
		Default value if key is not present in the config file.
Each allowed key maps to a ConfigEntryType that defines these characteristics.
Each entry is a ConfigEntry having a ConfigEntryType and a value. The entire config file is held in ConfigEntryTable, which is an internal implementation detail of a SwordBookMetaData.

One critical aspect of the ConfigEntryTable is that it maintains two orders of the contents of the conf: original and organized. The original order is used when a property is added or changed. Added ones go to the bottom of the file in the order that they are added. Changed entries stay in the same location. The organized order is used to create OSIS view that is presented to an end user. IIRC, currently we add or change Font and Cipher. Font may have moved to its own file.

The reason we went with validation was that early on we didn't support all types of modules and there were quite a few config files that had errors in them. Some of these errors were benign, but some were in the "control" meta data. The IBT and Xiphos modules have "problems".

The reading of the conf is complicated by history. There are two parts to this. The location of the conf files has changed over time. There is migration code that migrates from the old location to the new location. For a while now, we've used a well defined location for Windows. The Xiphos folks decided to use a different location. We need to have migration code to go from the location that we are using now to the location that xiphos uses. But other than that the migration code is past its usefulness.

The other part of the complication is that the conf file exists in one of three forms:
mods.d.tar.gz, individual conf files and a unified conf file. (The latter was never implemented in JSword, but is defined in SWORD. JSword still has some catchup to do.)

mods.d.tar.gz is not unpacked but rather when a conf is desired, the tar entry is opened as a file stream. The reason we don't unpack it is that we don't have to manage add/modify/delete of the files as modules are added, changed, removed or renamed. These modules are not local. Those parts of the SBMD that refer to the installed module are not filled in.

The individual conf is read as a file and represents a module that actually is local. Recently we fixed a bug where a conf of a recently installed module was not updated to be an installed module conf.

One of the problems with the current design of SBMD is that we don't separate the parsing from the object. If we did then we could create empty SBMD.

As an aside, we have a PropertyMap class in JSword that we use as a replacement for Properties. This is a Map <String, String> class that maintains input order. Besides load and store, the other feature is that is taken from the Properties class is that there is a constructor PropertyMap(PropertyMap defaults), which implements what we are trying to accomplish with sidecar BookMetaData. If the property does not exist, the default is returned. In our case defaults is the conf as gotten from the module repository. It does not change.

In PropertyMap and Properties, the load and save routines work on open streams. In our case, I think it would be good if BookMetaData knew the location of the file(s) that it needs to work with. As an example see: http://www.crosswire.org/svn/jsword/trunk/bibledesktop/src/main/java/org/crosswire/common/swing/FontStore.java

The problem I see with having more than 2 chained sets of properties, where the defaults is not changed, is that one needs to know where the properties belong. I presume that is what "level" is about.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: smime.p7s
Type: application/pkcs7-signature
Size: 4145 bytes
Desc: not available
URL: <http://www.crosswire.org/pipermail/jsword-devel/attachments/20140426/60c1347e/attachment.p7s>