org.apache.commons.collections.iterators
Class IteratorChain<E>

java.lang.Object
  extended by org.apache.commons.collections.iterators.IteratorChain<E>
All Implemented Interfaces:
Iterator<E>

public class IteratorChain<E>
extends Object
implements Iterator<E>

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.

Since:
Commons Collections 2.1
Version:
$Revision: 1.1.1.1 $ $Date: 2005/05/23 04:34:54 $
Author:
Morgan Delagrange, Matt Hall, John Watkinson, Stephen Colebourne

Field Summary
protected  Iterator<? extends E> 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  List<Iterator<? extends E>> iteratorChain
          The chain of iterators
protected  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
IteratorChain()
          Construct an IteratorChain with no Iterators.
IteratorChain(Collection<Iterator<? extends E>> iterators)
          Constructs a new IteratorChain over the collection of iterators.
IteratorChain(Iterator<? extends E> iterator)
          Construct an IteratorChain with a single Iterator.
IteratorChain(Iterator<? extends E>[] iterators)
          Constructs a new IteratorChain over the array of iterators.
IteratorChain(Iterator<? extends E> a, Iterator<? extends E> b)
          Constructs a new IteratorChain over the two given iterators.
 
Method Summary
 void addIterator(Iterator<? extends E> iterator)
          Add an Iterator to the end of the chain
 List<Iterator<? extends E>> 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.
 E 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<? extends E> iterator)
          Set the Iterator at the given index
 int size()
          Number of Iterators in the current IteratorChain.
protected  void updateCurrentIterator()
          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
 

Field Detail

iteratorChain

protected final List<Iterator<? extends E>> iteratorChain
The chain of iterators


currentIteratorIndex

protected int currentIteratorIndex
The index of the current iterator


currentIterator

protected Iterator<? extends E> currentIterator
The current iterator


lastUsedIterator

protected 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


isLocked

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

Constructor Detail

IteratorChain

public IteratorChain()
Construct an IteratorChain with no Iterators.

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


IteratorChain

public IteratorChain(Iterator<? extends E> iterator)
Construct an IteratorChain with a single Iterator.

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

IteratorChain

public IteratorChain(Iterator<? extends E> a,
                     Iterator<? extends E> 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

IteratorChain

public IteratorChain(Iterator<? extends E>[] 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

IteratorChain

public IteratorChain(Collection<Iterator<? extends E>> 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
Method Detail

addIterator

public void addIterator(Iterator<? extends E> 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

setIterator

public void setIterator(int index,
                        Iterator<? extends E> iterator)
                 throws IndexOutOfBoundsException
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

getIterators

public List<Iterator<? extends E>> getIterators()
Get the list of Iterators (unmodifiable)

Returns:
the unmodifiable list of iterators added

size

public int size()
Number of Iterators in the current IteratorChain.

Returns:
Iterator count

isLocked

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

updateCurrentIterator

protected 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 IteratorChain has a remaining element.

Specified by:
hasNext in interface Iterator<E>
Returns:
true if elements remain

next

public E next()
Returns the next Object of the current Iterator

Specified by:
next in interface Iterator<E>
Returns:
Object 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.


Copyright © 2005-2005 Apache Software Foundation, Matt Hall, John Watkinson. All Rights Reserved.