Class AbstractIterator<T>
- All Implemented Interfaces:
Iterator<T>
- Direct Known Subclasses:
Collections2.OrderedPermutationIterator,Collections2.PermutationIterator,ConsumingQueueIterator,EndpointPairIterator,StandardTable.Column.EntrySetIterator,StandardTable.ColumnKeyIterator,TreeTraverser.PostOrderIterator
Iterator interface, to make this
interface easier to implement for certain types of data sources.
Iterator requires its implementations to support querying the end-of-data status
without changing the iterator's state, using the hasNext() method. But many data sources,
such as Reader.read(), do not expose this information; the only way to discover
whether there is any data left is by trying to retrieve it. These types of data sources are
ordinarily difficult to write iterators for. But using this class, one must implement only the
computeNext() method, and invoke the endOfData() method when appropriate.
Another example is an iterator that skips over null elements in a backing iterator. This could be implemented as:
public static Iterator<String> skipNulls(final Iterator<String> in) {
return new AbstractIterator<String>() {
protected String computeNext() {
while (in.hasNext()) {
String s = in.next();
if (s != null) {
return s;
}
}
return endOfData();
}
};
}
This class supports iterators that include null elements.
- Since:
- 2.0
-
Nested Class Summary
Nested Classes -
Field Summary
Fields -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionprotected abstract TReturns the next element.protected final TImplementations ofcomputeNext()must invoke this method when there are no elements left in the iteration.final booleanhasNext()final Tnext()final Tpeek()Returns the next element in the iteration without advancing the iteration, according to the contract ofPeekingIterator.peek().private booleanMethods inherited from class com.google.common.collect.UnmodifiableIterator
removeMethods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, waitMethods inherited from interface java.util.Iterator
forEachRemaining
-
Field Details
-
state
-
next
-
-
Constructor Details
-
AbstractIterator
protected AbstractIterator()Constructor for use by subclasses.
-
-
Method Details
-
computeNext
Returns the next element. Note: the implementation must callendOfData()when there are no elements left in the iteration. Failure to do so could result in an infinite loop.The initial invocation of
hasNext()ornext()calls this method, as does the first invocation ofhasNextornextfollowing each successful call tonext. Once the implementation either invokesendOfDataor throws an exception,computeNextis guaranteed to never be called again.If this method throws an exception, it will propagate outward to the
hasNextornextinvocation that invoked this method. Any further attempts to use the iterator will result in anIllegalStateException.The implementation of this method may not invoke the
hasNext,next, orpeek()methods on this instance; if it does, anIllegalStateExceptionwill result.- Returns:
- the next element if there was one. If
endOfDatawas called during execution, the return value will be ignored. - Throws:
RuntimeException- if any unrecoverable error happens. This exception will propagate outward to thehasNext(),next(), orpeek()invocation that invoked this method. Any further attempts to use the iterator will result in anIllegalStateException.
-
endOfData
Implementations ofcomputeNext()must invoke this method when there are no elements left in the iteration.- Returns:
null; a convenience so yourcomputeNextimplementation can use the simple statementreturn endOfData();
-
hasNext
public final boolean hasNext() -
tryToComputeNext
private boolean tryToComputeNext() -
next
-
peek
Returns the next element in the iteration without advancing the iteration, according to the contract ofPeekingIterator.peek().Implementations of
AbstractIteratorthat wish to expose this functionality should implementPeekingIterator.
-