Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.google.common.collect
Class AbstractIterator<T>

    java.lang.Object
      com.google.common.collect.UnmodifiableIterator<T>
          com.google.common.collect.AbstractIterator<T>

All Implemented Interfaces:
  Iterator<T>

    public abstract class AbstractIterator<T>

extends UnmodifiableIterator<T>

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 `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.

Author:
  Kevin Bourrillion

Constructor Summary
`AbstractIterator()`

Method Summary
`protected abstract T` | `computeNext()` Returns the next element.
`protected T` | `endOfData()` Implementations of `computeNext` must invoke this method when there are no elements left in the iteration.
`boolean` | `hasNext()` Returns `true` if the iteration has more elements.
`T` | `next()` Returns the next element in the iteration.
`T` | `peek()` Returns the next element in the iteration without advancing the iteration, according to the contract of `PeekingIterator.peek()`.

Methods inherited from class com.google.common.collect.UnmodifiableIterator
`remove`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### AbstractIterator

    public AbstractIterator()

Method Detail

### computeNext

    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:
    the next element if there was one. If `endOfData` was called during execution, the return value will be ignored.
  Throws:
    `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

    protected final T endOfData()

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

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

### hasNext

    public final boolean hasNext()

  Description copied from interface: `java.util.Iterator`
  Returns `true` if the iteration has more elements. (In other words, returns `true` if `Iterator.next()` would return an element rather than throwing an exception.)

  Returns:
    `true` if the iteration has more elements

### next

    public final T next()

  Description copied from interface: `java.util.Iterator`
  Returns the next element in the iteration.

  Returns:
    the next element in the iteration

### peek

    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`.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD