org.apache.uima.cas

## Interface FSIterator<T extends FeatureStructure>

- All Superinterfaces:
    Iterator<T>, ListIterator<T>
  All Known Subinterfaces:
    LowLevelIterator<T>
  All Known Implementing Classes:
    FsIterator_multiple_indexes, FsIterator_singletype, FsIterator_subtypes_ordered, FsIterator_subtypes_snapshot, FSIteratorImplBase, LLUnambiguousIteratorImpl, LowLevelIterator_empty, Subiterator

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

  Iterator over feature structures.

  This iterator interface extends `ListIterator` which, in turn, extends `Iterator`. It supports all the methods of those APIs except nextIndex, previousIndex, set, and add. remove meaning is changed to mean remove the item obtained by a get() from all the indexes in this view. 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.

  If the iterator's underlying UIMA Indexes are modified, the iterator continues as if it doesn't see these modifications. Three operations cause the iterator to "see" any modifications: moveToFirst, moveToLast, and moveTo(featureStructure).

  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 Default Methods
    Modifier and Type | Method and Description
    --- | ---
    `default void` | `add(T e)`
    `FSIterator<T>` | `copy()` Copy this iterator.
    `default T` | `get()` Get the structure the iterator is pointing at.
    `T` | `getNvc()` Get the structure the iterator is pointing at.
    `default Type` | `getType()`
    `default boolean` | `hasNext()` DEFAULT implementations of Iterator interface in terms of FSIterator methods
    `default boolean` | `hasPrevious()`
    `boolean` | `isValid()` Check if this iterator is valid.
    `void` | `moveTo(FeatureStructure fs)` Move the iterator to the first Feature Structure that matches the `fs`.
    `void` | `moveToFirst()` Move the iterator to the first element.
    `void` | `moveToLast()` Move the iterator to the last element.
    `default void` | `moveToNext()` Advance the iterator.
    `void` | `moveToNextNvc()` version of moveToNext which bypasses the isValid check - call only if you've just done this check yourself
    `default void` | `moveToPrevious()` Move the iterator one element back.
    `void` | `moveToPreviousNvc()` version of moveToPrevious which bypasses the isValid check - call only if you've just done this check yourself
    `default T` | `next()`
    `default int` | `nextIndex()`
    `default T` | `nextNvc()`
    `default T` | `previous()`
    `default int` | `previousIndex()`
    `default T` | `previousNvc()`
    `default void` | `remove()` Removes from all the indexes associated with this view, the "current" Feature Structure (the one that would be returned by a "get()" operation).
    `default void` | `set(T e)`
    `default int` | `size()` return the size of the collection being iterated over, if available.
    `default Spliterator<T>` | `spliterator()` Don't use this directly, use select()...
    `default Stream<T>` | `stream()`

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

      `forEachRemaining`

