Apache Commons Collections 4.4 · org.apache.commons.collections4.iterators.IteratorChain

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 Iterator after a method in the Iterator interface has been called will result in an UnsupportedOperationException.

Note

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

Note

As from version 4.0, the IteratorChain stores the iterators in a queue and removes any reference to them as soon as they are not used anymore. Thus the methods setIterator(Iterator) and getIterators() have been removed and size() will return the number of remaining iterators in the queue.

Modifier and Type	Field and Description
private Iterator<? extends E>	currentIterator The current iterator
private boolean	isLocked ComparatorChain is "locked" after the first time compare(Object,Object) is called
private final Queue<Iterator<? extends E>>	iteratorChain The chain of iterators
private Iterator<? extends E>	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

Access	Constructor and Description
public	IteratorChain() Construct an IteratorChain with no Iterators.
public	IteratorChain(final Iterator<? extends E> the first child iterator in the IteratorChain, not null iterator) Construct an IteratorChain with a single Iterator.
public	IteratorChain(final Iterator<? extends E> the first child iterator in the IteratorChain, not null first, final Iterator<? extends E> the second child iterator in the IteratorChain, not null second) Constructs a new `IteratorChain` over the two given iterators.
public	IteratorChain(final Iterator<? extends E>... the array of iterators, not null iteratorChain) Constructs a new `IteratorChain` over the array of iterators.
public	IteratorChain(final Collection<Iterator<? extends E>> the collection of iterators, not null iteratorChain) Constructs a new `IteratorChain` over the collection of iterators.

Method Summary

Modifier and Type	Method and Description
public void	addIterator(final Iterator<? extends E> Iterator to add iterator) Add an Iterator to the end of the chain
private void	checkLocked() Checks whether the iterator chain is now locked and in use.
public boolean	Returns: true if elements remain hasNext() Implements java.util.Iterator.hasNext. Return true if any Iterator in the IteratorChain has a remaining element.
public boolean	Returns: true if IteratorChain cannot be modified, false if it can isLocked() Determine if modifications can still be made to the IteratorChain.
private void	lockChain() Lock the chain so no more iterators can be added.
public E	Returns: Object from the current Iterator next() Implements java.util.Iterator.next. Returns the next Object of the current Iterator
public void	remove() Overrides default java.util.Iterator.remove. Removes from the underlying collection the last element returned by the Iterator.
public int	Returns: Iterator count size() Returns the remaining number of Iterators in the current IteratorChain.
protected void	updateCurrentIterator() Updates the current iterator field to ensure that the current Iterator is not exhausted

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

currentIterator	back to summary
private Iterator<? extends E> currentIterator The current iterator

isLocked	back to summary
private boolean isLocked ComparatorChain is "locked" after the first time compare(Object,Object) is called

iteratorChain	back to summary
private final Queue<Iterator<? extends E>> iteratorChain The chain of iterators

lastUsedIterator	back to summary
private Iterator<? extends E> lastUsedIterator The "last used" Iterator is the Iterator upon which next() or hasNext() was most recently called used for the remove() operation only

Constructor Detail

IteratorChain back to summary

IteratorChain	back to summary
public IteratorChain() Construct an IteratorChain with no Iterators. You will normally use `addIterator(Iterator)` to add some iterators after using this constructor.

public IteratorChain()

Construct an IteratorChain with no Iterators.

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

IteratorChain back to summary

IteratorChain	back to summary
public IteratorChain(final Iterator<? extends E> iterator) Construct an IteratorChain with a single Iterator. This method takes one iterator. The newly constructed iterator will iterate through that iterator. Thus calling this constructor on its own will have no effect other than decorating the input iterator. You will normally use `addIterator(Iterator)` to add some more iterators after using this constructor. Parameters iterator:Iterator<? extends E> the first child iterator in the IteratorChain, not null Exceptions NullPointerException: if the iterator is null

public IteratorChain(final Iterator<? extends E> iterator)

Construct an IteratorChain with a single Iterator.

This method takes one iterator. The newly constructed iterator will iterate through that iterator. Thus calling this constructor on its own will have no effect other than decorating the input iterator.

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

Parameters

iterator:Iterator<? extends E>: the first child iterator in the IteratorChain, not null

Exceptions

NullPointerException:: if the iterator is null

IteratorChain back to summary

IteratorChain	back to summary
public IteratorChain(final Iterator<? extends E> first, final Iterator<? extends E> second) Constructs a new `IteratorChain` over the two given iterators. This method takes two iterators. The newly constructed iterator will iterate through each one of the input iterators in turn. Parameters first:Iterator<? extends E> the first child iterator in the IteratorChain, not null second:Iterator<? extends E> the second child iterator in the IteratorChain, not null Exceptions NullPointerException: if either iterator is null

