org.crosswire.jsword.passage
Interface Passage

All Superinterfaces:
Cloneable, Comparable, Key, Serializable
All Known Implementing Classes:
AbstractPassage, BitwisePassage, DistinctPassage, PassageTally, RangedPassage, ReadOnlyPassage, RocketPassage, SynchronizedPassage

public interface Passage
extends Key, Serializable

A Passage is a specialized Collection of Verses. The additions are:

Passage no longer extends the Collection interface to avoid J2SE 1.1/1.2 portability problems, and because many of the things that a Passage does rely on consecutive Verses which are an alien concept to Collections. So users would have to use the Passage interface anyway.

Other arguments for and against.

The upshot of all this is that I am removing the Collections interface from Passage, but writing a PassageSet as a proxy.

I considered giving Passages names to allow for a CLI that could use named RangedPassages, however that is perhaps better left to another class.

Author:
Joe Walker [joe at eireneh dot com]
See Also:
for license details. The copyright to this program is held by it's authors.

Method Summary
 void add(VerseBase that)
          Add this Verse/VerseRange to this Passage
 void addPassageListener(PassageListener li)
          Event Listeners - Add Listener
 int booksInPassage()
          How many books are there in this Passage
 int chaptersInPassage(int book)
          How many chapters are there in a particular book in this Passage
 boolean contains(VerseBase that)
          Returns true if this collection contains all the specified Verse
 boolean containsAll(Passage that)
          Returns true if this Passage contains all of the verses in that Passage
 int countRanges(RestrictionType restrict)
          Like countVerses() that counts VerseRanges instead of Verses Returns the number of fragments in this collection.
 int countVerses()
          Returns the number of verses in this collection.
 String getOverview()
          A summary of the verses in this Passage For example "10 verses in 4 books"
 VerseRange getRangeAt(int offset, RestrictionType restrict)
          Get a specific VerseRange from this collection
 Verse getVerseAt(int offset)
          Get a specific Verse from this collection
 void optimizeReads()
          For preformance reasons we may well want to hint to the Passage that we have done editing it for now and that it is safe to cache certain values to speed up future reads.
 Iterator rangeIterator(RestrictionType restrict)
          Like verseElements() that iterates over VerseRanges instead of Verses.
 void readDescription(Reader in)
          To be compatible with humans we read/write ourselves to a file that a human can read and even edit.
 void remove(VerseBase that)
          Remove this Verse/VerseRange from this Passage
 void removePassageListener(PassageListener li)
          Event Listeners - Remove Listener
 Passage trimRanges(int count, RestrictionType restrict)
          Ensures that there are a maximum of count VerseRanges in this Passage.
 Passage trimVerses(int count)
          Ensures that there are a maximum of count Verses in this Passage.
 int versesInPassage(int book, int chapter)
          How many chapters are there in a particular book in this Passage Note that versesInPassage(ref, 0, 0) == ref.countVerses()
 void writeDescription(Writer out)
          To be compatible with humans we read/write ourselves to a file that a human can read and even edit.
 
Methods inherited from interface org.crosswire.jsword.passage.Key
addAll, blur, canHaveChildren, clear, clone, contains, get, getChildCount, getName, getOsisID, getOsisRef, getParent, indexOf, isEmpty, iterator, removeAll, retainAll
 
Methods inherited from interface java.lang.Comparable
compareTo
 

Method Detail

getOverview

String getOverview()
A summary of the verses in this Passage For example "10 verses in 4 books"

Returns:
a String containing an overview of the verses

countVerses

int countVerses()
Returns the number of verses in this collection. Like Collection.size() This does not mean the Passage needs to use Verses, just that it understands the concept.

Returns:
the number of Verses in this collection
See Also:
Verse

countRanges

int countRanges(RestrictionType restrict)
Like countVerses() that counts VerseRanges instead of Verses Returns the number of fragments in this collection. This does not mean the Passage needs to use VerseRanges, just that it understands the concept.

Parameters:
restrict - Do we break ranges at chapter/book boundries
Returns:
the number of VerseRanges in this collection
See Also:
VerseRange

trimVerses

Passage trimVerses(int count)
Ensures that there are a maximum of count Verses in this Passage. If there were more than count Verses then a new Passage is created containing the Verses from count+1 onwards. If there was not greater than count in the Passage, then the passage remains unchanged, and null is returned.

Parameters:
count - The maximum number of Verses to allow in this collection
Returns:
A new Passage conatining the remaining verses or null
See Also:
Verse

