org.apache.commons.collections.iterators
Class CollatingIterator

java.lang.Object
  |
  +--org.apache.commons.collections.iterators.CollatingIterator
All Implemented Interfaces:
java.util.Iterator

public class CollatingIterator
extends java.lang.Object
implements java.util.Iterator

Provides an ordered iteration over the elements contained in a collection of ordered Iterators. In other words, given two ordered Iterators A and B, my next() method will return the lesser of A.next() and B.next().

Since:
2.1
Version:
$Revision: 1.3.2.1 $ $Date: 2004/05/22 12:14:04 $
Author:
Rodney Waldhoff, Stephen Colebourne

Constructor Summary
CollatingIterator()
          Constructs a new CollatingIterator.
CollatingIterator(java.util.Comparator comp)
          Constructs a new CollatingIterator that will used the specified comparator for ordering.
CollatingIterator(java.util.Comparator comp, java.util.Collection iterators)
          Constructs a new CollatingIterator that will use the specified comparator to provide ordered iteration over the collection of iterators.
CollatingIterator(java.util.Comparator comp, int initIterCapacity)
          Constructs a new CollatingIterator that will used the specified comparator for ordering and have the specified initial capacity.
CollatingIterator(java.util.Comparator comp, java.util.Iterator[] iterators)
          Constructs a new CollatingIterator that will use the specified comparator to provide ordered iteration over the array of iterators.
CollatingIterator(java.util.Comparator comp, java.util.Iterator a, java.util.Iterator b)
          Constructs a new CollatingIterator that will use the specified comparator to provide ordered iteration over the two given iterators.
 
Method Summary
 void addIterator(java.util.Iterator iterator)
          Add the given Iterator to my collection to collate.
 java.util.Comparator getComparator()
          Get the Comparator by which I collate.
 java.util.List getIterators()
          Get the list of Iterators (unmodifiable)
 boolean hasNext()
          Returns true if any child iterator has remaining elements.
 java.lang.Object 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(java.util.Comparator comp)
          Set the Comparator by which I collate.
 void setIterator(int index, java.util.Iterator iterator)
          Set the Iterator at the given index
 
Methods inherited from class java.lang.Object
equals, 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(java.util.Comparator 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 for ordering, or null to use natural sort order

CollatingIterator

public CollatingIterator(java.util.Comparator 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 for ordering, or null to use natural sort order
initIterCapacity - the initial capacity for the internal list of child iterators

CollatingIterator

public CollatingIterator(java.util.Comparator comp,
                         java.util.Iterator a,
                         java.util.Iterator 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:
java.lang.NullPointerException - if either iterator is null

CollatingIterator

public CollatingIterator(java.util.Comparator comp,
                         java.util.Iterator[] 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:
java.lang.NullPointerException - if iterators array is or contains null

CollatingIterator

public CollatingIterator(java.util.Comparator comp,
                         java.util.Collection 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:
java.lang.NullPointerException - if the iterators collection is or contains null
java.lang.ClassCastException - if the iterators collection contains an element that's not an Iterator
Method Detail

addIterator

public void addIterator(java.util.Iterator iterator)
Add the given Iterator to my collection to collate.

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

setComparator

public void setComparator(java.util.Comparator comp)
Set the Comparator by which I collate.

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

getComparator

public java.util.Comparator getComparator()
Get the Comparator by which I collate.


hasNext

public boolean hasNext()
Returns true if any child iterator has remaining elements.

Specified by:
hasNext in interface java.util.Iterator
Returns:
true if this iterator has remaining elements

next

public java.lang.Object next()
                      throws java.util.NoSuchElementException
Returns the next ordered element from a child iterator.

Specified by:
next in interface java.util.Iterator
Returns:
the next ordered element
Throws:
java.util.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 java.util.Iterator
Throws:
java.lang.IllegalStateException - if there is no last returned element, or if the last returned element has already been removed


Copyright © 2001-2004 The Apache Software Foundation. All Rights Reserved.