public IteratorChain(final Iterator<? extends E> first, final Iterator<? extends E> second)

Constructs a new IteratorChain over the two given iterators.

This method takes two iterators. The newly constructed iterator will iterate through each one of the input iterators in turn.

Parameters

first:Iterator<? extends E>: the first child iterator in the IteratorChain, not null
second:Iterator<? extends E>: the second child iterator in the IteratorChain, not null

Exceptions

NullPointerException:: if either iterator is null

IteratorChain back to summary

IteratorChain	back to summary
public IteratorChain(final Iterator<? extends E>... iteratorChain) Constructs a new `IteratorChain` over the array of iterators. This method takes an array of iterators. The newly constructed iterator will iterate through each one of the input iterators in turn. Parameters iteratorChain:Iterator<? extends E>[] the array of iterators, not null Exceptions NullPointerException: if iterators array is or contains null

public IteratorChain(final Iterator<? extends E>... iteratorChain)

Constructs a new IteratorChain over the array of iterators.

This method takes an array of iterators. The newly constructed iterator will iterate through each one of the input iterators in turn.

Parameters

iteratorChain:Iterator<? extends E>[]: the array of iterators, not null

Exceptions

NullPointerException:: if iterators array is or contains null

IteratorChain back to summary

IteratorChain	back to summary
public IteratorChain(final Collection<Iterator<? extends E>> iteratorChain) Constructs a new `IteratorChain` over the collection of iterators. This method takes a collection of iterators. The newly constructed iterator will iterate through each one of the input iterators in turn. Parameters iteratorChain:Collection<Iterator<? extends E>> the collection of iterators, not null Exceptions NullPointerException: if iterators collection is or contains null ClassCastException: if iterators collection doesn't contain an iterator

public IteratorChain(final Collection<Iterator<? extends E>> iteratorChain)

Constructs a new IteratorChain over the collection of iterators.

This method takes a collection of iterators. The newly constructed iterator will iterate through each one of the input iterators in turn.

Parameters

iteratorChain:Collection<Iterator<? extends E>>: the collection of iterators, not null

Exceptions

NullPointerException:: if iterators collection is or contains null
ClassCastException:: if iterators collection doesn't contain an iterator

Method Detail

addIterator	back to summary
public void addIterator(final Iterator<? extends E> iterator) Add an Iterator to the end of the chain Parameters iterator:Iterator<? extends E> Iterator to add Exceptions IllegalStateException: if I've already started iterating NullPointerException: if the iterator is null

addIterator

back to summary

public void addIterator(final Iterator<? extends E> iterator)

Add an Iterator to the end of the chain

Parameters

iterator:Iterator<? extends E>: Iterator to add

Exceptions

IllegalStateException:: if I've already started iterating
NullPointerException:: if the iterator is null

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

hasNext	back to summary
public boolean hasNext() Implements java.util.Iterator.hasNext. Return true if any Iterator in the IteratorChain has a remaining element. Returns:boolean true if elements remain Annotations @Override

hasNext

back to summary

public boolean hasNext()

Implements java.util.Iterator.hasNext.

Return true if any Iterator in the IteratorChain has a remaining element.

Returns:boolean

true if elements remain

Annotations

@Override

isLocked	back to summary
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:boolean true if IteratorChain cannot be modified, false if it can

isLocked

back to summary

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:boolean: true if IteratorChain cannot be modified, false if it can

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

next	back to summary
public E next() Implements java.util.Iterator.next. Returns the next Object of the current Iterator Returns:E Object from the current Iterator Annotations @Override Exceptions NoSuchElementException: if all the Iterators are exhausted

back to summary

public E next()

Implements java.util.Iterator.next.

Returns the next Object of the current Iterator

Returns:E

Object from the current Iterator

Annotations

@Override

Exceptions

NoSuchElementException:: if all the Iterators are exhausted

remove	back to summary
public void remove() Overrides default java.util.Iterator.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. Annotations @Override Exceptions 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.

remove

back to summary

public void remove()

Overrides default java.util.Iterator.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.

Annotations

@Override

Exceptions

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.

size	back to summary
public int size() Returns the remaining number of Iterators in the current IteratorChain. Returns:int Iterator count

size

back to summary

public int size()

Returns the remaining number of Iterators in the current IteratorChain.

Returns:int: Iterator count

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

public Class IteratorChain<E>

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail