Package org.apache.commons.collections.iterators

Class IteratorChain

  • All Implemented Interfaces:
    java.util.Iterator
    public class IteratorChain
extends java.lang.Object
implements java.util.Iterator
    An IteratorChain is an Iterator that wraps a number of Iterators.

    This class makes multiple iterators look like one to the caller When any method from the Iterator interface is called, the IteratorChain will delegate to a single underlying Iterator. The IteratorChain will invoke the Iterators in sequence until all Iterators are exhausted.

    Under many circumstances, linking Iterators together in this manner is more efficient (and convenient) than reading out the contents of each Iterator into a List and creating a new Iterator.

    Calling a method that adds new Iteratorafter a method in the Iterator interface has been called will result in an UnsupportedOperationException. Subclasses should take care to not alter the underlying List of Iterators.

    NOTE: As from version 3.0, the IteratorChain may contain no iterators. In this case the class will function as an empty iterator.

    Since:
    Commons Collections 2.1
    Version:
    $Revision: 647116 $ $Date: 2008-04-11 13:23:08 +0200 (Fri, 11 Apr 2008) $

    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected java.util.Iterator currentIterator
      The current iterator
      protected int currentIteratorIndex
      The index of the current iterator
      protected boolean isLocked
      ComparatorChain is "locked" after the first time compare(Object,Object) is called
      protected java.util.List iteratorChain
      The chain of iterators
      protected java.util.Iterator lastUsedIterator
      The "last used" Iterator is the Iterator upon which next() or hasNext() was most recently called used for the remove() operation only

    • Constructor Summary

      Constructors 
      Constructor Description
      IteratorChain()
      Construct an IteratorChain with no Iterators.
      IteratorChain​(java.util.Collection iterators)
      Constructs a new IteratorChain over the collection of iterators.
      IteratorChain​(java.util.Iterator iterator)
      Construct an IteratorChain with a single Iterator.
      IteratorChain​(java.util.Iterator[] iterators)
      Constructs a new IteratorChain over the array of iterators.
      IteratorChain​(java.util.Iterator a, java.util.Iterator b)
      Constructs a new IteratorChain over the two given iterators.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void addIterator​(java.util.Iterator iterator)
      Add an Iterator to the end of the chain
      private void checkLocked()
      Checks whether the iterator chain is now locked and in use.
      java.util.List getIterators()
      Get the list of Iterators (unmodifiable)
      boolean hasNext()
      Return true if any Iterator in the IteratorChain has a remaining element.
      boolean isLocked()
      Determine if modifications can still be made to the IteratorChain.
      private void lockChain()
      Lock the chain so no more iterators can be added.
      java.lang.Object next()
      Returns the next Object of the current Iterator
      void remove()
      Removes from the underlying collection the last element returned by the Iterator.
      void setIterator​(int index, java.util.Iterator iterator)
      Set the Iterator at the given index
      int size()
      Number of Iterators in the current IteratorChain.
      protected void updateCurrentIterator()
      Updates the current iterator field to ensure that the current Iterator is not exhausted

      • 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

      • iteratorChain

        protected final java.util.List iteratorChain
        The chain of iterators

      • currentIteratorIndex

        protected int currentIteratorIndex
        The index of the current iterator

      • currentIterator

        protected java.util.Iterator currentIterator
        The current iterator

      • lastUsedIterator

        protected java.util.Iterator lastUsedIterator
        The "last used" Iterator is the Iterator upon which next() or hasNext() was most recently called used for the remove() operation only

      • isLocked

        protected boolean isLocked
        ComparatorChain is "locked" after the first time compare(Object,Object) is called

    • Constructor Detail

      • IteratorChain

        public IteratorChain()
        Construct an IteratorChain with no Iterators.

        You will normally use addIterator(Iterator) to add some iterators after using this constructor.

      • IteratorChain

        public IteratorChain​(java.util.Iterator iterator)
        Construct an IteratorChain with a single Iterator.
        Parameters:
        iterator - first Iterator in the IteratorChain
        Throws:
        java.lang.NullPointerException - if the iterator is null

      • IteratorChain

        public IteratorChain​(java.util.Iterator a,
                     java.util.Iterator b)
        Constructs a new IteratorChain over the two given iterators.
        Parameters:
        a - the first child iterator
        b - the second child iterator
        Throws:
        java.lang.NullPointerException - if either iterator is null

      • IteratorChain

        public IteratorChain​(java.util.Iterator[] iterators)
        Constructs a new IteratorChain over the array of iterators.
        Parameters:
        iterators - the array of iterators
        Throws:
        java.lang.NullPointerException - if iterators array is or contains null

      • IteratorChain

        public IteratorChain​(java.util.Collection iterators)
        Constructs a new IteratorChain over the collection of iterators.
        Parameters:
        iterators - the collection of iterators
        Throws:
        java.lang.NullPointerException - if iterators collection is or contains null
        java.lang.ClassCastException - if iterators collection doesn't contain an iterator

    • Method Detail

      • addIterator

        public void addIterator​(java.util.Iterator iterator)
        Add an Iterator to the end of the chain
        Parameters:
        iterator - Iterator to add
        Throws:
        java.lang.IllegalStateException - if I've already started iterating
        java.lang.NullPointerException - if the iterator is null

      • setIterator

        public void setIterator​(int index,
                        java.util.Iterator iterator)
                 throws java.lang.IndexOutOfBoundsException
        Set 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 I've already started iterating
        java.lang.NullPointerException - if the iterator is null

      • getIterators

        public java.util.List getIterators()
        Get the list of Iterators (unmodifiable)
        Returns:
        the unmodifiable list of iterators added

      • size

        public int size()
        Number of Iterators in the current IteratorChain.
        Returns:
        Iterator count

      • isLocked

        public boolean isLocked()
        Determine if modifications can still be made to the IteratorChain. IteratorChains cannot be modified once they have executed a method from the Iterator interface.
        Returns:
        true if IteratorChain cannot be modified, false if it can

      • checkLocked

        private void checkLocked()
        Checks whether the iterator chain is now locked and in use.

      • lockChain

        private void lockChain()
        Lock the chain so no more iterators can be added. This must be called from all Iterator interface methods.

      • updateCurrentIterator

        protected void updateCurrentIterator()
        Updates the current iterator field to ensure that the current Iterator is not exhausted

      • hasNext

        public boolean hasNext()
        Return true if any Iterator in the IteratorChain has a remaining element.
        Specified by:
        hasNext in interface java.util.Iterator
        Returns:
        true if elements remain

      • next

        public java.lang.Object next()
        Returns the next Object of the current Iterator
        Specified by:
        next in interface java.util.Iterator
        Returns:
        Object from the current Iterator
        Throws:
        java.util.NoSuchElementException - if all the Iterators are exhausted

      • remove

        public void remove()
        Removes from the underlying collection the last element returned by the Iterator. As with next() and hasNext(), this method calls remove() on the underlying Iterator. Therefore, this method may throw an UnsupportedOperationException if the underlying Iterator does not support this method.
        Specified by:
        remove in interface java.util.Iterator
        Throws:
        java.lang.UnsupportedOperationException - if the remove operator is not supported by the underlying Iterator
        java.lang.IllegalStateException - if the next method has not yet been called, or the remove method has already been called after the last call to the next method.