org.crosswire.jsword.passage
Class Verse

java.lang.Object
  org.crosswire.jsword.passage.Verse

All Implemented Interfaces:

Serializable, Cloneable, Comparable<Key>, Iterable<Key>, Key

public final class Verse
extends Object
implements Key

A Verse is a pointer to a single verse. Externally its unique identifier is a String of the form "Gen 1:1" Internally we use ( book, chapter, verse )

A Verse is designed to be immutable. This is a necessary from a collections point of view. A Verse should always be valid, although some versions may not return any text for verses that they consider to be mis-translated in some way.

Author:

Joe Walker [joe at eireneh dot com]

See Also:

for license details.
The copyright to this program is held by it's authors., Serialized Form

Field Summary

private BibleBook	book The book of the Bible.
private int	chapter The chapter number
static Verse	DEFAULT The default verse
private String	originalName The original string for picky users
private Key	parent The parent key.
(package private) static long	serialVersionUID To make serialization work across new versions
private static NumberShaper	shaper Allow the conversion to and from other number representations.
private int	verse The verse number
static String	VERSE_OSIS_DELIM What characters should we use to separate parts of an OSIS verse reference
static String	VERSE_PREF_DELIM1 What characters should we use to separate the book from the chapter
static String	VERSE_PREF_DELIM2 What characters should we use to separate the chapter from the verse

Constructor Summary

Verse()
The default Verse is Genesis 1:1.

Verse(BibleBook book, int chapter, int verse)
Create a Verse from book, chapter and verse numbers, throwing up if the specified Verse does not exist.

Verse(BibleBook book, int chapter, int verse, boolean patch_up)
Create a Verse from book, chapter and verse numbers, patching up if the specified verse does not exist.

Verse(int ordinal)
Set a Verse using a Verse Ordinal number - WARNING Do not use this method unless you really know the dangers of doing so.

Verse(String original, BibleBook book, int chapter, int verse)
Create a Verse from book, chapter and verse numbers, throwing up if the specified Verse does not exist.

Method Summary

Verse	add(int n) Deprecated.
void	addAll(Key key) Adds the specified element to this set if it is not already present.
boolean	adjacentTo(Verse that) Deprecated.
void	blur(int by, RestrictionType restrict) Widen the range of the verses/keys in this list.
boolean	canHaveChildren() Returns false if the receiver is a leaf node and can not have children.
void	clear() Removes all of the elements from this set (optional operation).
Verse	clone() This needs to be declared here so that it is visible as a method on a derived Key.
int	compareTo(Key obj)
boolean	contains(Key key) Returns true if this set contains the specified element.
private String	doGetName(Verse verseBase) Deprecated. do not use
boolean	equals(Object obj) This needs to be declared here so that it is visible as a method on a derived Key.
Key	get(int index) Gets a key from a specific point in this list of children.
BibleBook	getBook() Return the book that we refer to
int	getCardinality() Returns the number of elements in this set (its cardinality).
int	getChapter() Return the chapter that we refer to
int	getChildCount() Returns the number of children that this node has.
String	getName() A Human readable version of the Key.
String	getName(Key base) Translate the Key into a human readable string, with the assumption that the specified Key has just been output, so if we are in the same region, we do not need to display the region name, and so on.
int	getOrdinal() Deprecated. do not use
String	getOsisID() The OSIS defined id specification for this Key.
String	getOsisRef() The OSIS defined reference specification for this Key.
Key	getParent() All keys have parents unless they are the root of a Key.
String	getRootName() A Human readable version of the Key's top level name.
int	getVerse() Return the verse that we refer to
int	hashCode() This needs to be declared here so that it is visible as a method on a derived Key.
int	indexOf(Key that) Reverse a Key into the position the key holds in the list of children
boolean	isEmpty() Does this Key have 0 members
boolean	isEndOfBook() Deprecated.
boolean	isEndOfChapter() Deprecated.
boolean	isSameBook(Verse that) Deprecated.
boolean	isSameChapter(Verse that) Deprecated.
boolean	isStartOfBook() Deprecated.
boolean	isStartOfChapter() Deprecated.
Iterator<Key>	iterator()
static Verse	max(Verse a, Verse b) Deprecated. do not use
static Verse	min(Verse a, Verse b) Deprecated. do not use
protected static int	parseInt(String text) This is simply a convenience function to wrap Integer.parseInt() and give us a reasonable exception on failure.
private void	readObject(ObjectInputStream in) Write out the object to the given ObjectOutputStream
void	removeAll(Key key) Removes the specified elements from this set if it is present.
void	retainAll(Key key) Removes all but the specified element from this set.
private void	set(BibleBook book, int chapter, int verse) Verify and set the references.
private void	set(int ordinal) Deprecated. do not use
private void	setAndPatch(BibleBook book, int chapter, int verse) Deprecated. do not use
void	setParent(Key parent) Set a parent Key.
Verse	subtract(int n) Deprecated.
int	subtract(Verse start) Deprecated.
String	toString()
Verse[]	toVerseArray() Create an array of Verses
private void	writeObject(ObjectOutputStream out) Write out the object to the given ObjectOutputStream

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

