Interface FSIterator<T extends FeatureStructure>
-
- All Superinterfaces:
java.util.Iterator<T>
,java.util.ListIterator<T>
- All Known Subinterfaces:
ComparableFSIterator<F>
,LowLevelIterator<T>
- All Known Implementing Classes:
FilteredIterator
,FsIterator_aggregation_common
,FsIterator_backwards
,FsIterator_bag
,FsIterator_bag_pear
,FsIterator_limited
,FsIterator_multiple_indexes
,FsIterator_set_sorted_pear
,FsIterator_set_sorted2
,FsIterator_singletype
,FsIterator_subtypes_ordered
,FsIterator_subtypes_snapshot
,FSIteratorImplBase
,LLUnambiguousIteratorImpl
,LowLevelIterator_empty
,SelectFSs_impl.SelectFSIterator
,Subiterator
public interface FSIterator<T extends FeatureStructure> extends java.util.ListIterator<T>
Iterator over feature structures.This iterator interface extends
ListIterator
which, in turn, extendsIterator
. 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()
andhasNext()
. 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 methodsget()
,moveToNext()
,moveToPrevious()
methods. With these methods, retrieving the current element (get
) is a separate operation from moving the iterator (moveToNext
andmoveToPrevious
. 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 tonext()
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()
ormoveToPrevious()
is undefined. For example, if a previously valid iterator is invalidated by a call tomoveToNext()
, a subsequent call tomoveToPrevious()
is not guaranteed to set the iterator back to the last element in the collection. Always usemoveToLast()
in such cases.
-
-
Method Summary
All Methods Instance Methods Abstract Methods Default Methods 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 methodsdefault boolean
hasPrevious()
boolean
isValid()
Check if this iterator is valid.void
moveTo(FeatureStructure fs)
Move the iterator to the first Feature Structure that matches thefs
.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 yourselfdefault 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 yourselfdefault 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 java.util.Spliterator<T>
spliterator()
Don't use this directly, use select()...default java.util.stream.Stream<T>
stream()
-
-
-
Method Detail
-
isValid
boolean isValid()
Check if this iterator is valid.- Returns:
true
if the iterator is valid.
-
get
default T get() throws java.util.NoSuchElementException
Get the structure the iterator is pointing at.- Returns:
- The structure the iterator is pointing at.
- Throws:
java.util.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:
java.util.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 thefs
. 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" forfs
, i.e., to a point where the current feature structure compares greater thanfs
, and the previous one compares less thanfs
, 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 interfacejava.util.Iterator<T extends FeatureStructure>
- Specified by:
hasNext
in interfacejava.util.ListIterator<T extends FeatureStructure>
-
next
default T next()
- Specified by:
next
in interfacejava.util.Iterator<T extends FeatureStructure>
- Specified by:
next
in interfacejava.util.ListIterator<T extends FeatureStructure>
-
nextNvc
default T nextNvc()
-
hasPrevious
default boolean hasPrevious()
- Specified by:
hasPrevious
in interfacejava.util.ListIterator<T extends FeatureStructure>
-
previous
default T previous()
- Specified by:
previous
in interfacejava.util.ListIterator<T extends FeatureStructure>
-
previousNvc
default T previousNvc()
-
nextIndex
default int nextIndex()
- Specified by:
nextIndex
in interfacejava.util.ListIterator<T extends FeatureStructure>
-
previousIndex
default int previousIndex()
- Specified by:
previousIndex
in interfacejava.util.ListIterator<T extends FeatureStructure>
-
set
default void set(T e)
- Specified by:
set
in interfacejava.util.ListIterator<T extends FeatureStructure>
-
add
default void add(T e)
- Specified by:
add
in interfacejava.util.ListIterator<T extends FeatureStructure>
-
spliterator
default java.util.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 java.util.stream.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 interfacejava.util.Iterator<T extends FeatureStructure>
- Specified by:
remove
in interfacejava.util.ListIterator<T extends FeatureStructure>
- Throws:
java.util.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.
-
-