Package org.apache.commons.collections.iterators

Class 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 14:33:15 +0200 (Thu, 10 Apr 2008) $

    • Field Summary

      Fields 
      Modifier and Type Field Description
      private java.util.Comparator comparator
      The Comparator used to evaluate order.
      private java.util.ArrayList iterators
      The list of Iterators to evaluate.
      private int lastReturned
      Index of the iterator from whom the last returned value was obtained.
      private java.util.ArrayList values
      Next objects peeked from each iterator.
      private java.util.BitSet valueSet
      Whether or not each values element has been set.

    • Constructor Summary

      Constructors 
      Constructor Description
      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, 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.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, 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

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void addIterator​(java.util.Iterator iterator)
      Adds the given Iterator to the iterators being collated.
      private boolean anyHasNext​(java.util.ArrayList iters)
      Returns true iff any Iterator in the given list has a next value.
      private boolean anyValueSet​(java.util.BitSet set)
      Returns true iff any bit in the given set is true.
      private void checkNotStarted()
      Throws IllegalStateException if iteration has started via start().
      private void clear​(int i)
      Clears the values and valueSet attributes at position i.
      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.
      private int least()
      Returns the index of the least element in values, setting any uninitialized values.
      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.
      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.
      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.
      private void start()
      Initializes the collating state if it hasn't been already.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

      • Methods inherited from interface java.util.Iterator

        forEachRemaining

    • Field Detail

      • comparator

        private java.util.Comparator comparator
        The Comparator used to evaluate order.

      • iterators

        private java.util.ArrayList iterators
        The list of Iterators to evaluate.

      • values

        private java.util.ArrayList values
        Next objects peeked from each iterator.

      • valueSet

        private java.util.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 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

      • 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 java.lang.IllegalStateException
        Throws IllegalStateException if iteration has started via start().
        Throws:
        java.lang.IllegalStateException - if iteration started

      • least

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

      • anyValueSet

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

      • anyHasNext

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