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

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: 646777 $ $Date: 2008-04-10 13:33:15 +0100 (Thu, 10 Apr 2008) $
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)` Adds the given `Iterator` to the iterators being collated.
`java.util.Comparator` `getComparator()` Gets the `Comparator` by which collatation occurs.
`java.util.List` `getIterators()` Gets 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)` Sets the `Comparator` by which collation occurs.
`void` `setIterator(int index, java.util.Iterator 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(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 to sort, 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 to sort, 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)

  Adds the given `Iterator` to the iterators being collated.

  Parameters:
    `iterator` - the iterator to add to the collation, must not be null
  Throws:
    `java.lang.IllegalStateException` - if iteration has started
    `java.lang.NullPointerException` - if the iterator is null

### setIterator

    public void setIterator(int index,
                            java.util.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:
    `java.lang.IndexOutOfBoundsException` - if index < 0 or index > size()
    `java.lang.IllegalStateException` - if iteration has started
    `java.lang.NullPointerException` - if the iterator is null

### getIterators

    public java.util.List getIterators()

  Gets the list of Iterators (unmodifiable).

  Returns:
    the unmodifiable list of iterators added

### getComparator

    public java.util.Comparator getComparator()

  Gets the `Comparator` by which collatation occurs.

### setComparator

    public void setComparator(java.util.Comparator comp)

  Sets the `Comparator` by which collation occurs.

  Throws:
    `java.lang.IllegalStateException` - if iteration has started

### 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-2008 The Apache Software Foundation. All Rights Reserved.