- - ### Method Detail

    - #### isValid

          boolean isValid()

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

    - #### get

          default 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.

    - #### getNvc

          T getNvc()

      Get the structure the iterator is pointing at. Throws various unchecked exceptions, if the iterator is not valid
      Returns:
        The structure the iterator is pointing at.

    - #### moveToNext

          default void moveToNext()

      Advance the iterator. This may invalidate the iterator.

    - #### moveToNextNvc

          void moveToNextNvc()

      version of moveToNext which bypasses the isValid check - call only if you've just done this check yourself

    - #### moveToPrevious

          default void moveToPrevious()

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

    - #### moveToPreviousNvc

          void moveToPreviousNvc()

      version of moveToPrevious which bypasses the isValid check - call only if you've just done this check yourself

    - #### 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 matches the `fs`. First means the earliest one occurring in the index, in case multiple FSs matching the fs are in the index. If no such feature structure exists in the underlying collection, and the iterator is over a sorted index, set the iterator to the "insertion point" for `fs`, i.e., to a point where the current feature structure compares greater than `fs`, and the previous one compares less than `fs`, using this sorted index's comparator.

      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 set or bag index, or an unordered form of iteration is configured (for example using the `select` API, no ordering is present, and the moveTo operation moves to a matching item, if one exists. The match is done using the index's comparator. If none exist, the index is left if possible in some valid (but non-matching) position.

      When the iterator is over a sorted index whose keys include the typeOrder key, this can cause unexpected operation, depending on type priorities. For example, consider the Annotation Index, which includes this key. If there are many indexed instances of the type "Foo" with the same begin and end, and a moveTo operation is specified using an Annotation instance with the same begin and end, then the Foo elements might or might not be seen going forwards, depending on the relative type priorities of "Foo" and "Annotation".

      If you are not making use of typeOrdering, the "select" APIs can create iterators which will ignore the typeOrdering key when doing the moveTo operation, which will result in all the instances of type "Foo" being seen going forwards, independent of the type priorities. See the select documentation in the version 3 users guide.

      Parameters:
        `fs` - The feature structure the iterator that supplies the comparison information. It doesn't need to be in the index; it is just being used as a comparison template. It can be a supertype of T as long as it can supply the keys needed. A typical example is a subtype of Annotation, and using an annotation instance to specify the begin / end.

    - #### copy

          FSIterator<T> copy()

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

    - #### getType

          default Type getType()

      Returns:
        the type this iterator is over

    - #### hasNext

          default boolean hasNext()

      DEFAULT implementations of Iterator interface in terms of FSIterator methods
      Specified by:
        `hasNext` in interface `Iterator<T extends FeatureStructure>`
      Specified by:
        `hasNext` in interface `ListIterator<T extends FeatureStructure>`

    - #### next

          default T next()

      Specified by:
        `next` in interface `Iterator<T extends FeatureStructure>`
      Specified by:
        `next` in interface `ListIterator<T extends FeatureStructure>`

    - #### nextNvc

          default T nextNvc()

    - #### hasPrevious

          default boolean hasPrevious()

      Specified by:
        `hasPrevious` in interface `ListIterator<T extends FeatureStructure>`

    - #### previous

          default T previous()

      Specified by:
        `previous` in interface `ListIterator<T extends FeatureStructure>`

    - #### previousNvc

          default T previousNvc()

    - #### nextIndex

          default int nextIndex()

      Specified by:
        `nextIndex` in interface `ListIterator<T extends FeatureStructure>`

    - #### previousIndex

          default int previousIndex()

      Specified by:
        `previousIndex` in interface `ListIterator<T extends FeatureStructure>`

    - #### set

          default void set(T e)

      Specified by:
        `set` in interface `ListIterator<T extends FeatureStructure>`

    - #### add

          default void add(T e)

      Specified by:
        `add` in interface `ListIterator<T extends FeatureStructure>`

    - #### spliterator

          default Spliterator<T> spliterator()

      Don't use this directly, use select()... spliterator instead where possible. Otherwise, insure the FSIterator instance can support sized/subsized.
      Returns:
        a split iterator for this iterator, which has the following characteristics DISTINCT, SIZED, SUBSIZED

    - #### stream

          default Stream<T> stream()

      Returns:
        a Stream consisting of the items being iterated over by this iterator, starting from the current position.

    - #### remove

          default void remove()

      Removes from all the indexes associated with this view, the "current" Feature Structure (the one that would be returned by a "get()" operation).
      Specified by:
        `remove` in interface `Iterator<T extends FeatureStructure>`
      Specified by:
        `remove` in interface `ListIterator<T extends FeatureStructure>`
      Throws:
        `NoSuchElementException` - if the iterator is invalid.

    - #### size

          default int size()

      return the size of the collection being iterated over, if available. Because the iterator can move forwards and backwards, the size is the total size that the iterator would iterate over, starting at the first element thru the last element. This may be inefficient to compute.
      Returns:
        the size of the collection being iterated over.

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