Class AbstractIterator<T extends @Nullable java.lang.Object>
- java.lang.Object
-
- com.google.common.collect.UnmodifiableIterator<T>
-
- com.google.common.collect.AbstractIterator<T>
-
- All Implemented Interfaces:
java.util.Iterator<T>
@GwtCompatible public abstract class AbstractIterator<T extends @Nullable java.lang.Object> extends UnmodifiableIterator<T>
This class provides a skeletal implementation of theIterator
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 thehasNext()
method. But many data sources, such asReader.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 thecomputeNext()
method, and invoke theendOfData()
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
- Author:
- Kevin Bourrillion
-
-
Constructor Summary
Constructors Modifier Constructor Description protected
AbstractIterator()
Constructor for use by subclasses.
-
Method Summary
All Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description protected abstract T
computeNext()
Returns the next element.protected T
endOfData()
Implementations ofcomputeNext()
must invoke this method when there are no elements left in the iteration.boolean
hasNext()
T
next()
T
peek()
Returns the next element in the iteration without advancing the iteration, according to the contract ofPeekingIterator.peek()
.-
Methods inherited from class com.google.common.collect.UnmodifiableIterator
remove
-
-
-
-
Constructor Detail
-
AbstractIterator
protected AbstractIterator()
Constructor for use by subclasses.
-
-
Method Detail
-
computeNext
@CheckForNull protected abstract T 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 ofhasNext
ornext
following each successful call tonext
. Once the implementation either invokesendOfData
or throws an exception,computeNext
is guaranteed to never be called again.If this method throws an exception, it will propagate outward to the
hasNext
ornext
invocation 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, anIllegalStateException
will result.- Returns:
- the next element if there was one. If
endOfData
was called during execution, the return value will be ignored. - Throws:
java.lang.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
@CanIgnoreReturnValue @CheckForNull protected final T endOfData()
Implementations ofcomputeNext()
must invoke this method when there are no elements left in the iteration.- Returns:
null
; a convenience so yourcomputeNext
implementation can use the simple statementreturn endOfData();
-
hasNext
public final boolean hasNext()
-
next
@CanIgnoreReturnValue public final T next()
-
peek
public final T peek()
Returns the next element in the iteration without advancing the iteration, according to the contract ofPeekingIterator.peek()
.Implementations of
AbstractIterator
that wish to expose this functionality should implementPeekingIterator
.
-
-