Class LazyIteratorChain<E>

java.lang.Object
org.apache.commons.collections4.iterators.LazyIteratorChain<E>
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 sub-classes 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
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private int
    The number of times next() was already called.
    private boolean
    Indicates that the Iterator chain has been exhausted.
    private Iterator<? extends E>
    The current iterator.
    private Iterator<? extends E>
    The "last used" Iterator is the Iterator upon which next() or hasNext() was most recently called used for the remove() operation only.
  • Constructor Summary

    Constructors
    Constructor
    Description
     
  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    Return true if any Iterator in the chain has a remaining element.
    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
    Removes from the underlying collection the last element returned by the Iterator.
    private void
    Updates the current iterator field to ensure that the current Iterator is not exhausted.

    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
  • Field Details

    • callCounter

      private int callCounter
      The number of times next() was already called.
    • chainExhausted

      private boolean chainExhausted
      Indicates that the Iterator chain has been exhausted.
    • currentIterator

      private Iterator<? extends E> currentIterator
      The current iterator.
    • lastUsedIterator

      private Iterator<? extends E> lastUsedIterator
      The "last used" Iterator is the Iterator upon which next() or hasNext() was most recently called used for the remove() operation only.
  • Constructor Details

    • LazyIteratorChain

      public LazyIteratorChain()
  • Method Details

    • 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.
    • updateCurrentIterator

      private void updateCurrentIterator()
      Updates the current iterator field to ensure that the current Iterator is not exhausted.
    • 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
    • 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.