Package org.apache.commons.collections4.iterators

# Class LazyIteratorChain<E>

java.lang.Object
org.apache.commons.collections4.iterators.LazyIteratorChain<E>

Type Parameters:
  `E` - The type of elements in this iterator.

All Implemented Interfaces:
  `Iterator<E>`

public abstract class LazyIteratorChain<E> extends Object implements Iterator<E>
An LazyIteratorChain is an Iterator that wraps a number of Iterators in a lazy manner.

This class makes multiple iterators look like one to the caller. When any method from the Iterator interface is called, the LazyIteratorChain will delegate to a single underlying Iterator. The LazyIteratorChain will invoke the Iterators in sequence until all Iterators are exhausted.

The Iterators are provided by `nextIterator(int)` which has to be overridden by subclasses and allows to lazily create the Iterators as they are accessed:

     return new LazyIteratorChain<String>() {
         protected Iterator<String> nextIterator(int count) {
             return count == 1 ? Arrays.asList("foo", "bar").iterator() : null;
         }
     };

Once the inner Iterator's `Iterator.hasNext()` method returns false, `nextIterator(int)` will be called to obtain another iterator, and so on until `nextIterator(int)` returns null, indicating that the chain is exhausted.

NOTE: The LazyIteratorChain may contain no iterators. In this case the class will function as an empty iterator.

Since:
  4.0

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `LazyIteratorChain()`
  Constructs a new instance.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `hasNext()`
  Return true if any Iterator in the chain has a remaining element.
  `E`
  `next()`
  Returns the next element of the current Iterator
  `protected abstract Iterator<? extends E>`
  `nextIterator(int count)`
  Gets the next iterator after the previous one has been exhausted.
  `void`
  `remove()`
  Removes from the underlying collection the last element returned by the Iterator.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

  ### Methods inherited from interface java.util.Iterator

  `forEachRemaining`

- ## Constructor Details

  - ### LazyIteratorChain

    public LazyIteratorChain()
    Constructs a new instance.

- ## Method Details

  - ### hasNext

    public boolean hasNext()
    Return true if any Iterator in the chain has a remaining element.
    Specified by:
      `hasNext` in interface `Iterator<E>`
    Returns:
      true if elements remain

  - ### next

    public E next()
    Returns the next element of the current Iterator
    Specified by:
      `next` in interface `Iterator<E>`
    Returns:
      element from the current Iterator
    Throws:
      `NoSuchElementException` - if all the Iterators are exhausted

  - ### nextIterator

    protected abstract Iterator<? extends E> nextIterator(int count)
    Gets the next iterator after the previous one has been exhausted.

    This method MUST return null when there are no more iterators.

    Parameters:
      `count` - The number of time this method has been called (starts with 1)
    Returns:
      The next iterator, or null if there are no more.

  - ### remove

    public void remove()
    Removes from the underlying collection the last element returned by the Iterator.

    As with next() and hasNext(), this method calls remove() on the underlying Iterator. Therefore, this method may throw an UnsupportedOperationException if the underlying Iterator does not support this method.

    Specified by:
      `remove` in interface `Iterator<E>`
    Throws:
      `UnsupportedOperationException` - if the remove operator is not supported by the underlying Iterator
      `IllegalStateException` - if the next method has not yet been called, or the remove method has already been called after the last call to the next method.