Passage

Overview

Package

Class

Use

Deprecated

Index

Home >> All >> org >> crosswire >> bible >> [ passage overview ]

PREV CLASS NEXT CLASS

SUMMARY:

JAVADOC |

Sourc code of org.crosswire.bible.passage.Passage

SOURCE |

Download org.crosswire.bible.passage.Passage

DOWNLOAD | NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.crosswire.bible.passage
Interface Passage

All Superinterfaces:: java.lang.Cloneable, PassageConstants, java.io.Serializable

All Known Implementing Classes:: AbstractPassage, ReadOnlyPassage, SynchronizedPassage

public interface Passage
extends java.io.Serializable, java.lang.Cloneable, PassageConstants

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

List blurring
Range Counting and iteration (in addition to Verse counting etc)
List change notification, so you can register to update yourself, and this goes hand in hand with a added thread-safe contract.
getName() to be more VerseBase like.
Human readable serialization. So we can read and write to and from OLB style Passage files.

Passage no longer extends the Collection interface to avoid JDK 1.1/2.0 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 generic version will postpone some type errors to runtime. Is this a huge problem? Are there many syntax errors that would be lost? Probably not.
The specific version would stop enhancements like add("Gen 1:1"); (But this is just syntactical sugar anyway).
The specific version allows funcionality by is-a as well as has-a. But a Passage is fundamentally different so this is not that much use.
At the end of the day I expect people to use getName() instead of toString() and blur(), both of which are Passage things not Collection things. So the general use of these classes is via a Passage interface not a Collections one.
Note that the implementations of Passage could not adhere strictly to the Collections interface in returning false from add(), remove() etc, to specify if the Collection was changed. Given ranges and the like this can get very time consuming and complex.

The upshot of all this is that I am removing the Collections interface from Passage, but writing a PassageCollection 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.

Distribution Licence:
Project B is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License, version 2 as published by the Free Software Foundation.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
The License is available on the internet here, by writing to Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA, Or locally at the Licence link below.
The copyright to this program is held by it's authors.

Version:: $Id:$

Field Summary

Fields inherited from interface org.crosswire.bible.passage.PassageConstants

ACCURACY_BOOK_CHAPTER, ACCURACY_BOOK_ONLY, ACCURACY_BOOK_VERSE, ACCURACY_CHAPTER_VERSE, ACCURACY_NONE, ACCURACY_VERSE_ONLY, CASE_LOWER, CASE_MIXED, CASE_SENTANCE, CASE_UPPER, CASES, RANGE_ALLOWED_DELIMS, RANGE_PREF_DELIM, REF_ALLOWED_DELIMS, REF_PREF_DELIM, RESTRICT_BOOK, RESTRICT_CHAPTER, RESTRICT_NONE, RESTRICTIONS, VERSE_ALLOWED_DELIMS, VERSE_END_MARK1, VERSE_END_MARK2, VERSE_NUMERIC_BOOK, VERSE_PREF_DELIM1, VERSE_PREF_DELIM2

Method Summary

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

void addAll(Passage that)
          Adds all that Passage's verses to this Passage

void addPassageListener(PassageListener li)
          Event Listeners - Add Listener

void blur(int verses, int restrict)
          Widen the range of the verses in this list.

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

void clear()
          Removes all the verses is this Passage

java.lang.Object clone()
          I'm not sure why we have to keep on redeclaring this.

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()
          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.

java.lang.String getName()
          A Human readable version of the verse list.

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

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

VerseRange getVerseRangeAt(int offset)
          Get a specific VerseRange from this collection

boolean isEmpty()
          Does this Passage have 0 members

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.

java.util.Iterator rangeIterator()
          Like verseElements() that iterates over VerseRanges instead of Verses.

void readDescription(java.io.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 removeAll(Passage that)
          Removes all this collection's elements that are also contained in the specified collection.

void removePassageListener(PassageListener li)
          Event Listeners - Remove Listener

void retainAll(Passage that)
          Removes all the Verses from this reference that are not in that reference specified collection.

Passage trimRanges(int count)
          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.

java.util.Iterator verseIterator()
          Iterate over the Verses in this collection

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(java.io.Writer out)
          To be compatible with humans we read/write ourselves to a file that a human can read and even edit.

Method Detail

getName

public java.lang.String getName()

A Human readable version of the verse list. Uses short books names, and the shortest sensible rendering eg "Mat 3:1-4" and "Mar 1:1, 3, 5" and "3Jo, Jude"

getOverview

public java.lang.String getOverview()

A summary of the verses in this Passage For example "10 verses in 4 books"

isEmpty

public boolean isEmpty()

Does this Passage have 0 members

countVerses

public 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.

countRanges

public int countRanges()

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.

trimVerses

public 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.

trimRanges

public Passage trimRanges(int count)

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.

booksInPassage

public int booksInPassage()

How many books are there in this Passage

chaptersInPassage

public int chaptersInPassage(int book)
                      throws NoSuchVerseException

How many chapters are there in a particular book in this Passage

versesInPassage

public 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()

getVerseAt

public Verse getVerseAt(int offset)
                 throws java.lang.ArrayIndexOutOfBoundsException

Get a specific Verse from this collection

getVerseRangeAt

public VerseRange getVerseRangeAt(int offset)
                           throws java.lang.ArrayIndexOutOfBoundsException

Get a specific VerseRange from this collection

verseIterator

public java.util.Iterator verseIterator()

Iterate over the Verses in this collection

rangeIterator

public java.util.Iterator rangeIterator()

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)

