org.crosswire.jsword.passage
Class PassageKeyFactory

java.lang.Object
  extended by org.crosswire.jsword.passage.PassageKeyFactory

public final class PassageKeyFactory
extends Object

The PassageKeyFactory constructs Passages of the default Passage type. This allows for tuning the application to specific time/space needs and it allows for the development of other types of Passages without needing to change the application.

It is strongly recommended to use this factory to create passages if there is no driving need to create them for a specific purpose.

Most of the methods take the same arguments:

Most of the methods will throw:

Author:
Joe Walker, DM Smith
See Also:
The GNU Lesser General Public License for details.

Field Summary
private static PassageType defaultType
          The default type
private static PassageKeyFactory keyf
          How we create Passages
 
Constructor Summary
private PassageKeyFactory()
          This class implements a Singleton pattern.
 
Method Summary
protected static int binarySize(int max)
          Write to buffer (starting at index) the given number using a set of bytes as required by the max possible value for the number
 Key createEmptyKeyList(Versification v11n)
          Create an empty list of keys for the v11n
protected static int fromBinary(byte[] buffer, int[] index, int max)
          Read and return an int from the buffer (starting at index[0]) using a set of bytes as required by the max possible value for the number, and incrementing index[0] by that number of bytes.
(package private) static Passage fromBinaryRepresentation(byte[] buffer)
          Write out the object to the given ObjectOutputStream
static int getDefaultPassage()
          Get the default passage type as the ordinal value of the PassageType.
static PassageType getDefaultType()
          Get the default PassageType.
 Key getGlobalKeyList(Versification v11n)
          Get a Passage containing all the Verses in this Versification.
 Passage getKey(Versification v11n, String passageReference)
          Convert the passageReference into a Passage.
 Passage getKey(Versification v11n, String passageReference, Key basis)
          Convert the passageReference into a Passage.
static Passage getReadOnlyPassage(Passage ref, boolean ignore)
          Get a new Passage based on another Passage that synchronizes all access to its members.
static Passage getSynchronizedPassage(Passage ref)
          Get a new Passage based on another Passage that synchronizes all access to its members.
 Key getValidKey(Versification v11n, String passageReference)
          Convert the passageReference into a Passage or an empty Passage, if there is an error.
 Key getValidKey(Versification v11n, String passageReference, Key basis)
          Convert the passageReference into a Passage or an empty Passage, if there is an error.
static PassageKeyFactory instance()
          This PassageKeyFactory is accessed through this instance.
private  String mungOsisRef(String passageReference)
          Replace spaces with semi-colons, because the parser expects them.
private  String normalize(String passageReference)
          The internals of a Passage require that references are separated with a reference delimiter.
static Passage readPassage(Reader in)
          Read a passage from a given stream
static void setDefaultPassage(int newDefaultType)
          Set the default PassageType.
static void setDefaultType(PassageType newDefaultType)
          Set the default PassageType
protected static int toBinary(byte[] buffer, int index, int number, int max)
          Write to buffer (starting at index) the given number using a set of bytes as required by the max possible value for the number
(package private) static byte[] toBinaryRepresentation(Passage ref)
          Convert us to a binary representation.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

defaultType

private static PassageType defaultType
The default type


keyf

private static PassageKeyFactory keyf
How we create Passages

Constructor Detail

PassageKeyFactory

private PassageKeyFactory()
This class implements a Singleton pattern. So the ctor is private

Method Detail

instance

public static PassageKeyFactory instance()
This PassageKeyFactory is accessed through this instance.

Returns:
this PassageKeyFactory

createEmptyKeyList

public Key createEmptyKeyList(Versification v11n)
Create an empty list of keys for the v11n

Parameters:
v11n - The Versification to which this Passage belongs.
Returns:
an empty Passage

getGlobalKeyList

public Key getGlobalKeyList(Versification v11n)
Get a Passage containing all the Verses in this Versification. This differs from Book.getGlobalKeyList() which gets the verses in the Book, which may be a small part of the whole.

Parameters:
v11n - The Versification to which this Passage belongs.
Returns:
the Passage with all the Verses in the Versification

getValidKey

public Key getValidKey(Versification v11n,
                       String passageReference,
                       Key basis)
Convert the passageReference into a Passage or an empty Passage, if there is an error. Note, this is not recommended as it throws away the error.

Parameters:
v11n - The Versification to which this Passage belongs.
passageReference - A String containing the text of the Passage
basis - The basis by which to interpret passageReference
Returns:
a new Passage filled with the desired Verses or an empty Passage

getValidKey

public Key getValidKey(Versification v11n,
                       String passageReference)
Convert the passageReference into a Passage or an empty Passage, if there is an error. Note, this is not recommended as it throws away the error.

Parameters:
v11n - The Versification to which this Passage belongs.
passageReference - A String containing the text for the Passage
Returns:
a new Passage filled with the desired Verses or an empty Passage

getKey

