org.crosswire.jsword.passage

## Class RocketPassage

- java.lang.Object
- - org.crosswire.jsword.passage.AbstractPassage
  - - org.crosswire.jsword.passage.BitwisePassage
    - - org.crosswire.jsword.passage.RocketPassage

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

      public class RocketPassage
      extends BitwisePassage

  A RocketPassage is a bit and heavy implementation of Passage that goes fairly quickly once let of the leash. It manages its speed by creating contained instances of DistinctPassage and RangedPassage and selects the fastest implementation for each of its methods from the 3 available.
  Author:
    Joe Walker
  See Also:
    `The GNU Lesser General Public License for details.`, Serialized Form

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from class org.crosswire.jsword.passage.AbstractPassage

      `AbstractPassage.VerseRangeIterator`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `private DistinctPassage` | `distinct` The contained DistinctPassage
    `private RangedPassage` | `ranged` The contained RangedPassage
    `private static long` | `serialVersionUID` Serialization ID

    - ### Fields inherited from class org.crosswire.jsword.passage.BitwisePassage

      `store`

    - ### Fields inherited from class org.crosswire.jsword.passage.AbstractPassage

      `BITWISE, DISTINCT, listeners, METHOD_COUNT, originalName, RANGED, REF_ALLOWED_DELIMS, REF_OSIS_DELIM, REF_PREF_DELIM, skipNormalization, suppressEvents`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `` | `RocketPassage(Versification v11n)` Create a new RocketPassage
    `protected` | `RocketPassage(Versification v11n, String refs)` Create a Verse from a human readable string.
    `protected` | `RocketPassage(Versification v11n, String refs, Key basis)` Create a Verse from a human readable string.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `int` | `booksInPassage()` How many books are there in this Passage
    `boolean` | `containsAll(Passage that)` Returns true if this Passage contains all of the verses in that Passage
    `int` | `countRanges(RestrictionType restrict)` Like countVerses() that counts VerseRanges instead of Verses Returns the number of fragments in this collection.
    `int` | `countVerses()` Returns the number of verses in this collection.
    `VerseRange` | `getRangeAt(int offset, RestrictionType restrict)` Get a specific VerseRange from this collection
    `Verse` | `getVerseAt(int offset)` Get a specific Verse from this collection
    `boolean` | `isEmpty()` Does this Key have 0 members
    `Iterator<Key>` | `iterator()`
    `void` | `optimizeReads()` For performance reasons we may well want to hint to the Passage that we have done editing it for now and that it is safe to cache certain values to speed up future reads.
    `protected void` | `optimizeWrites()` Simple method to instruct children to stop caching results
    `Iterator<VerseRange>` | `rangeIterator(RestrictionType restrict)` Like iterator() that iterates over VerseRanges instead of Verses.
    `private void` | `readObject(ObjectInputStream is)` Serialization support

    - ### Methods inherited from class org.crosswire.jsword.passage.BitwisePassage

      `add, addAll, addVersifiedOrdinal, blur, clear, clone, contains, remove, removeAll, retainAll`

    - ### Methods inherited from class org.crosswire.jsword.passage.AbstractPassage

      `addPassageListener, addVerses, canHaveChildren, compareTo, equals, fireContentsChanged, fireIntervalAdded, fireIntervalRemoved, get, getCardinality, getChildCount, getName, getName, getOsisID, getOsisRef, getOverview, getParent, getRootName, getVersification, getWhole, hashCode, hasRanges, indexOf, isWhole, lowerEventSuppressionAndTest, lowerNormalizeProtection, normalize, raiseEventSuppresion, raiseNormalizeProtection, readDescription, readObjectSupport, removePassageListener, reversify, setParent, toString, toVerseRange, trimRanges, trimVerses, writeDescription, writeObjectSupport`

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

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

