com.bigdata.striterator

Class Striterator<I extends Iterator<E>,E>

java.lang.Object

com.bigdata.striterator.Striterator<I,E>

Type Parameters:

I -

E -

All Implemented Interfaces:

IStriterator<I,E>, ICloseable, ICloseableIterator<E>, Enumeration<E>, Iterator<E>

Direct Known Subclasses:

ChunkedStriterator, GenericStriterator

public class Striterator<I extends Iterator<E>,E>
extends Object
implements IStriterator<I,E>

Streaming iterator pattern.

Version:

$Id$

Author:

Bryan Thompson

Field Summary

Fields

Modifier and Type	Field and Description
protected I	realSource Set to the source iterator by the ctor.
protected I	src Set to the source iterator by the ctor and then replaced each time we wrap the source iterator with another IFilter.

Constructor Summary

Constructors

Constructor and Description
Striterator(Enumeration<E> srcEnum) Wraps the enumeration as an iterator.
Striterator(I src)

Method Summary

Methods

Modifier and Type	Method and Description
IStriterator<I,E>	addFilter(IFilter<I,?,E> filter) Stack a filter on the source iterator.
IStriterator<I,E>	addInstanceOfFilter(Class<E> cls) Visits elements that are instances of the specified class.
IStriterator<I,E>	append(I src) Appends the given iterator when this iterator is exhausted.
void	close() Closes the iterator, releasing any associated resources.
IStriterator<I,E>	exclude(Set<E> set) Exclude elements found in the set.
boolean	hasMoreElements()
boolean	hasNext()
IStriterator<I,E>	makeUnique()
IStriterator<I,E>	map(Object client, Method method)
E	next()
E	nextElement()
void	remove() Unsupported operation.

Methods inherited from class java.lang.Object

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

Field Detail

realSource

protected final I extends Iterator<E> realSource

Set to the source iterator by the ctor. This exists against the possibility that some patterns will require access to the source iterator as well. One example is the partitioned tuple iterator which needs to know the key for last tuple visited by the source iterator in order to advance the aggregate iterator efficiently to the next chunk without re-scanning tuples.

src

protected I extends Iterator<E> src

Set to the source iterator by the ctor and then replaced each time we wrap the source iterator with another IFilter. This is always the iterator that realizes the stacked filter semantics.

Constructor Detail

Striterator

public Striterator(I src)

Parameters:

src - The source iterator.

Striterator

public Striterator(Enumeration<E> srcEnum)

Wraps the enumeration as an iterator. The constructor must be overridden for derived classes that specialize the type of the iterator.

Parameters:

srcEnum - The source enumeration.

Method Detail

addFilter

public IStriterator<I,E> addFilter(IFilter<I,?,E> filter)

Description copied from interface: IStriterator

Stack a filter on the source iterator.

Specified by:

addFilter in interface IStriterator<I extends Iterator<E>,E>

Parameters:

filter - The filter.

Returns:

The filtered iterator.

addInstanceOfFilter

public IStriterator<I,E> addInstanceOfFilter(Class<E> cls)

Description copied from interface: IStriterator

Visits elements that are instances of the specified class.

Specified by:

addInstanceOfFilter in interface IStriterator<I extends Iterator<E>,E>

Parameters:

cls - The class.

Returns:

The filtered iterator.

append

public IStriterator<I,E> append(I src)

Description copied from interface: IStriterator

Appends the given iterator when this iterator is exhausted.

Specified by:

append in interface IStriterator<I extends Iterator<E>,E>

Parameters:

src - Another iterator.

Returns:

The combined iterator.

exclude

public IStriterator<I,E> exclude(Set<E> set)

Exclude elements found in the set.

Parameters:

set - The set of elements to be excluded.

Returns:

The filtered iterator.

makeUnique

public IStriterator<I,E> makeUnique()

map

public IStriterator<I,E> map(Object client,
                    Method method)

close

public final void close()

Description copied from interface: ICloseableIterator

Closes the iterator, releasing any associated resources. This method MAY be invoked safely if the iterator is already closed. Implementations of this interface MUST invoke ICloseableIterator.close() if Iterator.hasNext() method returns false to ensure that the iterator is closed (and its resources release) as soon as it is exhausted.

Note: Implementations that support Iterator.remove() MUST NOT eagerly close the iterator when it is exhausted since that would make it impossible to remove the last visited statement. Instead they MUST wait for an explicit ICloseableIterator.close() by the application.

Specified by:

close in interface ICloseable

Specified by:

close in interface ICloseableIterator<E>

hasMoreElements

public final boolean hasMoreElements()

Specified by:

hasMoreElements in interface Enumeration<E>

nextElement

public final E nextElement()

Specified by:

nextElement in interface Enumeration<E>

hasNext

public final boolean hasNext()

Specified by:

hasNext in interface Iterator<E>

next

public final E next()

Specified by:

next in interface Iterator<E>

remove

public void remove()

Unsupported operation.

Extreme care must be taken when implementing striterator patterns that support removal in order to ensure that the current iterator element is removed from the iteration source. In the general case, it may not be possible to implement remove() for striterator patterns.

When the striterator is also an IChunkedIterator then remove() semantics face an additional difficulty. If the source iterator is being consumed a chunk at a time, then remove() only has the semantics of removing the last element in the chunk.

Specified by:

remove in interface Iterator<E>

Throws:

UnsupportedOperationException - For the above reasons, remove() is NOT supported for chunked striterator patterns and this method will always throw an UnsupportedOperationException.