public class

CollatingIterator

extends Object
implements Iterator<E>
java.lang.Object
   ↳ org.apache.commons.collections.iterators.CollatingIterator

Class Overview

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().

Summary

Public Constructors
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.
Public Methods
void addIterator(Iterator iterator)
Adds the given Iterator to the iterators being collated.
Comparator getComparator()
Gets the Comparator by which collatation occurs.
List getIterators()
Gets the list of Iterators (unmodifiable).
boolean hasNext()
Returns true if any child iterator has remaining elements.
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(Comparator comp)
Sets the Comparator by which collation occurs.
void setIterator(int index, Iterator iterator)
Sets the iterator at the given index.
[Expand]
Inherited Methods
From class java.lang.Object
From interface java.util.Iterator

Public Constructors

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.

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(Iterator) method.

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

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(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

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

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

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

Public Methods

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

public Comparator getComparator ()

Gets the Comparator by which collatation occurs.

public List getIterators ()

Gets the list of Iterators (unmodifiable).

Returns
  • the unmodifiable list of iterators added

public boolean hasNext ()

Returns true if any child iterator has remaining elements.

Returns
  • true if this iterator has remaining elements

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

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

public void setComparator (Comparator comp)

Sets the Comparator by which collation occurs.

Throws
IllegalStateException if iteration has started

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