- - ### Field Detail

    - #### distinct

          private transient DistinctPassage distinct

      The contained DistinctPassage

    - #### ranged

          private transient RangedPassage ranged

      The contained RangedPassage

    - #### serialVersionUID

          private static final long serialVersionUID

      Serialization ID
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### RocketPassage

          public RocketPassage(Versification v11n)

      Create a new RocketPassage
      Parameters:
        `v11n` - The Versification to which this Passage belongs.

    - #### RocketPassage

          protected RocketPassage(Versification v11n,
                       String refs,
                       Key basis)
                           throws NoSuchVerseException

      Create a Verse from a human readable string. The opposite of getName(), Given any RangedPassage v1, and the following `RangedPassage v2 = new RangedPassage(v1.getName());` Then `v1.equals(v2);` Theoretically, since there are many ways of representing a RangedPassage as text string comparison along the lines of: `v1.getName().equals(v2.getName())` could be false. However since getName() is standardized this will be true. We don't need to worry about thread safety in a ctor since we don't exist yet.
      Parameters:
        `v11n` - The Versification to which this Passage belongs.
        `refs` - A String containing the text of the RangedPassage
        `basis` - The basis by which to interpret refs
      Throws:
        `NoSuchVerseException` - if refs is invalid

    - #### RocketPassage

          protected RocketPassage(Versification v11n,
                       String refs)
                           throws NoSuchVerseException

      Create a Verse from a human readable string. The opposite of getName(), Given any RangedPassage v1, and the following `RangedPassage v2 = new RangedPassage(v1.getName());` Then `v1.equals(v2);` Theoretically, since there are many ways of representing a RangedPassage as text string comparison along the lines of: `v1.getName().equals(v2.getName())` could be false. However since getName() is standardized this will be true. We don't need to worry about thread safety in a ctor since we don't exist yet.
      Parameters:
        `v11n` - The Versification to which this Passage belongs.
        `refs` - A String containing the text of the RangedPassage
      Throws:
        `NoSuchVerseException` - if refs is invalid

  - ### Method Detail

    - #### optimizeReads

          public void optimizeReads()

      Description copied from interface: `Passage`
      For performance reasons we may well want to hint to the Passage that we have done editing it for now and that it is safe to cache certain values to speed up future reads. Any action taken by this method will be undone simply by making a future edit, and the only loss in calling optimizeReads() is a loss of time if you then persist in writing to the Passage.
      Specified by:
        `optimizeReads` in interface `Passage`
      Overrides:
        `optimizeReads` in class `AbstractPassage`

    - #### optimizeWrites

          protected void optimizeWrites()

      Description copied from class: `AbstractPassage`
      Simple method to instruct children to stop caching results
      Overrides:
        `optimizeWrites` in class `AbstractPassage`

    - #### countRanges

          public int countRanges(RestrictionType restrict)

      Description copied from interface: `Passage`
      Like countVerses() that counts VerseRanges instead of Verses Returns the number of fragments in this collection. This does not mean the Passage needs to use VerseRanges, just that it understands the concept.
      Specified by:
        `countRanges` in interface `Passage`
      Overrides:
        `countRanges` in class `AbstractPassage`
      Parameters:
        `restrict` - Do we break ranges at chapter/book boundaries
      Returns:
        the number of VerseRanges in this collection
      See Also:
        `VerseRange`

    - #### countVerses

          public int countVerses()

      Description copied from interface: `Passage`
      Returns the number of verses in this collection. Like Collection.size() This does not mean the Passage needs to use Verses, just that it understands the concept.
      Specified by:
        `countVerses` in interface `Passage`
      Overrides:
        `countVerses` in class `BitwisePassage`
      Returns:
        the number of Verses in this collection
      See Also:
        `Verse`

    - #### iterator

          public Iterator<Key> iterator()

      Specified by:
        `iterator` in interface `Iterable<Key>`
      Overrides:
        `iterator` in class `BitwisePassage`

    - #### rangeIterator

          public Iterator<VerseRange> rangeIterator(RestrictionType restrict)

      Description copied from interface: `Passage`
      Like iterator() that iterates over VerseRanges instead of Verses. Exactly the same data will be traversed, however using rangeIterator() will usually give fewer iterations (and never more)
      Specified by:
        `rangeIterator` in interface `Passage`
      Overrides:
        `rangeIterator` in class `AbstractPassage`
      Parameters:
        `restrict` - Do we break ranges over chapters
      Returns:
        A list enumerator

    - #### isEmpty

          public boolean isEmpty()

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

    - #### getVerseAt

          public Verse getVerseAt(int offset)
                           throws ArrayIndexOutOfBoundsException

      Description copied from interface: `Passage`
      Get a specific Verse from this collection
      Specified by:
        `getVerseAt` in interface `Passage`
      Overrides:
        `getVerseAt` in class `AbstractPassage`
      Parameters:
        `offset` - The verse offset (legal values are 0 to countVerses()-1)
      Returns:
        The Verse
      Throws:
        `ArrayIndexOutOfBoundsException` - If the offset is out of range

    - #### getRangeAt

          public VerseRange getRangeAt(int offset,
                              RestrictionType restrict)
                                throws ArrayIndexOutOfBoundsException

      Description copied from interface: `Passage`
      Get a specific VerseRange from this collection
      Specified by:
        `getRangeAt` in interface `Passage`
      Overrides:
        `getRangeAt` in class `AbstractPassage`
      Parameters:
        `offset` - The verse range offset (legal values are 0 to countRanges()-1)
        `restrict` - Do we break ranges at chapter/book boundaries
      Returns:
        The Verse Range
      Throws:
        `ArrayIndexOutOfBoundsException` - If the offset is out of range

    - #### booksInPassage

          public int booksInPassage()

      Description copied from interface: `Passage`
      How many books are there in this Passage
      Specified by:
        `booksInPassage` in interface `Passage`
      Overrides:
        `booksInPassage` in class `AbstractPassage`
      Returns:
        The number of distinct books

    - #### containsAll

          public boolean containsAll(Passage that)

      Description copied from interface: `Passage`
      Returns true if this Passage contains all of the verses in that Passage
      Specified by:
        `containsAll` in interface `Passage`
      Overrides:
        `containsAll` in class `AbstractPassage`
      Parameters:
        `that` - Passage to be checked for containment in this collection.
      Returns:
        true if this reference contains all of the Verses in that Passage

    - #### readObject

          private void readObject(ObjectInputStream is)
                           throws IOException,
                                  ClassNotFoundException

      Serialization support
      Parameters:
        `is` - The stream to read our state from
      Throws:
        `IOException` - if the read fails
        `ClassNotFoundException` - If the read data is incorrect