⇒ Index (Frames) |  ⇒ Index (No Frames) |  ⇒ Package |  ⇒ Package Tree |  ⇒ Full Tree 
org.apache.commons.collections.iterators

Class CollatingIterator

java.lang.Object
|
+--org.apache.commons.collections.iterators.CollatingIterator

All Implemented Interfaces:
Iterator


public class CollatingIterator
extends java.lang.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 next method on this iterator will return the lesser of A.next() and B.next().

Since:
Commons Collections 2.1
Authors:
Rodney Waldhoff
Stephen Colebourne

Constructor Summary

CollatingIterator()

Constructs a new CollatingIterator.

CollatingIterator(final Comparator comp)

Constructs a new CollatingIterator that will used the specified comparator for ordering.

CollatingIterator(final Comparator comp, final int initIterCapacity)

Constructs a new CollatingIterator that will used the specified comparator for ordering and have the specified initial capacity.

CollatingIterator(final Comparator comp, final Iterator a, final Iterator b)

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

CollatingIterator(final Comparator comp, final Iterator[] iterators)

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

CollatingIterator(final Comparator comp, final Collection iterators)

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

Method Summary

void

addIterator(final 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(final Comparator comp)

Sets the Comparator by which collation occurs.

void

setIterator(final int index, final Iterator iterator)

Sets the iterator at the given index.

Constructor Details

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(final Comparator comp, final 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:
- if the iterators collection is or contains null
- if the iterators collection contains an element that's not an Iterator

CollatingIterator

public CollatingIterator(final Comparator comp, final int initIterCapacity)

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(final Comparator comp, final Iterator a, final 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:
- if either iterator is null

CollatingIterator

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

CollatingIterator

public CollatingIterator(final Comparator comp)

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

Method Details

addIterator

public void addIterator(final 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:
- if iteration has started
- 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:
- 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:
- if there is no last returned element, or if the last returned element has already been removed

setComparator

public void setComparator(final Comparator comp)

Sets the Comparator by which collation occurs.

Parameters:
comp
Throws:
- if iteration has started

setIterator

public void setIterator(final int index, final 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:
- if index < 0 or index > size()
- if iteration has started
- if the iterator is null