[jsword-devel] SwordBookMetaData

[Joe Walker]

DM Smith wrote:

> It really was not a biggie, but I wanted to get rid of the trailing 
> comma in the tree of installed and installable books in the books dialog.
>
> I found that it is a simple change to getFullName().
>
> But one thing got me looking at another, and that, yet another.
>
> First thing I noticed was that the listing of the BookMetaData when a 
> book is selected seems to be randomly ordered. I traced this down to 
> the use of Properties, which is unordered. So I found that in Java 1.4 
> there is a new Map called LinkedHashMap that will provide its keys or 
> values in insertion order. If this were used to maintain the 
> properties then they could be listed as they were in the file.

Sounds sensible. Would TreeSet (alpha order) also make sense?

> I found that there is one other implementation of BookMetaData, called 
> DefaultBookMetaData. I examined the use of the Properties object in it 
> and found that it has a problem in the various set routines. It tries 
> to "put" the value in the properties as objects and not strings, which 
> is stongly discouraged in the documentation. 

It used to be a Map not too long ago, and we even used it to store 
objects. I guess I changed it by just altering the declaration. Since 
Properties inherits Map, I guess that will have been superficially easy!

> And the object stored against a key is sometimes a string and 
> sometimes an other kind of object. The access of the value would be 
> suspect with that. If it were expected to be a string when it is not 
> or is expected to be a Date when it is a string may cause a runtime 
> error. In tracing the use of DefaultBookMetaData, it seemed to be in 
> classes intended for future use.
>
> In looking at how the BookMetaData properties were used I could not 
> find a real use beyond displaying the contents. Every KEY_* stored in 
> it was double stored in a member variable. My guess is that the 
> various KEY_* are present for a future use.

The issue is that BookMetaData needs to store a number of properties 
that are vital for it's normal operation, like the name of the Book for 
example. In addition to the mandatory properties (which are given direct 
accessors) there are other properties like who created it and so on that 
are useful to remember if you know, but that not everyone provides. It 
is natural to store optional properties in a Properties object.
It would be a bit of a pain to someone wanting to display information 
about a book it when the called getProperties() to get the optional 
stuff, if they then had to read all the mandatory properties too. So we 
store all properties in the Properties file, and give the mandatory 
properties defined keys.

> I also found the following about SwordBookMetaData *.conf files:
> The first line is blank. Is there any reason to store that?

I guess not. I'm not sure why we do. The code has some 'heritage' to it 
here. (Read: it's been booted around by everyone)

> The second line is of the form [KJV]. This looks like a MS windows 
> style section identifier. Is this really needed to be kept? I think 
> that if we are trying to preserve the output, then yes.
> Some keys are repeated and are simply concatenated together in the 
> properties. Should these be separated?
> Some lines look like continuation lines. (See Webster's Revised 
> Unabridged Dictionary of the English Language.) 

I thought when I first read this that you wanted me to look up 
"continuation line" in a dictionary!

> The key line ends with a \ which seems to indicate that the next line 
> should be concatenated, if it is not of the form key=value.


I've always taken the point of view that we just have to live with how 
the sword *.conf files are. There are several projects that read them, 
and many thousands of people that have downloaded them.

There are multi valued keys - C++ Sword uses STL, which includes a 
multi-valued map as standard. Java doesn't so the format is less natural 
for us.
In SwordMetaData there are 2 stores of the data, 'table' which is a map 
of lists, and Properties which is a map of concatenated strings.

Hope that helps.

Joe.