# Package org.crosswire.jsword.passage

The core responsibility of the passage package is to store and collate information about the structure of the Bible - The most important classes are `Passage`, `PassageTally` and `Strongs`.

See: Description

- Interface Summary
  Interface | Description
  --- | ---
  Key | A Key is a Key that can contain other Keys.
  KeyFactory | A Factory for new Keys and KeyLists.
  KeyVisitor | An interface for components wanting to visit all the nodes in a Key tree.
  Passage | A Passage is a specialized Collection of Verses.
  PassageListener | A PassageListener gets told when the verses in a Passage have changed (added or removed).
  PreferredKey | For any time when a component wishes to express a preference for a Key.
  VerseKey<T extends VerseKey> | A VerseKey indicates that a Key has a Versification reference system.

- Class Summary
  Class | Description
  --- | ---
  AbstractKeyList | An implementation of some of the easier methods from Key.
  AbstractKeyList.NameVisitor | The `NameVisitor` constructs a readable representation of the Passage.
  AbstractKeyList.OsisIDVisitor | The `OsisRefVisitor` constructs a readable representation of the Passage, using OSIS names.
  AbstractKeyList.OsisRefVisitor | The `OsisRefVisitor` constructs a readable representation of the Passage, using OSIS names.
  AbstractPassage | This is a base class to help with some of the common implementation details of being a Passage.
  AbstractPassage.VerseRangeIterator | Skip over verses that are part of a range
  BitwisePassage | A Passage that is implemented using a BitSet - one for each verse.
  DefaultKeyList | A default implementation of Key.
  DefaultKeyVisitor | A default implementation of KeyVisitor that does nothing, for use in inheritance where you want to save space by not overriding all methods.
  DefaultLeafKeyList | A simple default implementation of the Key interface.
  DistinctPassage | A Passage that is implemented using a TreeSet of Verses.
  KeyIterator | This KeyIterator performs a depth first iteration over the subkeys in the key.
  KeyIterator.Locator | A helper class that remembers where we've been and where we are.
  KeyUtil | .
  OsisParser | The Osis ID parser simply assumes 1-3 parts divided by '.'.
  PassageEvent | Defines an event that encapsulates changes to a Passage.
  PassageKeyFactory | The PassageKeyFactory constructs Passages of the default Passage type.
  PassageTally | Similar to a Passage, but that stores a ranking for each of the Verses that it contains.
  PassageTally.OrderedVerseIterator | Iterate over the Verses in order of their rank in the tally
  PassageTally.OrderedVerseRangeIterator | Iterate over the Ranges in order of their rank in the tally
  PassageTally.TalliedVerse | Hack to make this work with J2SE 1.1 as well as J2SE 1.2 This compared 2 Integers
  PassageTally.TalliedVerseRange | Hack to make this work with JDK1.1 as well as JDK1.2 This compared 2 Integers
  PassageUtil | A Utility class containing various static methods.
  RangedPassage | A Passage that is implemented using a TreeSet of VerseRanges.
  RangedPassage.VerseIterator | This class is here to prevent users of RangedPassage.iterator() from altering the underlying store and getting us out of sync.
  RangedPassage.VerseRangeIterator | Loop over the VerseRanges and check that they do not require digging into
  ReadOnlyKeyList | A read-only wrapper around any writable implementation of Key.
  ReadOnlyPassage | This is a simple proxy to a real Passage object that denies all attempts to write to it.
  RocketPassage | A RocketPassage is a bit and heavy implementation of Passage that goes fairly quickly once let of the leash.
  SetKeyList | A Key that uses a Set of Keys as it's store of data.
  SynchronizedPassage | This is a simple proxy to a real Passage object that makes all accesses synchronized.
  TreeKey | A Key that knows where the data is in the real file.
  Verse | A Verse is a pointer to a single verse.
  VerseFactory | A factory to create a Verse from user input.
  VerseRange | A VerseRange is one step between a Verse and a Passage - it is a Verse plus a verseCount.
  VerseRange.VerseIterator | Iterate over the Verses in the VerseRange
  VerseRangeFactory | A factory that creates VerseRanges from user input.

- Enum Summary
  Enum | Description
  --- | ---
  AccuracyType | Types of Accuracy for verse references.
  PassageEvent.EventType | Indicates what kind of change happened to a Passage.
  PassageListType | Types of Passage Lists.
  PassageTally.Order | Indicates how this PassageTally is to order it's Verses.
  PassageType | Types of Passage optimizations.
  RestrictionType | Types of Passage Blurring Restrictions.

- Exception Summary
  Exception | Description
  --- | ---
  NoSuchKeyException | When something tries to use a key that we don't understand.
  NoSuchVerseException | When something tries to use a verse that we don't understand.

## Package org.crosswire.jsword.passage Description

The core responsibility of the passage package is to store and collate information about the structure of the Bible - The most important classes are `Passage`, `PassageTally` and `Strongs`. A `Passage` stores lists of verses, for example "Gen 1:1-5, 10". `PassageTally` is similar but stores verses ordered by a tally against each verse. A `Strongs` represents a Greek or Hebrew word as categorized by James Strong.

# Passage

A `Passage` is modeled after the JDK 2.0 `Collections` interface - so all the usual `add()`, `remove()` type actions are available. (A `PassageCollection` proxy class is available in order to treat a `Passage` exactly like a `Collection`)

In addition to this a `Passage` will do:

- List blurring (for find X within 5 verses of Y type requests)
- List change notification, so you can register to receive notification of changes to a `Passage`. This will be of most use with a multi-threaded search engine.
- An understanding of VerseRanges (see below) for range counting and iteration (in addition to Verse counting etc)

The `Passage` interface uses `Verse` and `VerseRange` in many of its methods. A `Verse` is obvious - a single Bible verse e.g. "Exo 2:4", or "Jude 4". A `VerseRange` has a start Verse and an end Verse e.g. "Exo 3:5-7", or "Mat 25:1-Mar 2:4".

`Verse` and `VerseRange` have a superclass interface of `VerseBase`, and this interface is collected and sorted by `Passage` .So an example `Passage` is "Exo 2:4, 3:5-7, Mat 25:1-Mar 2:4, Jude 4".

The `Passage` interface is implemented by 3 concrete classes - `DistinctPassage` is a simple sorted collection of `Verse`s, `RangedPassage` is a sorted collection of `VerseRange`s, and `BitwisePassage` uses an array - essentially `boolean[31104]` to specify whether a verse is a member of the `Passage`. Obviously each of these implementations has different strengths, which the user should not need to be bothered with. So the `PassageFactory` class is responsible for creating `Passages` of a suitable type.

## PassageTally

The `PassageTally` class is-a to `Passage` however it's job is to store a rank to a `Verse`. This is for a best-match type application - "find the verse that best matches these words". It is the intent to marry this with a Thesarus interface, because a gripe with the OLB is that I search for "God & loves & world" and expect to find John 3:16, but the search fails because John 3:16 uses the word "loved" and not "loves".

The final aim is a fuzzy matching scheme to I can search for "God loves us and gave Jesus to save us" and correctly be told John 3:16.

## Strongs

The `Strongs` class represents a Hebrew or Greek word, or a parsing number indicating the way the verse is aimed.

## Other Stuff

This package has a `SelfTest` class that is designed to stress every line of code in the rest of the package to make it bug-free. Otherwise this package is largely complete. I still need to inspect [Bitwise|Distinct|Ranged]Passage and PassageTally.