Package org.apache.commons.collections.iterators

Class 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 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​(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 Detail

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

      • 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

      • 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