## org.apache.commons.collections.iterators
Class IteratorChain

    java.lang.Object
      org.apache.commons.collections.iterators.IteratorChain

All Implemented Interfaces:
  Iterator

public class IteratorChain
extends Object
implements Iterator

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.13 $ $Date: 2004/05/26 21:58:02 $
Author:
  Morgan Delagrange, Stephen Colebourne

Field Summary
`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 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

Constructor Summary
`IteratorChain()` Construct an IteratorChain with no Iterators.
`IteratorChain(Collection iterators)` Constructs a new `IteratorChain` over the collection of iterators.
`IteratorChain(Iterator iterator)` Construct an IteratorChain with a single Iterator.
`IteratorChain(Iterator[] iterators)` Constructs a new `IteratorChain` over the array of iterators.
`IteratorChain(Iterator a, Iterator b)` Constructs a new `IteratorChain` over the two given iterators.

Method Summary
`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 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 iteratorChain

  The chain of iterators

### currentIteratorIndex

    protected int currentIteratorIndex

  The index of the current iterator

### currentIterator

    protected Iterator currentIterator

  The current iterator

### lastUsedIterator

    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

### 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 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 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

### IteratorChain

    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

### IteratorChain

    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

Method Detail

### addIterator

    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

### setIterator

    public void setIterator(int index,
                            Iterator 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 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`
  Returns:
    true if elements remain

### next

    public Object next()

  Returns the next Object of the current Iterator

  Specified by:
    `next` in interface `Iterator`
  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`
  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 © 2001-2005 Apache Software Foundation. All Rights Reserved.