This class provides a skeletal implementation of the 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 java.io.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.

Nested and Inner Type Summary

Modifier and Type	Class and Description
private static enum	AbstractIterator.State

Field Summary

Modifier and Type	Field and Description
private T	next
private AbstractIterator.State	state

Constructor Summary

Access	Constructor and Description
protected	AbstractIterator() Constructor for use by subclasses.

Method Summary

Modifier and Type	Method and Description
protected abstract T	Returns: the next element if there was one. If `endOfData` was called during execution, the return value will be ignored. computeNext() Returns the next element Note the implementation must call `endOfData()` when there are no elements left in the iteration.
protected final T	Returns: `null`; a convenience so your `computeNext` implementation can use the simple statement `return endOfData();` endOfData() Implementations of `computeNext` must invoke this method when there are no elements left in the iteration.
public final boolean	hasNext() Implements java.util.Iterator.hasNext. Returns `true` if the iteration has more elements.
public final T	next() Implements java.util.Iterator.next. Returns the next element in the iteration.
public final T	peek() Returns the next element in the iteration without advancing the iteration, according to the contract of `PeekingIterator#peek()`.
private boolean	tryToComputeNext()

Inherited from com.google.common.collect.UnmodifiableIterator:: remove

Field Detail

next	back to summary
private T next Annotations @CheckForNull

state	back to summary
private AbstractIterator.State state

Constructor Detail

AbstractIterator	back to summary
protected AbstractIterator() Constructor for use by subclasses.

Method Detail

computeNext back to summary

computeNext	back to summary
protected abstract T computeNext() Returns the next element Note the implementation must call `endOfData()` when there are no elements left in the iteration. Failure to do so could result in an infinite loop. The initial invocation of `hasNext()` or `next()` calls this method, as does the first invocation of `hasNext` or `next` following each successful call to `next`. Once the implementation either invokes `endOfData` 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` or `next` invocation that invoked this method. Any further attempts to use the iterator will result in an `IllegalStateException`. The implementation of this method may not invoke the `hasNext`, `next`, or `peek()` methods on this instance; if it does, an `IllegalStateException` will result. Returns:T the next element if there was one. If `endOfData` was called during execution, the return value will be ignored. Annotations @CheckForNull Exceptions RuntimeException: if any unrecoverable error happens. This exception will propagate outward to the `hasNext()`, `next()`, or `peek()` invocation that invoked this method. Any further attempts to use the iterator will result in an `IllegalStateException`.

protected abstract T computeNext()

Returns the next element

Note

the implementation must call endOfData() when there are no elements left in the iteration. Failure to do so could result in an infinite loop.

The initial invocation of hasNext() or next() calls this method, as does the first invocation of hasNext or next following each successful call to next. Once the implementation either invokes endOfData 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 or next invocation that invoked this method. Any further attempts to use the iterator will result in an IllegalStateException.

The implementation of this method may not invoke the hasNext, next, or peek() methods on this instance; if it does, an IllegalStateException will result.

Returns:T

the next element if there was one. If endOfData was called during execution, the return value will be ignored.

Annotations

@CheckForNull

Exceptions

RuntimeException:: if any unrecoverable error happens. This exception will propagate outward to the hasNext(), next(), or peek() invocation that invoked this method. Any further attempts to use the iterator will result in an IllegalStateException.

endOfData back to summary

endOfData	back to summary
protected final T endOfData() Implementations of `computeNext` must invoke this method when there are no elements left in the iteration. Returns:T `null`; a convenience so your `computeNext` implementation can use the simple statement `return endOfData();` Annotations @CanIgnoreReturnValue @CheckForNull

protected final T endOfData()

Implementations of computeNext must invoke this method when there are no elements left in the iteration.

Returns:T

null; a convenience so your computeNext implementation can use the simple statement return endOfData();

Annotations

@CanIgnoreReturnValue
@CheckForNull

hasNext back to summary

hasNext	back to summary
public final boolean hasNext() Implements java.util.Iterator.hasNext. Doc from java.util.Iterator.hasNext. Returns `true` if the iteration has more elements. (In other words, returns `true` if `next` would return an element rather than throwing an exception.) Returns:boolean `true` if the iteration has more elements Annotations @Override

public final boolean hasNext()

Implements java.util.Iterator.hasNext.

Doc from java.util.Iterator.hasNext.

Returns true if the iteration has more elements. (In other words, returns true if next would return an element rather than throwing an exception.)

Returns:boolean

true if the iteration has more elements

Annotations

@Override

next	back to summary
public final T next() Implements java.util.Iterator.next. Doc from java.util.Iterator.next. Returns the next element in the iteration. Returns:T the next element in the iteration Annotations @CanIgnoreReturnValue @Override @ParametricNullness

back to summary

public final T next()

Implements java.util.Iterator.next.

Doc from java.util.Iterator.next.

Returns the next element in the iteration.

Returns:T

the next element in the iteration

Annotations

@CanIgnoreReturnValue
@Override
@ParametricNullness

peek back to summary

peek	back to summary
public final T peek() Returns the next element in the iteration without advancing the iteration, according to the contract of `PeekingIterator#peek()`. Implementations of `AbstractIterator` that wish to expose this functionality should implement `PeekingIterator`. Annotations @ParametricNullness

public final T peek()

Returns the next element in the iteration without advancing the iteration, according to the contract of PeekingIterator#peek().

Implementations of AbstractIterator that wish to expose this functionality should implement PeekingIterator.

Annotations

@ParametricNullness

tryToComputeNext	back to summary
private boolean tryToComputeNext()

com.google.common.collect back to summary

private final Enum AbstractIterator.State

Class Inheritance

extends Enum<AbstractIterator.State>

java.lang.Object
java.lang.Enum
com.google.common.collect.AbstractIterator.State

Field Summary

Modifier and Type	Field and Description
public static final AbstractIterator.State	DONE We have reached the end of the data and are finished.
public static final AbstractIterator.State	FAILED We've suffered an exception and are kaput.
public static final AbstractIterator.State	NOT_READY We haven't yet computed or have already returned the element.
public static final AbstractIterator.State	READY We have computed the next element and haven't returned it yet.

Constructor Summary

Access	Constructor and Description
private	State()

Method Summary

Modifier and Type	Method and Description
public static AbstractIterator.State	valueOf(String name)
public static AbstractIterator.State[]	values()

Inherited from java.lang.Enum:: clone compareTo describeConstable equals finalize getDeclaringClass hashCode name ordinal toString valueOf

Field Detail

DONE	back to summary
public static final AbstractIterator.State DONE We have reached the end of the data and are finished.

FAILED	back to summary
public static final AbstractIterator.State FAILED We've suffered an exception and are kaput.

NOT_READY	back to summary
public static final AbstractIterator.State NOT_READY We haven't yet computed or have already returned the element.

READY	back to summary
public static final AbstractIterator.State READY We have computed the next element and haven't returned it yet.

Constructor Detail

State	back to summary
private State()

Method Detail

valueOf	back to summary
public static AbstractIterator.State valueOf(String name)

values	back to summary
public static AbstractIterator.State[] values()

public abstract Class AbstractIterator<T extends @Nullable Object>

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

private final Enum AbstractIterator.State

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail