org.apache.commons.collections.iterators

Class CollatingIterator

public class CollatingIterator extends Object implements Iterator

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

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

Since: Commons Collections 2.1

Version: $Revision: 155406 $ $Date: 2005-02-26 12:55:26 +0000 (Sat, 26 Feb 2005) $

Author: Rodney Waldhoff Stephen Colebourne

Constructor Summary
CollatingIterator()
Constructs a new CollatingIterator.
CollatingIterator(Comparator comp)
Constructs a new CollatingIterator that will used the specified comparator for ordering.
CollatingIterator(Comparator comp, int initIterCapacity)
Constructs a new CollatingIterator that will used the specified comparator for ordering and have the specified initial capacity.
CollatingIterator(Comparator comp, Iterator a, Iterator b)
Constructs a new CollatingIterator that will use the specified comparator to provide ordered iteration over the two given iterators.
CollatingIterator(Comparator comp, Iterator[] iterators)
Constructs a new CollatingIterator that will use the specified comparator to provide ordered iteration over the array of iterators.
CollatingIterator(Comparator comp, Collection iterators)
Constructs a new CollatingIterator that will use the specified comparator to provide ordered iteration over the collection of iterators.
Method Summary
voidaddIterator(Iterator iterator)
Adds the given Iterator to the iterators being collated.
ComparatorgetComparator()
Gets the Comparator by which collatation occurs.
ListgetIterators()
Gets the list of Iterators (unmodifiable).
booleanhasNext()
Returns true if any child iterator has remaining elements.
Objectnext()
Returns the next ordered element from a child iterator.
voidremove()
Removes the last returned element from the child iterator that produced it.
voidsetComparator(Comparator comp)
Sets the Comparator by which collation occurs.
voidsetIterator(int index, Iterator iterator)
Sets the iterator at the given index.

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 method.

CollatingIterator

public CollatingIterator(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 method.

Parameters: comp the comparator to use to sort, or null to use natural sort order

CollatingIterator

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

CollatingIterator

public CollatingIterator(Comparator comp, 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: NullPointerException if iterators array is or contains null

CollatingIterator

public CollatingIterator(Comparator comp, 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: 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 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

getComparator

public Comparator getComparator()
Gets the Comparator by which collatation occurs.

getIterators

public List getIterators()
Gets the list of Iterators (unmodifiable).

Returns: the unmodifiable list of iterators added

hasNext

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

Returns: true if this iterator has remaining elements

next

public Object next()
Returns the next ordered element from a child iterator.

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.

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

setComparator

public void setComparator(Comparator comp)
Sets the Comparator by which collation occurs.

Throws: IllegalStateException if iteration has started

setIterator

public void setIterator(int index, Iterator 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

Copyright © 2001-2008 Apache Software Foundation. All Rights Reserved.