org.apache.uima.cas

## Interface FSIterator<T extends FeatureStructure>

- All Superinterfaces:
    Iterator<T>
  All Known Implementing Classes:
    FSIndexFlat.FSIteratorFlat, FSIteratorImplBase, FSIteratorWrapper, FSIteratorWrapperDoubleCheck, Subiterator

      public interface FSIterator<T extends FeatureStructure>
      extends Iterator<T>

  Iterator over feature structures.

  This iterator interface extends `Iterator`, and supports the standard `hasNext` and `next` methods. If finer control, including reverse iteration, is needed, see below.

  Note: do not use the APIs described below *together* with the standard Java iterator methods `next()` and `hasNext()`. On any given iterator, use either the one or the other, but not both together. Otherwise, `next/hasNext` may exhibit incorrect behavior.

  The `FSIterator` interface introduces the methods `get()`, `moveToNext()`, `moveToPrevious()` methods. With these methods, retrieving the current element (`get`) is a separate operation from moving the iterator (`moveToNext` and `moveToPrevious`. This makes the user's code less compact, but allows for finer control.

  Specifically the `get` method is defined to return the same element that a call to `next()` would return, but does not advance the iterator.

  Implementations of this interface are not required to be fail-fast. That is, if the iterator's collection is modified, the effects on the iterator are in general undefined. Some collections may handle this more gracefully than others, but in general, concurrent modification of the collection you're iterating over is a bad idea.

  If the iterator is moved past the boundaries of the collection, the behavior of subsequent calls to `moveToNext()` or `moveToPrevious()` is undefined. For example, if a previously valid iterator is invalidated by a call to `moveToNext()`, a subsequent call to `moveToPrevious()` is not guaranteed to set the iterator back to the last element in the collection. Always use `moveToLast()` in such cases.

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `FSIterator<T>` | `copy()` Copy this iterator.
    `T` | `get()` Get the structure the iterator is pointing at.
    `boolean` | `isValid()` Check if this iterator is valid.
    `void` | `moveTo(FeatureStructure fs)` Move the iterator to the first Feature Structure that is equal to `fs`.
    `void` | `moveToFirst()` Move the iterator to the first element.
    `void` | `moveToLast()` Move the iterator to the last element.
    `void` | `moveToNext()` Advance the iterator.
    `void` | `moveToPrevious()` Move the iterator one element back.

    - ### Methods inherited from interface java.util.Iterator

      `forEachRemaining, hasNext, next, remove`

- - ### Method Detail

    - #### isValid

          boolean isValid()

      Check if this iterator is valid.
      Returns:
        `true` if the iterator is valid.

    - #### get

          T get()
          throws NoSuchElementException

      Get the structure the iterator is pointing at.
      Returns:
        The structure the iterator is pointing at.
      Throws:
        `NoSuchElementException` - If the iterator is not valid.

    - #### moveToNext

          void moveToNext()

      Advance the iterator. This may invalidate the iterator.
      Throws:
        `ConcurrentModificationException` - if the underlying indexes being iterated over were modified

    - #### moveToPrevious

          void moveToPrevious()

      Move the iterator one element back. This may invalidate the iterator.
      Throws:
        `ConcurrentModificationException` - if the underlying indexes being iterated over were modified

    - #### moveToFirst

          void moveToFirst()

      Move the iterator to the first element. The iterator will be valid iff the underlying collection is non-empty. Allowed even if the underlying indexes being iterated over were modified.

    - #### moveToLast

          void moveToLast()

      Move the iterator to the last element. The iterator will be valid iff the underlying collection is non-empty. Allowed even if the underlying indexes being iterated over were modified.

    - #### moveTo

          void moveTo(FeatureStructure fs)

      Move the iterator to the first Feature Structure that is equal to `fs`. First means the earliest one occurring in the index, in case multiple FSs that are "equal" to fs are in the index. If no such feature structure exists in the underlying collection, set the iterator to the "insertion point" for `fs`, i.e., to a point where the current feature structure is greater than `fs`, and the previous one is less than `fs`.

      If the fs is greater than all of the entries in the index, the moveTo cannot set the iterator to an insertion point where the current feature structure is greater than fs, so it marks the iterator "invalid".

      If the underlying index is a bag index, no ordering is present, and the moveTo operation moves to the fs which is the same identical fs as the key. If no such fs is in the index, the iterator is marked invalid.

      Parameters:
        `fs` - The feature structure the iterator that supplies the comparison information. It must be of type T or a subtype of T.
      Throws:
        `ConcurrentModificationException` - if the underlying indexes being iterated over were modified

    - #### copy

          FSIterator<T> copy()

      Copy this iterator.
      Returns:
        A copy of this iterator, pointing at the same element.

Copyright © 2006–2021 The Apache Software Foundation. All rights reserved.