Package org.apache.commons.collections.iterators

Class CollatingIterator

java.lang.Object
org.apache.commons.collections.iterators.CollatingIterator
All Implemented Interfaces:
Iterator
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 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 14:33:15 +0200 (Thu, 10 Apr 2008) $
Author:
Rodney Waldhoff, Stephen Colebourne

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

    • 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

    • 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

    • getIterators

      public List getIterators()
      Gets the list of Iterators (unmodifiable).
      Returns:
      the unmodifiable list of iterators added

    • getComparator

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

    • setComparator

      public void setComparator(Comparator comp)
      Sets the Comparator by which collation occurs.
      Throws:
      IllegalStateException - if iteration has started

    • hasNext

      public boolean hasNext()
      Returns true if any child iterator has remaining elements.
      Specified by:
      hasNext in interface Iterator
      Returns:
      true if this iterator has remaining elements

    • next

      public Object next() throws NoSuchElementException
      Returns the next ordered element from a child iterator.
      Specified by:
      next in interface 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.
      Specified by:
      remove in interface Iterator
      Throws:
      IllegalStateException - if there is no last returned element, or if the last returned element has already been removed