org.crosswire.jsword.passage

## Class ReadOnlyKeyList

- java.lang.Object
- - org.crosswire.jsword.passage.ReadOnlyKeyList

- All Implemented Interfaces:
    Serializable, Cloneable, Comparable<Key>, Iterable<Key>, Key

      public class ReadOnlyKeyList
      extends Object
      implements Key

  A read-only wrapper around any writable implementation of Key.
  Author:
    Joe Walker
  See Also:
    `The GNU Lesser General Public License for details.`, Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `private boolean` | `ignore` Do we ignore write requests or throw?
    `private Key` | `keys` The Key to which we proxy
    `private static long` | `serialVersionUID` Serialization ID

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ReadOnlyKeyList(Key keys, boolean ignore)` Simple ctor

  - ### 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).
    `ReadOnlyKeyList` | `clone()` This needs to be declared here so that it is visible as a method on a derived Key.
    `int` | `compareTo(Key o)`
    `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
    `Iterator<Key>` | `iterator()`
    `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 class java.lang.Object

      `finalize, getClass, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### ignore

          private boolean ignore

      Do we ignore write requests or throw?

    - #### keys

          private Key keys

      The Key to which we proxy

    - #### serialVersionUID

          private static final long serialVersionUID

      Serialization ID
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### ReadOnlyKeyList

          public ReadOnlyKeyList(Key keys,
                         boolean ignore)

      Simple ctor
      Parameters:
        `keys` - the keys
        `ignore` -

  - ### Method Detail

    - #### getCardinality

          public int getCardinality()

      Description copied from interface: `Key`
      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.

      Specified by:
        `getCardinality` in interface `Key`
      Returns:
        the number of elements in this set (its cardinality).

    - #### canHaveChildren

          public boolean canHaveChildren()

      Description copied from interface: `Key`
      Returns false if the receiver is a leaf node and can not have children. Any attempt to add()/remove() will throw
      Specified by:
        `canHaveChildren` in interface `Key`
      Returns:
        true if the key can have children

    - #### getChildCount

          public int getChildCount()

      Description copied from interface: `Key`
      Returns the number of children that this node has. Leaf nodes return 0.
      Specified by:
        `getChildCount` in interface `Key`
      Returns:
        the number of children for the node

    - #### isEmpty

          public boolean isEmpty()

      Description copied from interface: `Key`
      Does this Key have 0 members
      Specified by:
        `isEmpty` in interface `Key`
      Returns:
        `true` if this set contains no elements.

    - #### contains

          public boolean contains(Key key)

      Description copied from interface: `Key`
      Returns `true` if this set contains the specified element.
      Specified by:
        `contains` in interface `Key`
      Parameters:
        `key` - element whose presence in this set is to be tested.
      Returns:
        `true` if this set contains the specified element.

    - #### iterator

          public Iterator<Key> iterator()

      Specified by:
        `iterator` in interface `Iterable<Key>`

    - #### addAll

          public void addAll(Key key)

      Description copied from interface: `Key`
      Adds the specified element to this set if it is not already present.
      Specified by:
        `addAll` in interface `Key`
      Parameters:
        `key` - element to be added to this set.

    - #### removeAll

          public void removeAll(Key key)

      Description copied from interface: `Key`
      Removes the specified elements from this set if it is present.
      Specified by:
        `removeAll` in interface `Key`
      Parameters:
        `key` - object to be removed from this set, if present.

    - #### retainAll

          public void retainAll(Key key)

      Description copied from interface: `Key`
      Removes all but the specified element from this set.
      Specified by:
        `retainAll` in interface `Key`
      Parameters:
        `key` - object to be left in this set.

    - #### clear

          public void clear()

      Description copied from interface: `Key`
      Removes all of the elements from this set (optional operation). This set will be empty after this call returns (unless it throws an exception).
      Specified by:
        `clear` in interface `Key`

    - #### getName

          public String getName()

      Description copied from interface: `Key`
      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"
      Specified by:
        `getName` in interface `Key`
      Returns:
        a String containing a description of the Key

    - #### getName

          public String getName(Key base)

      Description copied from interface: `Key`
      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.
      Specified by:
        `getName` in interface `Key`
      Parameters:
        `base` - The key to use to cut down unnecessary output.
      Returns:
        The string representation

    - #### getRootName

          public String getRootName()

      Description copied from interface: `Key`
      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.
      Specified by:
        `getRootName` in interface `Key`
      Returns:
        a String containing a description of the Key

    - #### getOsisRef

          public String getOsisRef()

      Description copied from interface: `Key`
      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.
      Specified by:
        `getOsisRef` in interface `Key`
      Returns:
        a String containing the OSIS description of the verses

    - #### getOsisID

          public String getOsisID()

      Description copied from interface: `Key`
      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.
      Specified by:
        `getOsisID` in interface `Key`
      Returns:
        a String containing the OSIS description of the verses

    - #### hashCode

          public int hashCode()

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

    - #### equals

          public boolean equals(Object obj)

      Description copied from interface: `Key`
      This needs to be declared here so that it is visible as a method on a derived Key.
      Specified by:
        `equals` in interface `Key`
      Overrides:
        `equals` in class `Object`
      Returns:
        true if equal

    - #### compareTo

          public int compareTo(Key o)

      Specified by:
        `compareTo` in interface `Comparable<Key>`

    - #### get

          public Key get(int index)

      Description copied from interface: `Key`
      Gets a key from a specific point in this list of children.
      Specified by:
        `get` in interface `Key`
      Parameters:
        `index` - The index of the Key to retrieve
      Returns:
        The specified key

    - #### indexOf

          public int indexOf(Key that)

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

    - #### getParent

          public Key getParent()

      Description copied from interface: `Key`
      All keys have parents unless they are the root of a Key.
      Specified by:
        `getParent` in interface `Key`
      Returns:
        The parent of this tree, or null if this Key is the root.

    - #### blur

          public void blur(int by,
                  RestrictionType restrict)

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

    - #### clone

          public ReadOnlyKeyList clone()

      Description copied from interface: `Key`
      This needs to be declared here so that it is visible as a method on a derived Key.
      Specified by:
        `clone` in interface `Key`
      Overrides:
        `clone` in class `Object`
      Returns:
        A complete copy of ourselves