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) $

  • Field Details

    • comparator

      private Comparator comparator
      The Comparator used to evaluate order.

    • iterators

      private ArrayList iterators
      The list of Iterators to evaluate.

    • values

      private ArrayList values
      Next objects peeked from each iterator.

    • valueSet

      private BitSet valueSet
      Whether or not each values element has been set.

    • lastReturned

      private int lastReturned
      Index of the iterator from whom the last returned value was obtained.

  • 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

    • start

      private void start()
      Initializes the collating state if it hasn't been already.

    • set

      private boolean set(int i)
      Sets the values and valueSet attributes at position i to the next value of the iterator at position i, or clear them if the ith iterator has no next value.
      Returns:
      false iff there was no value to set

    • clear

      private void clear(int i)
      Clears the values and valueSet attributes at position i.

    • checkNotStarted

      private void checkNotStarted() throws IllegalStateException
      Throws IllegalStateException if iteration has started via start().
      Throws:
      IllegalStateException - if iteration started

    • least

      private int least()
      Returns the index of the least element in values, setting any uninitialized values.
      Throws:
      IllegalStateException

    • anyValueSet

      private boolean anyValueSet(BitSet set)
      Returns true iff any bit in the given set is true.

    • anyHasNext

      private boolean anyHasNext(ArrayList iters)
      Returns true iff any Iterator in the given list has a next value.