serialVersionUID

static final long serialVersionUID

To make serialization work across new versions

See Also:

Constant Field Values

VERSE_OSIS_DELIM

public static final String VERSE_OSIS_DELIM

What characters should we use to separate parts of an OSIS verse reference

See Also:

Constant Field Values

VERSE_PREF_DELIM1

public static final String VERSE_PREF_DELIM1

What characters should we use to separate the book from the chapter

See Also:

Constant Field Values

VERSE_PREF_DELIM2

public static final String VERSE_PREF_DELIM2

What characters should we use to separate the chapter from the verse

See Also:

Constant Field Values

DEFAULT

public static final Verse DEFAULT

The default verse

shaper

private static NumberShaper shaper

Allow the conversion to and from other number representations.

parent

private transient Key parent

The parent key. See the key interface for more information. NOTE(joe): These keys are not serialized, should we?

See Also:

Key

book

private transient BibleBook book

The book of the Bible.

chapter

private transient int chapter

The chapter number

verse

private transient int verse

The verse number

originalName

private transient String originalName

The original string for picky users

Constructor Detail

Verse

public Verse()

The default Verse is Genesis 1:1. I didn't want to provide this constructor however, you are supposed to provide a default ctor for all beans. For this reason I suggest you don't use it.

Verse

Verse(String original,
      BibleBook book,
      int chapter,
      int verse)

Create a Verse from book, chapter and verse numbers, throwing up if the specified Verse does not exist. This constructor is deliberately package protected so that is used only by VerseFactory.

Parameters:

original - The original verse reference

book - The book number (Genesis = 1)

chapter - The chapter number

verse - The verse number

Verse

public Verse(BibleBook book,
             int chapter,
             int verse)

Create a Verse from book, chapter and verse numbers, throwing up if the specified Verse does not exist.

Parameters:

book - The book number (Genesis = 1)

chapter - The chapter number

verse - The verse number

Verse

public Verse(BibleBook book,
             int chapter,
             int verse,
             boolean patch_up)

Create a Verse from book, chapter and verse numbers, patching up if the specified verse does not exist.

The actual value of the boolean is ignored. However for future proofing you should only use 'true'. Do not use patch_up=false, use Verse(int, int, int) This so that we can declare this constructor to not throw an exception. Is there a better way of doing this?

Parameters:

book - The book number (Genesis = 1)

chapter - The chapter number

verse - The verse number

patch_up - True to trigger reference fixing

Verse

public Verse(int ordinal)

Set a Verse using a Verse Ordinal number - WARNING Do not use this method unless you really know the dangers of doing so. Ordinals are not always going to be the same. So you should use a Verse or an int[3] in preference to an int ordinal whenever possible. Ordinal numbers are 1 based and not 0 based.

Parameters:

ordinal - The verse id

Method Detail

toString

public String toString()

Overrides:

toString in class Object

getName

public String getName()

Description copied from interface: Key

A Human readable version of the Key. For Biblical passages this uses short books names, and the shortest sensible rendering, for example "Mat 3:1-4" and "Mar 1:1, 3, 5" and "3Jo, Jude"

Specified by:

getName in interface Key

Returns:

a String containing a description of the Key

getName

public String getName(Key base)

Description copied from interface: Key

Translate the Key into a human readable string, with the assumption that the specified Key has just been output, so if we are in the same region, we do not need to display the region name, and so on.

Specified by:

getName in interface Key

Parameters:

base - The key to use to cut down unnecessary output.

Returns:

The string representation

getRootName

public String getRootName()

Description copied from interface: Key

A Human readable version of the Key's top level name. For Biblical passages this uses short books names. For a dictionary it might return A-Z.

Specified by:

getRootName in interface Key

Returns:

a String containing a description of the Key

getOsisRef

public String getOsisRef()

Description copied from interface: Key

The OSIS defined reference specification for this Key. When the key is a single element, it is an OSIS book name with '.' separating the parts. When the key is multiple elements, it uses a range notation. Note, this will create a comma separated list of ranges, which is improper OSIS.

Specified by:

