Package org.apache.uima.cas

Interface FSIterator<T extends FeatureStructure>

All Superinterfaces:
Iterator<T>, ListIterator<T>
All Known Subinterfaces:
ComparableFSIterator<F>, 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

    Modifier and Type
    Method
    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()... spliterator instead where possible.
    default Stream<T>
    stream()
     

    Methods inherited from interface java.util.Iterator

    forEachRemaining

  • Method Details

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