Top Description Fields Constructors Methods
org.apache.commons.collections4.iterators

public abstract Class LazyIteratorChain<E>

extends Object
implements Iterator<E>
Class Inheritance
All Implemented Interfaces
java.util.Iterator
Imports
java.util.Iterator
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

Modifier and TypeField and Description
private int
callCounter

The number of times next() was already called.

private boolean
chainExhausted

Indicates that the Iterator chain has been exhausted.

private Iterator<? extends E>
currentIterator

The current iterator.

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 Summary

AccessConstructor and Description
public
LazyIteratorChain()

Method Summary

Modifier and TypeMethod and Description
public boolean

Returns:

true if elements remain
hasNext()

Implements java.util.Iterator.hasNext.

Return true if any Iterator in the chain has a remaining element.
public E

Returns:

element from the current Iterator
next()

Implements java.util.Iterator.next.

Returns the next element of the current Iterator
protected abstract Iterator<? extends E>

Returns:

the next iterator, or null if there are no more.
nextIterator(int
the number of time this method has been called (starts with 1)
count)

Gets the next iterator after the previous one has been exhausted.

public void
remove()

Overrides default java.util.Iterator.remove.

Removes from the underlying collection the last element returned by the Iterator.
private void
updateCurrentIterator()

Updates the current iterator field to ensure that the current Iterator is not exhausted.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

callCounterback to summary
private int callCounter

The number of times next() was already called.

chainExhaustedback to summary
private boolean chainExhausted

Indicates that the Iterator chain has been exhausted.

currentIteratorback to summary
private Iterator<? extends E> currentIterator

The current iterator.

lastUsedIteratorback to summary
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 Detail

LazyIteratorChainback to summary
public LazyIteratorChain()

Method Detail

hasNextback to summary
public boolean hasNext()

Implements java.util.Iterator.hasNext.

Return true if any Iterator in the chain has a remaining element.

Returns:boolean

true if elements remain

Annotations
@Override
nextback to summary
public E next()

Implements java.util.Iterator.next.

Returns the next element of the current Iterator

Returns:E

element from the current Iterator

Annotations
@Override
Exceptions
NoSuchElementException:
if all the Iterators are exhausted
nextIteratorback to summary
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:int

the number of time this method has been called (starts with 1)

Returns:Iterator<? extends E>

the next iterator, or null if there are no more.

removeback to summary
public void remove()

Overrides default java.util.Iterator.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.

Annotations
@Override
Exceptions
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.
updateCurrentIteratorback to summary
private void updateCurrentIterator()

Updates the current iterator field to ensure that the current Iterator is not exhausted.