public Passage getKey(Versification v11n,
                      String passageReference,
                      Key basis)
               throws NoSuchKeyException
Convert the passageReference into a Passage. This is the recommended form for understanding references in ThML and GBF.

Parameters:
v11n - The Versification to which this Passage belongs.
passageReference - A String containing the text for the Passage
basis - The basis by which to interpret passageReference
Returns:
a new Passage filled with the desired Verses
Throws:
NoSuchKeyException - If the passageReference has anything that could not be understood as a Verse

getKey

public Passage getKey(Versification v11n,
                      String passageReference)
               throws NoSuchKeyException
Convert the passageReference into a Passage. This is the recommended form for application constructed references and user input. Both of these should have a fully qualified first reference.

Parameters:
v11n - The Versification to which this Passage belongs.
passageReference - A String containing the text for the Passage
Returns:
a new Passage filled with the desired Verses
Throws:
NoSuchKeyException - If the passageReference has anything that could not be understood as a Verse

setDefaultType

public static void setDefaultType(PassageType newDefaultType)
Set the default PassageType

Parameters:
newDefaultType - The new default PassageType.

getDefaultType

public static PassageType getDefaultType()
Get the default PassageType.

Returns:
The default PassageType.

setDefaultPassage

public static void setDefaultPassage(int newDefaultType)
Set the default PassageType. Must be the ordinal value of one of:

Parameters:
newDefaultType - The new default type.

getDefaultPassage

public static int getDefaultPassage()
Get the default passage type as the ordinal value of the PassageType.

Returns:
default_type The new default type.
See Also:
setDefaultPassage(int)

getSynchronizedPassage

public static Passage getSynchronizedPassage(Passage ref)
Get a new Passage based on another Passage that synchronizes all access to its members.

Parameters:
ref - The passage to synchronize
Returns:
A new synchronized passage that proxies requests to the original

getReadOnlyPassage

public static Passage getReadOnlyPassage(Passage ref,
                                         boolean ignore)
Get a new Passage based on another Passage that synchronizes all access to its members.

Parameters:
ref - The passage to synchronize
ignore - Do we throw up if someone tries to change us
Returns:
A new synchronized passage that proxies requests to the original

toBinaryRepresentation

static byte[] toBinaryRepresentation(Passage ref)
Convert us to a binary representation. There are some distinctly endianist happenings here, but that is OK because we are reading the stuff we write here just below.

Parameters:
ref - The Passage to convert
Returns:
a byte array

fromBinaryRepresentation

static Passage fromBinaryRepresentation(byte[] buffer)
                                 throws NoSuchKeyException
Write out the object to the given ObjectOutputStream

Parameters:
buffer - The stream to read our state from
Returns:
The converted Passage
Throws:
NoSuchKeyException - If the buffer is invalid

readPassage

public static Passage readPassage(Reader in)
                           throws IOException,
                                  NoSuchKeyException
Read a passage from a given stream

Parameters:
in - The stream to read from
Returns:
a newly built Passage
Throws:
IOException - If there was trouble reading the stream
NoSuchKeyException - if the data was not a valid passage

binarySize

protected static int binarySize(int max)
Write to buffer (starting at index) the given number using a set of bytes as required by the max possible value for the number

Parameters:
max - The number to write
Returns:
The number of bytes needed

toBinary

protected static int toBinary(byte[] buffer,
                              int index,
                              int number,
                              int max)
Write to buffer (starting at index) the given number using a set of bytes as required by the max possible value for the number

Parameters:
buffer - Where to write to
index - The offset to start at
number - The number to write
max - The max size
Returns:
The number of bytes written

fromBinary

protected static int fromBinary(byte[] buffer,
                                int[] index,
                                int max)
Read and return an int from the buffer (starting at index[0]) using a set of bytes as required by the max possible value for the number, and incrementing index[0] by that number of bytes.

Parameters:
buffer - The buffer to read from
index - The offset to start at
max - The max number of bytes to read
Returns:
The converted number

mungOsisRef

private String mungOsisRef(String passageReference)
Replace spaces with semi-colons, because the parser expects them.

Parameters:
passageReference -
Returns:
the munged value

normalize

private String normalize(String passageReference)
The internals of a Passage require that references are separated with a reference delimiter. However, people and other systems may not be so stringent. So we want to allow for "Ge 1:26 3:22 11:7 20:13 31:7, 53 35:7" (which is from Clarke) This should become "Ge 1:26, 3:22, 11:7, 20:13, 31:7, 53, 35:7" Basically, the rule of thumb is that if two numbers are found separated by whitespace then add a comma between them. One note $, and ff are taken to be numbers. But it is complicated by Book names that are like 1 Cor And by verse references like Gen 1.2 Gen.1.2 Gen 1 2 which are all equivalent. So we use a counter when we see a number, if the counter reaches 2 and then we see a name or a number we emit a reference delimiter.

Parameters:
passageReference -
Returns:
the normalized value

Copyright ยจ 2003-2015