org.xshare.base.iterator
Class GlueingIterator

java.lang.Object
  |
  +--org.xshare.base.iterator.GlueingIterator

All Implemented Interfaces:

java.util.Iterator

public final class GlueingIterator

extends java.lang.Object

implements java.util.Iterator

This iterator allows to concatenate two or more iterators and to handle them like a single one.

Notes On The Implementation

• This iterator returns the elements of the underlying iterations in the same order as if you would iterate yourself over the elements of the first iterator, than over the elements of the second one and so on.

Version:

$Revision: 1.5 $

Author:

Oliver Fischer

Constructor Summary

GlueingIterator(java.util.Iterator[] pIters)
Creates an iterator which knits all iterators in a given array together.

GlueingIterator(java.util.Iterator pIter1, java.util.Iterator pIter2)
Creates an iterator which knits two other iterators together.

Method Summary

void	addIterator(java.util.Iterator pIterator) Attaches another iteration to the GlueingIterator after the already attached iterations.
boolean	hasNext() Checks if all elements of the underlying iterations have been returned or not.
boolean	isRunning() Checks if the iterator is in use or not.
java.lang.Object	next() Returns the next element of the underlying iterations.
void	remove() Removes the last element returned by next() from the underlaying iteration by forwarding the remove call to it.

Methods inherited from class java.lang.Object

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

Constructor Detail

GlueingIterator

public GlueingIterator(java.util.Iterator pIter1,
                       java.util.Iterator pIter2)

Creates an iterator which knits two other iterators together. Iterating over all elements of this iteration will return at first all the elements of the iteration given as the first argument and then the elements of the second one.

Parameters:

pIter1 - an Iterator representing the elements of the first iteration to add.

pIter2 - an Iterator representing the elements of the second iteration to add.

Throws:

java.lang.NullPointerException - if one of both iterations given as argument is null.

GlueingIterator

public GlueingIterator(java.util.Iterator[] pIters)

Creates an iterator which knits all iterators in a given array together. Iterating over all elements of this iteration will return all the elements in the same order as if you would iterate at first over the elements of the iteration stored at position 0 in the array, afterwards over the elements of the iteration at position 1 and so on.

Parameters:

pIters - an Iterator[] array containing all the iterations to link by this iterator.

Throws:

java.lang.NullPointerException - if the given array of iterators is empty.

Method Detail

isRunning

public boolean isRunning()

Checks if the iterator is in use or not. Being in use means for this iterator, that someone has called next() or hasNext().

Returns:

a boolean value which is true if the iterator is running. Otherwise false is returned.

addIterator

public void addIterator(java.util.Iterator pIterator)

Attaches another iteration to the GlueingIterator after the already attached iterations. This operation is only allowed if the iterator is not in use. Being in use means in this case, that someone called next() or hasNext().

Parameters:

pIterator - an Iterator representing the iteration to add to this iterator.

Throws:

java.lang.IllegalStateException - if isRunning() returns true.

java.lang.NullPointerException - if null is passed as argument to this method.

remove

public void remove()

Removes the last element returned by next() from the underlaying iteration by forwarding the remove call to it.

Specified by:

remove in interface java.util.Iterator

Throws:

java.lang.UnsupportedOperationException - if the source iteration doesn't support this operation.

next

public java.lang.Object next()

Returns the next element of the underlying iterations.

Specified by:

next in interface java.util.Iterator

Returns:

a Object representing the next element in the concatenation of the all underlying iterations.

Throws:

java.util.NoSuchElementException - if there are no more elements left to return, indicated by hasNext().

See Also:

hasNext()

hasNext

public boolean hasNext()

Checks if all elements of the underlying iterations have been returned or not.

Specified by:

hasNext in interface java.util.Iterator

Returns:

a boolean value which is true if not all elements have been returned or in other words: it returns true if there are some elements to return by next(). If this method did not return true it will return false. Another return value beside true or false is improbably.