trimRanges

Passage trimRanges(int count,
                   RestrictionType restrict)
Ensures that there are a maximum of count VerseRanges in this Passage. If there were more than count VerseRanges then a new Passage is created containing the VerseRanges from count+1 onwards. If there was not greater than count in the Passage, then the passage remains unchanged, and null is returned.

Parameters:
count - The maximum number of VerseRanges to allow in this collection
restrict - Do we break ranges at chapter/book boundries
Returns:
A new Passage conatining the remaining verses or null
See Also:
VerseRange

booksInPassage

int booksInPassage()
How many books are there in this Passage

Returns:
The number of distinct books

chaptersInPassage

int chaptersInPassage(int book)
                      throws NoSuchVerseException
How many chapters are there in a particular book in this Passage

Parameters:
book - The book to check (0 for distinct chapters in all books)
Returns:
The number of distinct chapters
Throws:
NoSuchVerseException - if the book is invalid

versesInPassage

int versesInPassage(int book,
                    int chapter)
                    throws NoSuchVerseException
How many chapters are there in a particular book in this Passage Note that versesInPassage(ref, 0, 0) == ref.countVerses()

Parameters:
book - The book to check (0 for distinct chapters in all books)
chapter - The chapter to check (0 for distinct verses in all chapters)
Returns:
The number of distinct chapters
Throws:
NoSuchVerseException - if the book/chapter is invalid

getVerseAt

Verse getVerseAt(int offset)
                 throws ArrayIndexOutOfBoundsException
Get a specific Verse from this collection

Parameters:
offset - The verse offset (legal values are 0 to countVerses()-1)
Returns:
The Verse
Throws:
ArrayIndexOutOfBoundsException - If the offset is out of range

getRangeAt

VerseRange getRangeAt(int offset,
                      RestrictionType restrict)
                      throws ArrayIndexOutOfBoundsException
Get a specific VerseRange from this collection

Parameters:
offset - The verse range offset (legal values are 0 to countRanges()-1)
restrict - Do we break ranges at chapter/book boundries
Returns:
The Verse Range
Throws:
ArrayIndexOutOfBoundsException - If the offset is out of range

rangeIterator

Iterator rangeIterator(RestrictionType restrict)
Like verseElements() that iterates over VerseRanges instead of Verses. Exactly the same data will be traversed, however using rangeIterator() will usually give less iterations (and never more)

Parameters:
restrict - Do we break ranges over chapters
Returns:
A list enumerator

contains

boolean contains(VerseBase that)
Returns true if this collection contains all the specified Verse

Parameters:
that - Verse or VerseRange that may exist in this Passage
Returns:
true if this collection contains that

add

void add(VerseBase that)
Add this Verse/VerseRange to this Passage

Parameters:
that - The Verses to be removed from this Passage

remove

void remove(VerseBase that)
Remove this Verse/VerseRange from this Passage

Parameters:
that - The Verses to be removed from this Passage

containsAll

boolean containsAll(Passage that)
Returns true if this Passage contains all of the verses in that Passage

Parameters:
that - Passage to be checked for containment in this collection.
Returns:
true if this reference contains all of the Verses in that Passage

readDescription

void readDescription(Reader in)
                     throws IOException,
                            NoSuchVerseException
To be compatible with humans we read/write ourselves to a file that a human can read and even edit. OLB verse.lst integration is a good goal here.

Parameters:
in - The stream to read from
Throws:
IOException - If the file/network etc breaks
NoSuchVerseException - If the file was invalid

writeDescription

void writeDescription(Writer out)
                      throws IOException
To be compatible with humans we read/write ourselves to a file that a human can read and even edit. OLB verse.lst integration is a good goal here.

Parameters:
out - The stream to write to
Throws:
IOException - If the file/network etc breaks

optimizeReads

void optimizeReads()
For preformance reasons we may well want to hint to the Passage that we have done editing it for now and that it is safe to cache certain values to speed up future reads. Any action taken by this method will be undone simply by making a future edit, and the only loss in calling optimizeReads() is a loss of time if you then persist in writing to the Passage.


addPassageListener

void addPassageListener(PassageListener li)
Event Listeners - Add Listener

Parameters:
li - The listener to add

removePassageListener

void removePassageListener(PassageListener li)
Event Listeners - Remove Listener

Parameters:
li - The listener to remove

Copyright ยจ 2003-2005