Package org.apache.commons.collections.iterators

Class IteratorChain

java.lang.Object
org.apache.commons.collections.iterators.IteratorChain
All Implemented Interfaces:
Iterator
@Deprecated(since="2021-04-30") public class IteratorChain extends Object implements Iterator
Deprecated.
Apache Commons Collections version 3.x is being deprecated from AEMaaCS. The upgraded version 4.4 of Commons Collections is already included as replacement. Customers are advised to upgrade to this version of the library. Please note: the package name was changed to org.apache.commons.collections4. Further note that there are AEM APIs currently exposing the old collections classes; these will be updated in upcoming releases.
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

  • Constructor Summary

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

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    addIterator(Iterator iterator)
    Deprecated.
    Add an Iterator to the end of the chain
    List
    getIterators()
    Deprecated.
    Get the list of Iterators (unmodifiable)
    boolean
    hasNext()
    Deprecated.
    Return true if any Iterator in the IteratorChain has a remaining element.
    boolean
    isLocked()
    Deprecated.
    Determine if modifications can still be made to the IteratorChain.
    Object
    next()
    Deprecated.
    Returns the next Object of the current Iterator
    void
    remove()
    Deprecated.
    Removes from the underlying collection the last element returned by the Iterator.
    void
    setIterator(int index, Iterator iterator)
    Deprecated.
    Set the Iterator at the given index
    int
    size()
    Deprecated.
    Number of Iterators in the current IteratorChain.

    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 Details

    • IteratorChain

      public IteratorChain()
      Deprecated.
      Construct an IteratorChain with no Iterators.

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

    • IteratorChain

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

    • IteratorChain

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

    • IteratorChain

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

    • IteratorChain

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

  • Method Details

    • addIterator

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

    • setIterator

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

    • getIterators

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

    • size

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

    • isLocked

      public boolean isLocked()
      Deprecated.
      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

    • hasNext

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

    • next

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

    • remove

      public void remove()
      Deprecated.
      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 Iterator
      Throws:
      UnsupportedOperationException - if the remove operator is not supported by the underlying Iterator
      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.