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

java.lang.Object
  org.apache.commons.collections.iterators.CollatingIterator<E>

All Implemented Interfaces:

Iterator<E>

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

Provides an ordered iteration over the elements contained in a collection of ordered Iterators.

Given two ordered Iterator instances A and B, the next() method on this iterator will return the lesser of A.next() and B.next().

Since:

Commons Collections 2.1

Version:

$Revision: 1.1.1.1 $ $Date: 2005/05/23 04:34:48 $

Author:

Rodney Waldhoff, Matt Hall, John Watkinson, Stephen Colebourne

Constructor Summary

CollatingIterator()
Constructs a new CollatingIterator.

CollatingIterator(Comparator<? super E> comp)
Constructs a new CollatingIterator that will used the specified comparator for ordering.

CollatingIterator(Comparator<? super E> comp, Collection<Iterator<? extends E>> iterators)
Constructs a new CollatingIterator that will use the specified comparator to provide ordered iteration over the collection of iterators.

CollatingIterator(Comparator<? super E> comp, int initIterCapacity)
Constructs a new CollatingIterator that will used the specified comparator for ordering and have the specified initial capacity.

CollatingIterator(Comparator<? super E> comp, Iterator<? extends E>[] iterators)
Constructs a new CollatingIterator that will use the specified comparator to provide ordered iteration over the array of iterators.

CollatingIterator(Comparator<? super E> comp, Iterator<? extends E> a, Iterator<? extends E> b)
Constructs a new CollatingIterator that will use the specified comparator to provide ordered iteration over the two given iterators.

Method Summary

void	addIterator(Iterator<? extends E> iterator) Adds the given Iterator to the iterators being collated.
Comparator<? super E>	getComparator() Gets the Comparator by which collatation occurs.
List<Iterator<? extends E>>	getIterators() Gets the list of Iterators (unmodifiable).
boolean	hasNext() Returns true if any child iterator has remaining elements.
E	next() Returns the next ordered element from a child iterator.
void	remove() Removes the last returned element from the child iterator that produced it.
void	setComparator(Comparator<? super E> comp) Sets the Comparator by which collation occurs.
void	setIterator(int index, Iterator<? extends E> iterator) Sets the iterator at the given index.

Methods inherited from class java.lang.Object

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

Constructor Detail

CollatingIterator

public CollatingIterator()

Constructs a new CollatingIterator. Natural sort order will be used, and child iterators will have to be manually added using the addIterator(Iterator) method.

CollatingIterator

public CollatingIterator(Comparator<? super E> comp)

Constructs a new CollatingIterator that will used the specified comparator for ordering. Child iterators will have to be manually added using the addIterator(Iterator) method.

Parameters:

comp - the comparator to use to sort, or null to use natural sort order

CollatingIterator

public CollatingIterator(Comparator<? super E> comp,
                         int initIterCapacity)

Constructs a new CollatingIterator that will used the specified comparator for ordering and have the specified initial capacity. Child iterators will have to be manually added using the addIterator(Iterator) method.

Parameters:

comp - the comparator to use to sort, or null to use natural sort order

initIterCapacity - the initial capacity for the internal list of child iterators

CollatingIterator

public CollatingIterator(Comparator<? super E> comp,
                         Iterator<? extends E> a,
                         Iterator<? extends E> b)

Constructs a new CollatingIterator that will use the specified comparator to provide ordered iteration over the two given iterators.

Parameters:

comp - the comparator to use to sort, or null to use natural sort order

a - the first child ordered iterator

b - the second child ordered iterator

Throws:

NullPointerException - if either iterator is null

CollatingIterator

public CollatingIterator(Comparator<? super E> comp,
                         Iterator<? extends E>[] iterators)

Constructs a new CollatingIterator that will use the specified comparator to provide ordered iteration over the array of iterators.

Parameters:

comp - the comparator to use to sort, or null to use natural sort order

iterators - the array of iterators

Throws:

NullPointerException - if iterators array is or contains null

CollatingIterator

public CollatingIterator(Comparator<? super E> comp,
                         Collection<Iterator<? extends E>> iterators)

Constructs a new CollatingIterator that will use the specified comparator to provide ordered iteration over the collection of iterators.

Parameters:

comp - the comparator to use to sort, or null to use natural sort order

iterators - the collection of iterators

Throws:

NullPointerException - if the iterators collection is or contains null

ClassCastException - if the iterators collection contains an element that's not an Iterator

Method Detail

addIterator

public void addIterator(Iterator<? extends E> iterator)

Adds the given Iterator to the iterators being collated.

Parameters:

iterator - the iterator to add to the collation, must not be null

Throws:

IllegalStateException - if iteration has started

NullPointerException - if the iterator is null

setIterator

public void setIterator(int index,
                        Iterator<? extends E> iterator)

Sets 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 iteration has started

NullPointerException - if the iterator is null

getIterators

public List<Iterator<? extends E>> getIterators()

Gets the list of Iterators (unmodifiable).

Returns:

the unmodifiable list of iterators added

getComparator

public Comparator<? super E> getComparator()

Gets the Comparator by which collatation occurs.

setComparator

public void setComparator(Comparator<? super E> comp)

Sets the Comparator by which collation occurs.

Throws:

IllegalStateException - if iteration has started

hasNext

public boolean hasNext()

Returns true if any child iterator has remaining elements.

Specified by:

hasNext in interface Iterator<E>

Returns:

true if this iterator has remaining elements

next

public E next()
       throws NoSuchElementException

Returns the next ordered element from a child iterator.

Specified by:

next in interface Iterator<E>

Returns:

the next ordered element

Throws:

NoSuchElementException - if no child iterator has any more elements

remove

public void remove()

Removes the last returned element from the child iterator that produced it.

Specified by:

remove in interface Iterator<E>

Throws:

IllegalStateException - if there is no last returned element, or if the last returned element has already been removed