com.antelmann.util
Class AbstractIterator<E>

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

All Implemented Interfaces:

Enumeration<E>, Iterator<E>

Direct Known Subclasses:

ObjectEnumerator, ServerLogFile.ServerLogEntryEnumerator, SQLCalendarEntryIterator

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

makes it very easy to implement both, Enumeration and Iterator. The only abstract method is getNextObject(). 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). 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).
E	currentElement() allows to access the current element over and over again without advancing the cursor.
static <F> Enumeration<F>	enumerate(Iterator<F> i) converts an Iterator into an Enumeration
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<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<F> e) converts an Enumeration into an Iterator
static <F> ArrayList<F>	list(Enumeration<F> e)
static <F> ArrayList<F>	list(Iterator<F> i)
E	next()
E	nextElement()
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 or Enumeration interface.
void	remove() throws UnsupportedOperationException (unless overridden, of course)
static <F> Enumeration<F>	reverseEnumeration(Enumeration<F> e) reverses the given Enumeration
void	setAllowNull(boolean flag) allows to set wether null is an allowed value for next() or if marks the end of an iteration.
void	setFilter(Filter<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<F> e) sorts the given Enumeration by the natural order of its elements
static <F> Enumeration<F>	sortEnumeration(Enumeration<F> e, Comparator<F> c) sorts the given Enumeration by the natural order of its elements

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

setFilter

public void setFilter(Filter<E> filter)

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

getFilter

public Filter<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 wether null is an allowed value for next() or if marks the end of an iteration. If set to true, the iteration only ends if getNextObject() 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 Iterator or 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

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

Returns:

null if the last getNextObject() returned null or an exception that was thrown

Throws:

IllegalStateException - if hasNext() is true

remove

public void remove()

throws UnsupportedOperationException (unless overridden, of course)

Specified by:

remove in interface Iterator<E>

iterate

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

converts an Enumeration into an Iterator

enumerate

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

converts an Iterator into an Enumeration

sortEnumeration

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

sorts the given Enumeration by the natural order of its elements

sortEnumeration

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

sorts the given Enumeration by the natural order of its elements

reverseEnumeration

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

reverses the given Enumeration

list

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

list

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