com.antelmann.util
Class AbstractIterator<E>

java.lang.Object
  com.antelmann.util.AbstractIterator<E>

All Implemented Interfaces:

Closeable, Iterable<E>, Enumeration<E>, Iterator<E>

Direct Known Subclasses:

AbstractDBEnumeration, ObjectEnumerator, ServerLogFile.ServerLogEntryEnumerator, SQLCalendarEntryIterator

public abstract class AbstractIterator<E>
extends Object
implements Enumeration<E>, Iterator<E>, Iterable<E>, Closeable

makes it very easy to implement both, Enumeration and Iterator. The only abstract method is getNextElement(). Additionally, this class also implements Iterable for most code flexibility. This method is to supply the next object until it throws an exception, which marks that the last object was reached. By default, returning null also marks the end of the iteration; in consequence, the next() never returns null in this case. You can change this behavior to allow an enumeration to return null as a valid element by calling setAllowNull(true) and you can also call setPropagateException(boolean) to have an exception thrown instead of having it mark the end of an iteration. In addition, this class supplies convenient static methods to convert an Enumeration to an Iterator and vice versa.

Since:

04/16/2004

Author:

Holger Antelmann

Constructor Summary

protected	AbstractIterator()
protected	AbstractIterator(boolean allowNull)

Method Summary

boolean	allowsNull() if false (the default), next() never returns null (as null marks the end of the iteration).
static <T> Iterable<T>	asIterable(Iterator<T> i)
void	close() closes this iterator by calling stopIteration().
static <T,X extends T,Y extends T> Enumeration<T>	concat(Enumeration<X> e1, Enumeration<Y> e2)
static <T,X extends T,Y extends T> Iterator<T>	concat(Iterator<X> i1, Iterator<Y> i2)
static <T,N> Enumeration<N>	convert(Enumeration<T> e, PatternExtractor<? super T,N> pe)
static <T,N> Iterator<N>	convert(Iterator<T> i, PatternExtractor<? super T,N> pe)
static int	count(Iterator<?> i)
E	currentElement() allows to access the current element over and over again without advancing the cursor.
static <T> Enumeration<T>	emptyEnumeration()
static <T> Iterable<T>	emptyIterable()
static <T> Iterator<T>	emptyIterator()
static <F> Enumeration<F>	enumerate(Iterator<? extends F> i) converts an Iterator
static <F> AbstractIterator<F>	filter(Enumeration<F> e, Filter<? super F> filter)
static <F> AbstractIterator<F>	filter(Iterator<F> i, Filter<? super F> filter) remove() is not supported on the returned iterator
List<E>	getAll()
long	getCount() returns the number of elements that have been returned through next so far
Exception	getEndCondition() indicates the cause for this iterator to end
Filter<? super E>	getFilter()
protected abstract E	getNextElement() if no more Element is available, this method is to return null or throw any Exception.
boolean	hasMoreElements()
boolean	hasNext()
static <F> Iterator<F>	iterate(Enumeration<? extends F> e) converts an Enumeration into an Iterator
static <T> Iterator<T>	iterate(T[] array)
Iterator<E>	iterator()
static <F> ArrayList<F>	list(Enumeration<F> e)
static <F> List<F>	list(Iterable<F> i)
static <E> ArrayList<E>	list(Iterator<E> it, int maxElements) if maxElements is negative, the entire iteration is returned
static <F> ArrayList<F>	list(Iterator<F> i)
static <T> Enumeration<T>	monitor(Enumeration<T> e, Monitor monitor)
static <T> Iterator<T>	monitor(Iterator<T> i, Monitor monitor) increments the monitor upon calling next() and returns false upon hasNext() if the monitor is disabled
E	next()
E	nextElement()
static <T,R extends RuntimeException> Enumeration<T>	process(Enumeration<T> e, Processor<T,R> p) allows to wrap a given Enumeration so that each enumerated object is processed (possibly even substituted) by the given Processor
static <T,R extends RuntimeException> Iterator<T>	process(Iterator<T> i, Processor<T,R> p) allows to wrap a given Iterator so that each iterated object is processed (possibly even substituted) by the given Processor
boolean	propagatesException() if true, an exception thrown by getNextElement() will be thrown as an IterationException back to the caller of any method of the Iterator
void	remove() throws UnsupportedOperationException (unless overridden, of course).
static <F> Enumeration<F>	reverseEnumeration(Enumeration<F> e) reverses the given Enumeration; requires to fully load the given Enumeration into memory
void	setAllowNull(boolean flag) allows to set whether null is an allowed value for next() or if marks the end of an iteration.
void	setFilter(Filter<? super E> filter) if a non-null filter is set, only those elements that pass the filter will be returned by next().
void	setPropagateException(boolean flag) allows to have Exceptions thrown during getNextElement() propagated as IterationExceptions back to the caller
static <F extends Comparable<? super F>> Enumeration<F>	sortEnumeration(Enumeration<? extends F> e) sorts the given Enumeration by the natural order of its elements; requires to fully load the given Enumeration into memory
static <F> Enumeration<F>	sortEnumeration(Enumeration<F> e, Comparator<F> c) sorts the given Enumeration by the order imposed by the given comparator; requires to fully load the given Enumeration into memory
protected void	stopIteration() allows to stop an iteration gracefully even when it allows null and propagates Exceptions.

