[jsword-devel] A few minor API changes

[DM Smith]

On Jul 6, 2013, at 6:47 AM, Chris Burrell <chris at burrell.me.uk> wrote:

> Hi all
> 
> I'm realising I'm doing quite a lot of casts from Key in particular to Passages, etc.
> 
> I was wondering if we could change some of our interfaces to be slightly more specific.
> 
> For example, PassageKeyFactory.instance().getKey() could return a Passage instead of a Key.
> 
> A Passage Iterator could return Verses
> 
> A range iterator could return ranges.
> 
> etc.
> 
> There are probably a few more...
> 
> Also, a more fundamental change, I was wondering if there is a reason for keeping the Verse hierarchy apart from the Passage hierarchy. For example, a Passage of size 1 is essentially a Passage (not suggesting we make all these changes now), but keen to understand why we have the difference.. 

Casting is typically a sign of an OO design flaw.

JSword was moving toward the unification of Keys from an API perspective, but didn't quite get there.

A Key serves multiple purposes:
A single reference. This might be a biblical reference, a dictionary term, ...
A list of references.
A tree of references.

A Verse is highly specialized in that it refers to a single verse and optimized for verse operations. The core optimization is the conversion of a Verse to and from an ordinal value that represents its relative position in a versification of the Bible.

A VerseRange is represented by a starting verse and a count. A VerseRange can have a count of 1, in which case it represents a single verse. One can iterate over a VerseRange to get Verses.

A Passage is a collection of one or more verse ranges. By and large a Passage not represented as a list of VerseRange objects, but by an optimized representation as such. The most common is a very large, fast bitmap. There are a whole variety of Passage types that are optimized for different needs. Iteration over VerseRanges and Verses is provided.

So looking at this, the following cast operations make sense:
Cast a Verse to a VerseRange.
Cast a Verse to a Passage.
Cast a VerseRange to a Passage.

The following might make sense:
Cast a VerseRange to a Verse, resulting in the first Verse of the VerseRange.
Cast a Passage to a VerseRange, resulting in the first VerseRange of the Passage.
Cast a Passage to a Verse, resulting in the first Verse of the Passage.

From a frontend persepective, the most important operations regarding a Key are:
Convert a Key to an ordered list of Keys (i.e. provide an iterator yielding the unit of module lookup.)
Do a module lookup.
Render the content of the key to the display.
Get the primary keys from a module (e.g. dictionary, genbook) or know what they are (verses).

In this regard there is no need to know anything about the Key. So the Passage hierarchy derives from Key.

But in creating significant study tools, knowing that a Key is a Verse (VerseRange or Passage) is very useful.

So, yes, it would be goodness to do more unification. To do so, will be to move optimization control from the frontend into JSword.

In Him,
	DM
-------------- 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/20130706/373a93fc/attachment.p7s>