org.crosswire.jsword.versification

## Class QualifiedKey

- java.lang.Object
- - org.crosswire.jsword.versification.QualifiedKey

-     public final class QualifiedKey
      extends Object

  A QualifiedKey represents the various left and right sides of a map entry.

  The QualifiedKey is Qualified:

  - DEFAULT - This QualifiedKey is either a Verse or a VerseRange.
  - ABSENT_IN_KJV - This QualifiedKey has a section name for what is absent in the KJV (the right hand of the map entry).
  - ABSENT_IN_LEFT - This QualifiedKey has no other content.

  The mapping can indicate a part of a verse. This is an internal implementation detail of the Versification mapping code. Here it is used to distinguish one QualifiedKey from another in equality tests and in containers.

  Author:
    Chris Burrell
  See Also:
    `The GNU Lesser General Public License for details.
    The copyright to this program is held by its authors.`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `(package private) static class` | `QualifiedKey.Qualifier` A Qualifier indicates whether the verse is numbered the same in both the KJV and the other, is missing in the KJV or the other.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `private QualifiedKey.Qualifier` | `absentType`
    `private VerseKey` | `qualifiedKey`
    `private String` | `sectionName`
    `private VerseKey` | `wholeKey`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `` | `QualifiedKey()` Constructs the QualifiedKey with the ABSENT_IN_LEFT qualifier.
    `` | `QualifiedKey(String sectionName)`
    `protected` | `QualifiedKey(Verse key)` Construct a QualifiedKey from a Verse.
    `` | `QualifiedKey(VerseRange key)` Construct a QualifiedKey from a Verse.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `private static boolean` | `bothNullOrEqual(Object x, Object y)` Determine whether two objects are equal, allowing nulls
    `static QualifiedKey` | `create(VerseKey k)` Create a QualifiedKey from a Verse or a VerseRange.
    `boolean` | `equals(Object obj)`
    `QualifiedKey.Qualifier` | `getAbsentType()`
    `VerseKey` | `getKey()`
    `String` | `getSectionName()`
    `Verse` | `getVerse()`
    `int` | `hashCode()`
    `boolean` | `isWhole()` A QualifiedKey is whole if it does not split part of a reference.
    `QualifiedKey` | `reversify(Versification target)` Convert this QualifiedKey from one Versification to another.
    `private void` | `setKey(Verse key)` Allow override of the key, particular useful if we're constructing in 2 stages like the offset mechanism
    `private void` | `setKey(VerseRange key)` Allow override of the key, particular useful if we're constructing in 2 stages like the offset mechanism
    `String` | `toString()`

    - ### Methods inherited from class java.lang.Object

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### qualifiedKey

          private VerseKey qualifiedKey

    - #### wholeKey

          private VerseKey wholeKey

    - #### sectionName

          private String sectionName

    - #### absentType

          private QualifiedKey.Qualifier absentType

  - ### Constructor Detail

    - #### QualifiedKey

          protected QualifiedKey(Verse key)

      Construct a QualifiedKey from a Verse.
      Parameters:
        `key` - the verse from which to create this QualifiedKey

    - #### QualifiedKey

          public QualifiedKey(VerseRange key)

      Construct a QualifiedKey from a Verse.
      Parameters:
        `key` - the verse range from which to create this QualifiedKey

    - #### QualifiedKey

          public QualifiedKey(String sectionName)

      Parameters:
        `sectionName` - with a given section name, we assume absent in KJV

    - #### QualifiedKey

          public QualifiedKey()

      Constructs the QualifiedKey with the ABSENT_IN_LEFT qualifier. This really means that there are no fields in this QualifiedKey.

  - ### Method Detail

    - #### create

          public static QualifiedKey create(VerseKey k)

      Create a QualifiedKey from a Verse or a VerseRange.
      Parameters:
        `k` - the Verse or VerseRange
      Returns:
        the created QualifiedKey
      Throws:
        `ClassCastException`

    - #### getKey

          public VerseKey getKey()

      Returns:
        * The internal key which is either a Verse or VerseRange

    - #### getVerse

          public Verse getVerse()

      Returns:
        * The internal key cast as a Verse
      Throws:
        `ClassCastException`

    - #### getAbsentType

          public QualifiedKey.Qualifier getAbsentType()

      Returns:
        the type of the unknown qualifier

    - #### getSectionName

          public String getSectionName()

      Returns:
        the name (any name) of the section represented within the KJV

    - #### isWhole

          public boolean isWhole()

      A QualifiedKey is whole if it does not split part of a reference.
      Returns:
        whether this QualifiedKey has a whole reference

    - #### reversify

          public QualifiedKey reversify(Versification target)

      Convert this QualifiedKey from one Versification to another. This is a potentially dangerous operation that does no mapping from one versification to another. Use it only when it is known to be safe.
      Parameters:
        `target` - The target versification
      Returns:
        The reversified QualifiedKey

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `Object`

    - #### equals

          public boolean equals(Object obj)

      Overrides:
        `equals` in class `Object`

    - #### setKey

          private void setKey(Verse key)

      Allow override of the key, particular useful if we're constructing in 2 stages like the offset mechanism
      Parameters:
        `key` - the new key

    - #### setKey

          private void setKey(VerseRange key)

      Allow override of the key, particular useful if we're constructing in 2 stages like the offset mechanism
      Parameters:
        `key` - the new key

    - #### bothNullOrEqual

          private static boolean bothNullOrEqual(Object x,
                                Object y)

      Determine whether two objects are equal, allowing nulls
      Parameters:
        `x` -
        `y` -
      Returns:
        true if both are null or the two are equal