org.apache.commons.collections.iterators

Class IteratorChain

Implemented Interfaces:
Iterator

public class IteratorChain
extends java.lang.Object
implements 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.

Version:
$Id: IteratorChain.java,v 1.2.2.1 2004/05/22 12:14:04 scolebourne Exp $
Authors:
Morgan Delagrange
Stephen Colebourne
Since:
2.1

Field Summary

protected Iterator
currentIterator
protected int
currentIteratorIndex
protected boolean
isLocked
protected List
iteratorChain
protected Iterator
lastUsedIterator

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 a, Iterator b)
Constructs a new IteratorChain over the two given iterators.
IteratorChain(Iterator[] iterators)
Constructs a new IteratorChain over the array of 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()

Field Details

currentIterator

protected Iterator currentIterator

currentIteratorIndex

protected int currentIteratorIndex

isLocked

protected boolean isLocked

iteratorChain

protected final List iteratorChain

lastUsedIterator

protected Iterator lastUsedIterator

Constructor Details

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(Collection iterators)
Constructs a new IteratorChain over the collection of iterators.
Parameters:
iterators - the collection of iterators

IteratorChain

public IteratorChain(Iterator iterator)
Construct an IteratorChain with a single Iterator.
Parameters:
iterator - first Iterator in the IteratorChain

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

IteratorChain

public IteratorChain(Iterator[] iterators)
Constructs a new IteratorChain over the array of iterators.
Parameters:
iterators - the array of iterators

Method Details

addIterator

public void addIterator(Iterator iterator)
Add an Iterator to the end of the chain
Parameters:
iterator - Iterator to add

getIterators

public List getIterators()
Get the list of Iterators (unmodifiable)
Returns:
the unmodifiable list of iterators added

hasNext

public boolean hasNext()
            throws UnsupportedOperationException
Return true if any Iterator in the IteratorChain has a remaining element.
Returns:
true if elements remain

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.

next

public Object next()
            throws NoSuchElementException,
                   UnsupportedOperationException
Returns the next Object of the current Iterator
Returns:
Object from the current Iterator

remove

public void remove()
            throws UnsupportedOperationException,
                   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.

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

size

public int size()
Number of Iterators in the current IteratorChain.
Returns:
Iterator count

updateCurrentIterator

protected void updateCurrentIterator()

Copyright © 2001-2004 Apache Software Foundation. Documenation generated ${TODAY}.