org.apache.uima.cas
Interface FSIterator<T extends FeatureStructure>

All Superinterfaces:

Iterator<T>

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

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 features 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

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.

moveToPrevious

void moveToPrevious()

Move the iterator one element back. This may invalidate the iterator.

moveToFirst

void moveToFirst()

Move the iterator to the first element. The iterator will be valid iff the underlying collection is non-empty.

moveToLast

void moveToLast()

Move the iterator to the last element. The iterator will be valid iff the underlying collection is non-empty.

moveTo

void moveTo(FeatureStructure fs)

Move the iterator to the first features structure that is equal to fs. 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.

Parameters:

fs - The feature structure the iterator should be set to.

copy

FSIterator<T> copy()

Copy this iterator.

Returns:

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