public class

IteratorChain

extends Object
implements Iterator<E>
java.lang.Object
   ↳ org.apache.commons.collections.iterators.IteratorChain

Class Overview

An IteratorChain is an Iterator that wraps a number of Iterators.

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

Under many circumstances, linking Iterators together in this manner is more efficient (and convenient) than reading out the contents of each Iterator into a List and creating a new Iterator.

Calling a method that adds new Iteratorafter a method in the Iterator interface has been called will result in an UnsupportedOperationException. Subclasses should take care to not alter the underlying List of Iterators.

NOTE: As from version 3.0, the IteratorChain may contain no iterators. In this case the class will function as an empty iterator.

Summary

Fields
protected Iterator currentIterator The current iterator
protected int currentIteratorIndex The index of the current iterator
protected boolean isLocked ComparatorChain is "locked" after the first time compare(Object,Object) is called
protected final List iteratorChain The chain of iterators
protected Iterator lastUsedIterator The "last used" Iterator is the Iterator upon which next() or hasNext() was most recently called used for the remove() operation only
Public Constructors
IteratorChain()
Construct an IteratorChain with no Iterators.
IteratorChain(Iterator iterator)
Construct an IteratorChain with a single Iterator.
IteratorChain(Iterator a, Iterator b)
Constructs a new IteratorChain over the two given iterators.
IteratorChain(Iterator[] iterators)
Constructs a new IteratorChain over the array of iterators.
IteratorChain(Collection iterators)
Constructs a new IteratorChain over the collection of iterators.
Public Methods
void addIterator(Iterator iterator)
Add an Iterator to the end of the chain
List getIterators()
Get the list of Iterators (unmodifiable)
boolean hasNext()
Return true if any Iterator in the IteratorChain has a remaining element.
boolean isLocked()
Determine if modifications can still be made to the IteratorChain.
Object next()
Returns the next Object of the current Iterator
void remove()
Removes from the underlying collection the last element returned by the Iterator.
void setIterator(int index, Iterator iterator)
Set the Iterator at the given index
int size()
Number of Iterators in the current IteratorChain.
Protected Methods
void updateCurrentIterator()
Updates the current iterator field to ensure that the current Iterator is not exhausted
[Expand]
Inherited Methods
From class java.lang.Object
From interface java.util.Iterator

Fields

protected Iterator currentIterator

The current iterator

protected int currentIteratorIndex

The index of the current iterator

protected boolean isLocked

ComparatorChain is "locked" after the first time compare(Object,Object) is called

protected final List iteratorChain

The chain of iterators

protected Iterator lastUsedIterator

The "last used" Iterator is the Iterator upon which next() or hasNext() was most recently called used for the remove() operation only

Public Constructors

public IteratorChain ()

Construct an IteratorChain with no Iterators.

You will normally use addIterator(Iterator) to add some iterators after using this constructor.

public IteratorChain (Iterator iterator)

Construct an IteratorChain with a single Iterator.

Parameters
iterator first Iterator in the IteratorChain
Throws
NullPointerException if the iterator is null

public IteratorChain (Iterator a, Iterator b)

Constructs a new IteratorChain over the two given iterators.

Parameters
a the first child iterator
b the second child iterator
Throws
NullPointerException if either iterator is null

public IteratorChain (Iterator[] iterators)

Constructs a new IteratorChain over the array of iterators.

Parameters
iterators the array of iterators
Throws
NullPointerException if iterators array is or contains null

public IteratorChain (Collection iterators)

Constructs a new IteratorChain over the collection of iterators.

Parameters
iterators the collection of iterators
Throws
NullPointerException if iterators collection is or contains null
ClassCastException if iterators collection doesn't contain an iterator

Public Methods

public void addIterator (Iterator iterator)

Add an Iterator to the end of the chain

Parameters
iterator Iterator to add
Throws
IllegalStateException if I've already started iterating
NullPointerException if the iterator is null

public List getIterators ()

Get the list of Iterators (unmodifiable)

Returns
  • the unmodifiable list of iterators added

public boolean hasNext ()

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

Returns
  • true if elements remain

public boolean isLocked ()

Determine if modifications can still be made to the IteratorChain. IteratorChains cannot be modified once they have executed a method from the Iterator interface.

Returns
  • true if IteratorChain cannot be modified, false if it can

public Object next ()

Returns the next Object of the current Iterator

Returns
  • Object from the current Iterator
Throws
NoSuchElementException if all the Iterators are exhausted

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.

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.

public void setIterator (int index, Iterator iterator)

Set the Iterator at the given index

Parameters
index index of the Iterator to replace
iterator Iterator to place at the given index
Throws
IndexOutOfBoundsException if index < 0 or index > size()
IllegalStateException if I've already started iterating
NullPointerException if the iterator is null

public int size ()

Number of Iterators in the current IteratorChain.

Returns
  • Iterator count

Protected Methods

protected void updateCurrentIterator ()

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