Package org.apache.commons.collections4.iterators

Class CollatingIterator<E>

  • All Implemented Interfaces:
    java.util.Iterator<E>
    public class CollatingIterator<E>
extends java.lang.Object
implements java.util.Iterator<E>
    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:
    2.1

    • Constructor Summary

      Constructors 
      Constructor Description
      CollatingIterator()
      Constructs a new CollatingIterator.
      CollatingIterator​(java.util.Comparator<? super E> comp)
      Constructs a new CollatingIterator that will used the specified comparator for ordering.
      CollatingIterator​(java.util.Comparator<? super E> 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<? super E> comp, java.util.Collection<java.util.Iterator<? extends E>> iterators)
      Constructs a new CollatingIterator that will use the specified comparator to provide ordered iteration over the collection of iterators.
      CollatingIterator​(java.util.Comparator<? super E> comp, java.util.Iterator<? extends E>[] iterators)
      Constructs a new CollatingIterator that will use the specified comparator to provide ordered iteration over the array of iterators.
      CollatingIterator​(java.util.Comparator<? super E> comp, java.util.Iterator<? extends E> a, java.util.Iterator<? extends E> 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<? extends E> iterator)
      Adds the given Iterator to the iterators being collated.
      java.util.Comparator<? super E> getComparator()
      Gets the Comparator by which collatation occurs.
      int getIteratorIndex()
      Returns the index of the iterator that returned the last element.
      java.util.List<java.util.Iterator<? extends E>> getIterators()
      Gets the list of Iterators (unmodifiable).
      boolean hasNext()
      Returns true if any child iterator has remaining elements.
      E 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<? super E> comp)
      Sets the Comparator by which collation occurs.
      void setIterator​(int index, java.util.Iterator<? extends E> iterator)
      Sets the iterator at the given index.

      • Methods inherited from class java.lang.Object

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

      • Methods inherited from interface java.util.Iterator

        forEachRemaining

    • Constructor Detail

      • CollatingIterator

        public CollatingIterator​(java.util.Comparator<? super E> 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; must not be null, unless you'll be invoking setComparator(Comparator) later on.

      • CollatingIterator

        public CollatingIterator​(java.util.Comparator<? super E> 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; must not be null, unless you'll be invoking setComparator(Comparator) later on.
        initIterCapacity - the initial capacity for the internal list of child iterators

      • CollatingIterator

        public CollatingIterator​(java.util.Comparator<? super E> comp,
                         java.util.Iterator<? extends E> a,
                         java.util.Iterator<? extends E> 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; must not be null, unless you'll be invoking setComparator(Comparator) later on.
        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<? super E> comp,
                         java.util.Iterator<? extends E>[] 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; must not be null, unless you'll be invoking setComparator(Comparator) later on.
        iterators - the array of iterators
        Throws:
        java.lang.NullPointerException - if iterators array is or contains null

      • CollatingIterator

        public CollatingIterator​(java.util.Comparator<? super E> comp,
                         java.util.Collection<java.util.Iterator<? extends E>> 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; must not be null, unless you'll be invoking setComparator(Comparator) later on.
        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<? extends E> 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<? extends E> 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<java.util.Iterator<? extends E>> getIterators()
        Gets the list of Iterators (unmodifiable).
        Returns:
        the unmodifiable list of iterators added

      • getComparator

        public java.util.Comparator<? super E> getComparator()
        Gets the Comparator by which collatation occurs.
        Returns:
        the Comparator

      • setComparator

        public void setComparator​(java.util.Comparator<? super E> comp)
        Sets the Comparator by which collation occurs. If you would like to use the natural sort order (or, in other words, if the elements in the iterators are implementing the Comparable interface), then use the ComparableComparator.
        Parameters:
        comp - the Comparator to set
        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<E>
        Returns:
        true if this iterator has remaining elements

      • next

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

      • getIteratorIndex

        public int getIteratorIndex()
        Returns the index of the iterator that returned the last element.
        Returns:
        the index of the iterator that returned the last element
        Throws:
        java.lang.IllegalStateException - if there is no last returned element