org.apache.commons.collections.iterators
Class IteratorChain

java.lang.Object
  |
  +--org.apache.commons.collections.iterators.IteratorChain

All Implemented Interfaces:

java.util.Iterator

public class IteratorChain

extends java.lang.Object

implements java.util.Iterator

An IteratorChain is an Iterator that wraps one or more Iterators. When any method from the Iterator interface is called, the IteratorChain will proxy to a single underlying Iterator. The IteratorChain will invoke the Iterators in sequence until all Iterators are exhausted completely.

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.

Since:

2.1

Version:

$Id: IteratorChain.java,v 1.2.2.1 2004/05/22 12:14:04 scolebourne Exp $

Author:

Morgan Delagrange, Stephen Colebourne

Constructor Summary

IteratorChain()
Construct an IteratorChain with no Iterators.

IteratorChain(java.util.Collection iterators)
Constructs a new IteratorChain over the collection of iterators.

IteratorChain(java.util.Iterator iterator)
Construct an IteratorChain with a single Iterator.

IteratorChain(java.util.Iterator[] iterators)
Constructs a new IteratorChain over the array of iterators.

IteratorChain(java.util.Iterator a, java.util.Iterator b)
Constructs a new IteratorChain over the two given iterators.

Method Summary

void	addIterator(java.util.Iterator iterator) Add an Iterator to the end of the chain
java.util.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.
java.lang.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, java.util.Iterator iterator) Set the Iterator at the given index
int	size() Number of Iterators in the current IteratorChain.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

IteratorChain

public IteratorChain()

Construct an IteratorChain with no Iterators. You must add at least Iterator before calling any method from the Iterator interface, or an UnsupportedOperationException is thrown

IteratorChain

public IteratorChain(java.util.Iterator iterator)

Construct an IteratorChain with a single Iterator.

Parameters:

iterator - first Iterator in the IteratorChain

Throws:

java.lang.NullPointerException - if the iterator is null

IteratorChain

public IteratorChain(java.util.Iterator a,
                     java.util.Iterator b)

Constructs a new IteratorChain over the two given iterators.

Parameters:

a - the first child iterator

b - the second child iterator

Throws:

java.lang.NullPointerException - if either iterator is null

IteratorChain

public IteratorChain(java.util.Iterator[] iterators)

Constructs a new IteratorChain over the array of iterators.

Parameters:

iterators - the array of iterators

Throws:

java.lang.NullPointerException - if iterators array is or contains null

IteratorChain

public IteratorChain(java.util.Collection iterators)

Constructs a new IteratorChain over the collection of iterators.

Parameters:

iterators - the collection of iterators

Throws:

java.lang.NullPointerException - if iterators collection is or contains null

java.lang.ClassCastException - if iterators collection doesn't contain an iterator

Method Detail

addIterator

public void addIterator(java.util.Iterator iterator)

Add an Iterator to the end of the chain

Parameters:

iterator - Iterator to add

Throws:

java.lang.IllegalStateException - if I've already started iterating

java.lang.NullPointerException - if the iterator is null

setIterator

public void setIterator(int index,
                        java.util.Iterator iterator)
                 throws java.lang.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:

java.lang.IndexOutOfBoundsException - if index < 0 or index > size()

java.lang.IllegalStateException - if I've already started iterating

java.lang.NullPointerException - if the iterator is null

getIterators

public java.util.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 = IteratorChain cannot be modified; false = IteratorChain can still be modified.

hasNext

public boolean hasNext()
                throws java.lang.UnsupportedOperationException

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

Specified by:

hasNext in interface java.util.Iterator

Returns:

true if elements remain

Throws:

java.lang.UnsupportedOperationException - if the IteratorChain does not contain at least one Iterator

next

public java.lang.Object next()
                      throws java.util.NoSuchElementException,
                             java.lang.UnsupportedOperationException

Returns the next Object of the current Iterator

Specified by:

next in interface java.util.Iterator

Returns:

Object from the current Iterator

Throws:

java.util.NoSuchElementException - if all the Iterators are exhausted

java.lang.UnsupportedOperationException - if the IteratorChain does not contain at least one Iterator

remove

public void remove()
            throws java.lang.UnsupportedOperationException,
                   java.lang.IllegalStateException

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

Throws:

java.lang.UnsupportedOperationException - if the remove operator is not supported by the underlying Iterator or if there are no Iterators in the IteratorChain

java.lang.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.