org.crosswire.jsword.passage

## Interface Key

- All Superinterfaces:
    Cloneable, Comparable<Key>, Iterable<Key>, Serializable
  All Known Subinterfaces:
    Passage, VerseKey<T>
  All Known Implementing Classes:
    AbstractKeyBackend, AbstractKeyList, AbstractPassage, BitwisePassage, DefaultKeyList, DefaultLeafKeyList, DistinctPassage, PassageTally, RangedPassage, RawLDBackend, ReadingsKey, ReadOnlyKeyList, ReadOnlyPassage, RocketPassage, SetKeyList, SynchronizedPassage, TreeKey, Verse, VerseRange, ZLDBackend

      public interface Key
      extends Comparable<Key>, Iterable<Key>, Cloneable, Serializable

  A Key is a Key that can contain other Keys. The interface is modeled on the java.util.Set interface customized because KeyLists can only store other Keys and simplified by making add() and remove() return void and not a boolean.
  Author:
    Joe Walker
  See Also:
    `The GNU Lesser General Public License for details.`

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addAll(Key key)` Adds the specified element to this set if it is not already present.
    `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).
    `Key` | `clone()` This needs to be declared here so that it is visible as a method on a derived Key.
    `boolean` | `contains(Key key)` Returns `true` if this set contains the specified element.
    `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.
    `int` | `getCardinality()` Returns the number of elements in this set (its cardinality).
    `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.
    `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` | `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
    `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.

    - ### Methods inherited from interface java.lang.Comparable

      `compareTo`

    - ### Methods inherited from interface java.lang.Iterable

      `iterator`

- - ### Method Detail

    - #### getName

          String getName()

      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"
      Returns:
        a String containing a description of the Key

    - #### getName

          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.
      Parameters:
        `base` - The key to use to cut down unnecessary output.
      Returns:
        The string representation

    - #### getRootName

          String getRootName()

      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.
      Returns:
        a String containing a description of the Key

    - #### getOsisRef

          String getOsisRef()

      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.
      Returns:
        a String containing the OSIS description of the verses

    - #### getOsisID

          String getOsisID()

      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.
      Returns:
        a String containing the OSIS description of the verses

    - #### getParent

          Key getParent()

      All keys have parents unless they are the root of a Key.
      Returns:
        The parent of this tree, or null if this Key is the root.

    - #### canHaveChildren

          boolean canHaveChildren()

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

    - #### getChildCount

          int getChildCount()

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

    - #### getCardinality

          int getCardinality()

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

      This method is potentially expensive, as it often requires cycling through all the keys in the set.

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

    - #### isEmpty

          boolean isEmpty()

      Does this Key have 0 members
      Returns:
        `true` if this set contains no elements.

    - #### contains

          boolean contains(Key key)

      Returns `true` if this set contains the specified element.
      Parameters:
        `key` - element whose presence in this set is to be tested.
      Returns:
        `true` if this set contains the specified element.

    - #### addAll

          void addAll(Key key)

      Adds the specified element to this set if it is not already present.
      Parameters:
        `key` - element to be added to this set.
      Throws:
        `NullPointerException` - if the specified element is null

    - #### removeAll

          void removeAll(Key key)

      Removes the specified elements from this set if it is present.
      Parameters:
        `key` - object to be removed from this set, if present.
      Throws:
        `NullPointerException` - if the specified element is null

    - #### retainAll

          void retainAll(Key key)

      Removes all but the specified element from this set.
      Parameters:
        `key` - object to be left in this set.
      Throws:
        `NullPointerException` - if the specified element is null

    - #### clear

          void clear()

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

    - #### get

          Key get(int index)

      Gets a key from a specific point in this list of children.
      Parameters:
        `index` - The index of the Key to retrieve
      Returns:
        The specified key
      Throws:
        `IndexOutOfBoundsException`

    - #### indexOf

          int indexOf(Key that)

      Reverse a Key into the position the key holds in the list of children
      Parameters:
        `that` - The Key to find
      Returns:
        The index of the key or < 0 if the key is not in the list

    - #### blur

          void blur(int by,
                  RestrictionType restrict)

      Widen the range of the verses/keys in this list. This is primarily for "find x within n verses of y" type applications.
      Parameters:
        `by` - The number of verses/keys to widen by
        `restrict` - How should we restrict the blurring?
      See Also:
        `Passage`

    - #### clone

          Key clone()

      This needs to be declared here so that it is visible as a method on a derived Key.
      Returns:
        A complete copy of ourselves

    - #### equals

          boolean equals(Object obj)

      This needs to be declared here so that it is visible as a method on a derived Key.
      Overrides:
        `equals` in class `Object`
      Parameters:
        `obj` -
      Returns:
        true if equal

    - #### hashCode

          int hashCode()

      This needs to be declared here so that it is visible as a method on a derived Key.
      Overrides:
        `hashCode` in class `Object`
      Returns:
        the hashcode