contains

public boolean contains(VerseBase that)

Returns true if this collection contains all the specified Verse

add

public void add(VerseBase that)

Add this Verse/VerseRange to this Passage

remove

public void remove(VerseBase that)

Remove this Verse/VerseRange from this Passage

containsAll

public boolean containsAll(Passage that)

Returns true if this Passage contains all of the verses in that Passage

addAll

public void addAll(Passage that)

Adds all that Passage's verses to this Passage

removeAll

public void removeAll(Passage that)

Removes all this collection's elements that are also contained in the specified collection.

retainAll

public void retainAll(Passage that)

Removes all the Verses from this reference that are not in that reference specified collection.

clear

public void clear()

Removes all the verses is this Passage

blur

public void blur(int verses,
                 int restrict)

Widen the range of the verses in this list. This is primarily for "find x within n verses of y" type applications.

readDescription

public void readDescription(java.io.Reader in)
                     throws java.io.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.

writeDescription

public void writeDescription(java.io.Writer out)
                      throws java.io.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.

optimizeReads

public 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

public void addPassageListener(PassageListener li)

Event Listeners - Add Listener

removePassageListener

public void removePassageListener(PassageListener li)

Event Listeners - Remove Listener

clone

public java.lang.Object clone()
                       throws java.lang.CloneNotSupportedException

I'm not sure why we have to keep on redeclaring this. But If I don't Then I get accused of attempting to reduce access level of clone(); Maybe this is a bug in MS JVM. It has been behaving strangely here.

Overview

Package

Class

Use

Deprecated

Index

Home >> All >> org >> crosswire >> bible >> [ passage overview ]

PREV CLASS NEXT CLASS

SUMMARY:

JAVADOC |

SOURCE |

DOWNLOAD | NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

Method Summary
`void`	`add(VerseBase that)` Add this Verse/VerseRange to this Passage
`void`	`addAll(Passage that)` Adds all that Passage's verses to this Passage
`void`	`addPassageListener(PassageListener li)` Event Listeners - Add Listener
`void`	`blur(int verses, int restrict)` Widen the range of the verses in this list.
`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
`void`	`clear()` Removes all the verses is this Passage
`java.lang.Object`	`clone()` I'm not sure why we have to keep on redeclaring this.
`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()` 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.
`java.lang.String`	`getName()` A Human readable version of the verse list.
`java.lang.String`	`getOverview()` A summary of the verses in this Passage For example "10 verses in 4 books"
`Verse`	`getVerseAt(int offset)` Get a specific Verse from this collection
`VerseRange`	`getVerseRangeAt(int offset)` Get a specific VerseRange from this collection
`boolean`	`isEmpty()` Does this Passage have 0 members
`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.
`java.util.Iterator`	`rangeIterator()` Like verseElements() that iterates over VerseRanges instead of Verses.
`void`	`readDescription(java.io.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`	`removeAll(Passage that)` Removes all this collection's elements that are also contained in the specified collection.
`void`	`removePassageListener(PassageListener li)` Event Listeners - Remove Listener
`void`	`retainAll(Passage that)` Removes all the Verses from this reference that are not in that reference specified collection.
`Passage`	`trimRanges(int count)` 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.
`java.util.Iterator`	`verseIterator()` Iterate over the Verses in this collection
`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(java.io.Writer out)` To be compatible with humans we read/write ourselves to a file that a human can read and even edit.

org.crosswire.bible.passage Interface Passage

getName

getOverview

isEmpty

countVerses

countRanges

trimVerses

trimRanges

booksInPassage

chaptersInPassage

versesInPassage

getVerseAt

getVerseRangeAt

verseIterator

rangeIterator

contains

add

remove

containsAll

addAll

removeAll

retainAll

clear

blur

readDescription

writeDescription

optimizeReads

addPassageListener

removePassageListener

clone

org.crosswire.bible.passage
Interface Passage