org.crosswire.jsword.passage

## Class PassageKeyFactory

- java.lang.Object
- - 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:

  - Versification v11n - All Passages are created as part of a Versification. Verses and VerseRanges which make up a Passage, require a one.
  - String passageReference - A string representation for the Passage. The parser is very lenient, but requires the verses to be a member of the Versification.
  - VerseRange basis - When interpreting a reference, the prior reference forms the context to understand that reference. For example, when seeing 11:1, it needs the context of the BibleBook to know what this chapter and verse belongs. A basis is not needed for OSIS references, as every verse is fully qualified. But for references from ThML and GBF, it is highly needed.

  Most of the methods will throw:

  - NoSuchKeyException - Indicating that something in the string references could not be understood as a verse. The message of the exception will give the precise reason for the failure.
  Author:
    Joe Walker, DM Smith
  See Also:
    `The GNU Lesser General Public License for details.`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `private static PassageType` | `defaultType` The default type
    `private static PassageKeyFactory` | `keyf` How we create Passages

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `private` | `PassageKeyFactory()` This class implements a Singleton pattern.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `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:
      - PassageType.SPEED
      - PassageType.WRITE_SPEED
      - PassageType.SIZE
      - PassageType.MIX
      - PassageType.TALLY
      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