Methods inherited from class java.lang.Object

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

Constructor Detail

AbstractIterator

protected AbstractIterator()

AbstractIterator

protected AbstractIterator(boolean allowNull)

See Also:

setAllowNull(boolean)

Method Detail

iterator

public Iterator<E> iterator()

Specified by:

iterator in interface Iterable<E>

setFilter

public void setFilter(Filter<? super E> filter)

if a non-null filter is set, only those elements that pass the filter will be returned by next().

getFilter

public Filter<? super E> getFilter()

allowsNull

public boolean allowsNull()

if false (the default), next() never returns null (as null marks the end of the iteration).

See Also:

setAllowNull(boolean)

setAllowNull

public void setAllowNull(boolean flag)

allows to set whether null is an allowed value for next() or if marks the end of an iteration. If set to true, the iteration only ends if getNextElement() throws an exception.

propagatesException

public boolean propagatesException()

if true, an exception thrown by getNextElement() will be thrown as an IterationException back to the caller of any method of the Iteratoror Enumeration interface. If false (the default behavior), this iterator will simply assume that there are no more elements and otherwise ignore the Exception.

See Also:

IterationException

setPropagateException

public void setPropagateException(boolean flag)

allows to have Exceptions thrown during getNextElement() propagated as IterationExceptions back to the caller

See Also:

IterationException

getNextElement

protected abstract E getNextElement()
                             throws Exception

if no more Element is available, this method is to return null or throw any Exception. Errors (as opposed to Exceptions) are not caught, i.e. they would always be thrown directly and unwrapped during next().

Throws:

Exception

close

public void close()
           throws IOException

closes this iterator by calling stopIteration(). You can use this method to clean up any resources there may be needed for this iterator. Note, however, that this method is not called automatically; so if you need this method to be called after the iteration is through (or only partially used), you have to call this method yourself (or you overwrite this implementation accordingly). Also, when overriding this method, you should call super.close().

Specified by:

close in interface Closeable

Throws:

IOException

stopIteration

protected void stopIteration()

allows to stop an iteration gracefully even when it allows null and propagates Exceptions. After calling this method, hasNext() will return false.

next

public E next()

Specified by:

next in interface Iterator<E>

getCount

public long getCount()

returns the number of elements that have been returned through next so far

currentElement

public E currentElement()
                 throws IllegalStateException

allows to access the current element over and over again without advancing the cursor.

Throws:

IllegalStateException - if this method is called before next() has been called the first time, it returns null.

nextElement

public E nextElement()