getOsisRef in interface Key

Returns:

a String containing the OSIS description of the verses

getOsisID

public String getOsisID()

Description copied from interface: Key

The OSIS defined id specification for this Key. When the key is a single element, it is an OSIS book name with '.' separating the parts. When the key is multiple elements, it uses a space to separate each.

Specified by:

getOsisID in interface Key

Returns:

a String containing the OSIS description of the verses

clone

public Verse clone()

Description copied from interface: Key

This needs to be declared here so that it is visible as a method on a derived Key.

Specified by:

clone in interface Key

Overrides:

clone in class Object

Returns:

A complete copy of ourselves

equals

public boolean equals(Object obj)

Description copied from interface: Key

This needs to be declared here so that it is visible as a method on a derived Key.

Specified by:

equals in interface Key

Overrides:

equals in class Object

Returns:

true if equal

hashCode

public int hashCode()

Description copied from interface: Key

This needs to be declared here so that it is visible as a method on a derived Key.

Specified by:

hashCode in interface Key

Overrides:

hashCode in class Object

Returns:

the hashcode

compareTo

public int compareTo(Key obj)

Specified by:

compareTo in interface Comparable<Key>

adjacentTo

@Deprecated
public boolean adjacentTo(Verse that)

Deprecated.

Is this verse adjacent to another verse

Parameters:

that - The thing to compare against

Returns:

1 means he is earlier than me, -1 means he is later ...

subtract

@Deprecated
public int subtract(Verse start)

Deprecated.

How many verses are there in between the 2 Verses. The answer is -ve if start is bigger than this (the end). The answer is inclusive of start and exclusive of this, so that gen12.subtract(gen11) == 1

Parameters:

start - The Verse to compare this to

Returns:

The count of verses between this and that.

subtract

@Deprecated
public Verse subtract(int n)

Deprecated.

Get the verse n down from here this Verse.

Parameters:

n - The number to count down by

Returns:

The new Verse

add

@Deprecated
public Verse add(int n)

Deprecated.

Get the verse that is a few verses on from the one we've got.

Parameters:

n - the number of verses later than the one we're one

Returns:

The new verse

getBook

public BibleBook getBook()

Return the book that we refer to

Returns:

The book of the Bible

getChapter

public int getChapter()

Return the chapter that we refer to

Returns:

The chapter number

getVerse

public int getVerse()

Return the verse that we refer to

Returns:

The verse number

isStartOfChapter

@Deprecated
public boolean isStartOfChapter()

Deprecated.

Is this verse the first in a chapter

Returns:

true or false ...

isEndOfChapter

@Deprecated
public boolean isEndOfChapter()

Deprecated.

Is this verse the first in a chapter

Returns:

true or false ...

isStartOfBook

@Deprecated
public boolean isStartOfBook()

Deprecated.

Is this verse the first in a chapter

Returns:

true or false ...

isEndOfBook

@Deprecated
public boolean isEndOfBook()

Deprecated.

Is this verse the first in a chapter

Returns:

true or false ...

isSameChapter

@Deprecated
public boolean isSameChapter(Verse that)

Deprecated.

Is this verse in the same chapter as that one

Parameters:

that - The verse to compare to

Returns:

true or false ...

isSameBook

@Deprecated
public boolean isSameBook(Verse that)

Deprecated.

Is this verse in the same book as that one

Parameters:

that - The verse to compare to

Returns:

true or false ...

getOrdinal

@Deprecated
public int getOrdinal()

Deprecated. do not use

Return the verse id that we refer to, where Gen 1:1 = 1, and Rev 22:21 = 31104

Returns:

The verse number

max

@Deprecated
public static Verse max(Verse a,
                                   Verse b)

Deprecated. do not use

Return the bigger of the 2 verses. If the verses are equal() then return Verse a

Parameters:

a - The first verse to compare

b - The second verse to compare

Returns:

The bigger of the 2 verses

min

@Deprecated
public static Verse min(Verse a,
                                   Verse b)

Deprecated. do not use

Return the smaller of the 2 verses. If the verses are equal() then return Verse a

Parameters:

a - The first verse to compare

b - The second verse to compare

Returns:

The smaller of the 2 verses

toVerseArray

public Verse[] toVerseArray()

Create an array of Verses

Returns:

The array of verses that this makes up

getParent

public Key getParent()

Description copied from interface: Key

All keys have parents unless they are the root of a Key.

Specified by:

getParent in interface Key

Returns:

The parent of this tree, or null if this Key is the root.

setParent

public void setParent(Key parent)

Set a parent Key. This allows us to follow the Key interface more closely, although the concept of a parent for a verse is fairly alien.

