org.crosswire.jsword.passage
Class PassageKeyFactory

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

All Implemented Interfaces:

KeyFactory

public class PassageKeyFactory
extends Object
implements KeyFactory

An implementation of KeyFactory that works for most Bibles that contain all the verses in the Bible.

Distribution Licence:
JSword 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, or by writing to: Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
The copyright to this program is held by it's authors.

Version:

$Id: PassageKeyFactory.java,v 1.8 2005/03/19 18:44:58 dmsmith Exp $

Author:

Joe Walker [joe at eireneh dot com]

See Also:

Licence

Field Summary

private static int	defaultType The default type
private static KeyFactory	keyf How we create Passages
static int	MIX Optimize the Passage for a mix
static int	SIZE Optimize the Passage for size
static int	SPEED Optimize the Passage for speed
static int	TALLY Optimize the Passage for tally operations
private static Passage	whole The cached whole Bible passage
static int	WRITE_SPEED Optimize the Passage for speed

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() Fetch an empty Key to which we can add Keys.
protected Passage	createPassage() Create an empty Passage using the default type.
protected Passage	createPassage(int type) Create an empty Passage using a specified type.
protected Passage	createPassage(int type, String name) Create an empty Passage using a specified type.
protected Passage	createPassage(String name) Create an empty Passage using the default type.
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.
static Passage	fromBinaryRepresentation(byte[] buffer) Write out the object to the given ObjectOutputStream
static int	getDefaultPassage() Get the default reference type.
Key	getGlobalKeyList() Get a complete list of index entries.
Key	getKey(String name) Someone has typed in a reference to find, but we need a Key to actually look it up.
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.
static KeyFactory	instance()
static Passage	readPassage(Reader in) Read a passage from a given stream
static void	setDefaultPassage(int defaultType) Set the default reference type.
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
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

SPEED

public static final int SPEED

Optimize the Passage for speed

See Also:

Constant Field Values

WRITE_SPEED

public static final int WRITE_SPEED

Optimize the Passage for speed

See Also:

Constant Field Values

SIZE

public static final int SIZE

Optimize the Passage for size

See Also:

Constant Field Values

MIX

public static final int MIX

Optimize the Passage for a mix

See Also:

Constant Field Values

TALLY

public static final int TALLY

Optimize the Passage for tally operations

See Also:

Constant Field Values

keyf

private static KeyFactory keyf

How we create Passages

whole

private static Passage whole

The cached whole Bible passage

defaultType

private static int defaultType

The default type

Constructor Detail

PassageKeyFactory

private PassageKeyFactory()

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

Method Detail

instance

public static KeyFactory instance()

createEmptyKeyList

public Key createEmptyKeyList()

Description copied from interface: KeyFactory

Fetch an empty Key to which we can add Keys. Not all implementations of Key are able to hold any type of Key, It isn't reasonable to expect a Key of Bible verses (=Passage) to hold a dictionary Key. So each KeyFactory must be able to create you an empty Key to which you can safely add other Keys it generates.

Specified by:

createEmptyKeyList in interface KeyFactory

Returns:

An empty Key that can hold other Keys from this factory.

getKey

public Key getKey(String name)
           throws NoSuchKeyException

Description copied from interface: KeyFactory

Someone has typed in a reference to find, but we need a Key to actually look it up. So we create a Key from the string if such a translation is possible. The returned Key may be a BranchKey if the string represents more than one Key.

Specified by:

getKey in interface KeyFactory

Parameters:

name - The string to translate into a Key

Returns:

The Key corresponding to the input text

Throws:

NoSuchKeyException - If the name can not be parsed.

getGlobalKeyList

public Key getGlobalKeyList()

Description copied from interface: KeyFactory

Get a complete list of index entries. Create a Key that encompasses all of the known valid keys for the given context. For a dictionary this will include all of the entries in the dictionary, for a Bible this will probably include all the verses in the Bible, but a commentary may well miss some out.

Specified by:

getGlobalKeyList in interface KeyFactory

Returns:

A Key that includes all of the known Keys

createPassage

protected Passage createPassage()

Create an empty Passage using the default type.

Returns:

The new Passage

createPassage

protected Passage createPassage(String name)
                         throws NoSuchVerseException

Create an empty Passage using the default type. And set the contents of the Passage using a string.

Parameters:

name - The Passage description.

Returns:

The new Passage

Throws:

NoSuchVerseException - if the name is invalid

createPassage

protected Passage createPassage(int type)

Create an empty Passage using a specified type.

Parameters:

type - The type of Passage to create.

Returns:

The new Passage

See Also:

setDefaultPassage(int)

createPassage

protected Passage createPassage(int type,
                                String name)
                         throws NoSuchVerseException

Create an empty Passage using a specified type. And set the contents of the Passage using a string.

Parameters:

type - The type of Passage to create.

name - The Passage description.

Returns:

The new Passage

Throws:

NoSuchVerseException - if the name is invalid

See Also:

setDefaultPassage(int)

setDefaultPassage

public static void setDefaultPassage(int defaultType)

Set the default reference type. Must be one of:

• PassageFactory.SPEED
• PassageFactory.WRITE_SPEED
• PassageFactory.SIZE
• PassageFactory.MIX
• PassageFactory.TALLY

Parameters:

defaultType - The new default type.

getDefaultPassage

public static int getDefaultPassage()

Get the default reference type.

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

public static byte[] toBinaryRepresentation(Passage ref)

Convert us to a binary representation. There are sme 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

public static Passage fromBinaryRepresentation(byte[] buffer)
                                        throws NoSuchVerseException

Write out the object to the given ObjectOutputStream

Parameters:

buffer - The stream to read our state from

Returns:

The converted Passage

Throws:

NoSuchVerseException - If the buffer is invalid

readPassage

public static Passage readPassage(Reader in)
                           throws IOException,
                                  NoSuchVerseException

Read a passage from a given stream

Parameters:

in - The stream to read from

Returns:

a newly built Passage

Throws:

IOException - If there was troule reading the stream

NoSuchVerseException - 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 nuber of bytes to read

Returns:

The converted number