Specified by:

nextElement in interface Enumeration<E>

hasMoreElements

public boolean hasMoreElements()

Specified by:

hasMoreElements in interface Enumeration<E>

hasNext

public boolean hasNext()

Specified by:

hasNext in interface Iterator<E>

getAll

public List<E> getAll()

getEndCondition

public Exception getEndCondition()
                          throws IllegalStateException

indicates the cause for this iterator to end

Throws:

IllegalStateException - if hasNext() is true

remove

public void remove()

throws UnsupportedOperationException (unless overridden, of course). At this level, remove() cannot be supported due to the filtering/caching abilities.

Specified by:

remove in interface Iterator<E>

iterate

public static <T> Iterator<T> iterate(T[] array)

iterate

public static <F> Iterator<F> iterate(Enumeration<? extends F> e)

converts an Enumeration into an Iterator

enumerate

public static <F> Enumeration<F> enumerate(Iterator<? extends F> i)

converts an Iteratorinto an Enumeration

sortEnumeration

public static <F extends Comparable<? super F>> Enumeration<F> sortEnumeration(Enumeration<? extends F> e)

sorts the given Enumeration by the natural order of its elements; requires to fully load the given Enumeration into memory

sortEnumeration

public static <F> Enumeration<F> sortEnumeration(Enumeration<F> e,
                                                 Comparator<F> c)

sorts the given Enumeration by the order imposed by the given comparator; requires to fully load the given Enumeration into memory

reverseEnumeration

public static <F> Enumeration<F> reverseEnumeration(Enumeration<F> e)

reverses the given Enumeration; requires to fully load the given Enumeration into memory

list

public static <E> ArrayList<E> list(Iterator<E> it,
                                    int maxElements)

if maxElements is negative, the entire iteration is returned

list

public static <F> List<F> list(Iterable<F> i)

list

public static <F> ArrayList<F> list(Iterator<F> i)

list

public static <F> ArrayList<F> list(Enumeration<F> e)

See Also:

Collections.list(Enumeration)

filter

public static <F> AbstractIterator<F> filter(Enumeration<F> e,
                                             Filter<? super F> filter)

filter

public static <F> AbstractIterator<F> filter(Iterator<F> i,
                                             Filter<? super F> filter)

remove() is not supported on the returned iterator

monitor

public static <T> Enumeration<T> monitor(Enumeration<T> e,
                                         Monitor monitor)

monitor

public static <T> Iterator<T> monitor(Iterator<T> i,
                                      Monitor monitor)

increments the monitor upon calling next() and returns false upon hasNext() if the monitor is disabled

count

public static int count(Iterator<?> i)

process

public static <T,R extends RuntimeException> Enumeration<T> process(Enumeration<T> e,
                                                                    Processor<T,R> p)

allows to wrap a given Enumeration so that each enumerated object is processed (possibly even substituted) by the given Processor

process

public static <T,R extends RuntimeException> Iterator<T> process(Iterator<T> i,
                                                                 Processor<T,R> p)

allows to wrap a given Iterator so that each iterated object is processed (possibly even substituted) by the given Processor

convert

public static <T,N> Enumeration<N> convert(Enumeration<T> e,
                                           PatternExtractor<? super T,N> pe)

convert

public static <T,N> Iterator<N> convert(Iterator<T> i,
                                        PatternExtractor<? super T,N> pe)

concat

public static <T,X extends T,Y extends T> Enumeration<T> concat(Enumeration<X> e1,
                                                                Enumeration<Y> e2)

concat

public static <T,X extends T,Y extends T> Iterator<T> concat(Iterator<X> i1,
                                                             Iterator<Y> i2)

emptyEnumeration

public static <T> Enumeration<T> emptyEnumeration()

emptyIterator

public static <T> Iterator<T> emptyIterator()

emptyIterable

public static <T> Iterable<T> emptyIterable()

asIterable

public static <T> Iterable<T> asIterable(Iterator<T> i)