Parameters:

parent - The parent Key for this verse

doGetName

@Deprecated
private String doGetName(Verse verseBase)

Deprecated. do not use

Compute the verse representation given the context.

Parameters:

verseBase - the context or null if there is none

Returns:

the verse representation

parseInt

protected static int parseInt(String text)
                       throws NoSuchVerseException

This is simply a convenience function to wrap Integer.parseInt() and give us a reasonable exception on failure. It is called by VerseRange hence protected, however I would prefer private

Parameters:

text - The string to be parsed

Returns:

The correctly parsed chapter or verse

Throws:

NoSuchVerseException

setAndPatch

@Deprecated
private void setAndPatch(BibleBook book,
                                    int chapter,
                                    int verse)

Deprecated. do not use

Mutate into this reference and fix the reference if needed. This must only be called from a ctor to maintain immutability

Parameters:

book - The book to set (Genesis = 1)

chapter - The chapter to set

verse - The verse to set

set

private void set(BibleBook book,
                 int chapter,
                 int verse)

Verify and set the references. This must only be called from a ctor to maintain immutability

Parameters:

book - The book to set (Genesis = 1)

chapter - The chapter to set

verse - The verse to set

set

@Deprecated
private void set(int ordinal)

Deprecated. do not use

Set the references. This must only be called from a ctor to maintain immutability

Parameters:

ordinal - The ordinal of the verse

writeObject

private void writeObject(ObjectOutputStream out)
                  throws IOException

Write out the object to the given ObjectOutputStream

Parameters:

out - The stream to write our state to

Throws:

IOException - if the read fails

readObject

private void readObject(ObjectInputStream in)
                 throws IOException,
                        ClassNotFoundException

Write out the object to the given ObjectOutputStream

Parameters:

in - The stream to read our state from

Throws:

IOException - if the read fails

ClassNotFoundException - If the read data is incorrect

canHaveChildren

public boolean canHaveChildren()

Description copied from interface: Key

Returns false if the receiver is a leaf node and can not have children. Any attempt to add()/remove() will throw

Specified by:

canHaveChildren in interface Key

getChildCount

public int getChildCount()

Description copied from interface: Key

Returns the number of children that this node has. Leaf nodes return 0.

Specified by:

getChildCount in interface Key

getCardinality

public int getCardinality()

Description copied from interface: Key

Returns the number of elements in this set (its cardinality). If this set contains more than Integer.MAX_VALUE elements, returns Integer.MAX_VALUE.

Specified by:

getCardinality in interface Key

Returns:

the number of elements in this set (its cardinality).

isEmpty

public boolean isEmpty()

Description copied from interface: Key

Does this Key have 0 members

Specified by:

isEmpty in interface Key

Returns:

true if this set contains no elements.

contains

public boolean contains(Key key)

Description copied from interface: Key

Returns true if this set contains the specified element.

Specified by:

contains in interface Key

Parameters:

key - element whose presence in this set is to be tested.

Returns:

true if this set contains the specified element.

iterator

public Iterator<Key> iterator()

Specified by:

iterator in interface Iterable<Key>

addAll

public void addAll(Key key)

Description copied from interface: Key

Adds the specified element to this set if it is not already present.

Specified by:

addAll in interface Key

Parameters:

key - element to be added to this set.

removeAll

public void removeAll(Key key)

Description copied from interface: Key

Removes the specified elements from this set if it is present.

Specified by:

removeAll in interface Key

Parameters:

key - object to be removed from this set, if present.

retainAll

public void retainAll(Key key)

Description copied from interface: Key

Removes all but the specified element from this set.

Specified by:

retainAll in interface Key

Parameters:

key - object to be left in this set.

clear

public void clear()

Description copied from interface: Key

Removes all of the elements from this set (optional operation). This set will be empty after this call returns (unless it throws an exception).

Specified by:

clear in interface Key

get

public Key get(int index)

Description copied from interface: Key

Gets a key from a specific point in this list of children.

Specified by:

get in interface Key

Parameters:

index - The index of the Key to retrieve

Returns:

The specified key

indexOf

public int indexOf(Key that)

Description copied from interface: Key

Reverse a Key into the position the key holds in the list of children

Specified by:

indexOf in interface Key

Parameters:

that - The Key to find

Returns:

The index of the key or < 0 if the key is not in the list

blur

public void blur(int by,
                 RestrictionType restrict)

Description copied from interface: Key

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

Specified by:

blur in interface Key

Parameters:

by - The number of verses/keys to widen by

restrict - How should we restrict the blurring?

See Also:

Passage