Holger's Java API

## 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 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`

### 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 Iterator<?>into 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)

(c) Holger Antelmann since 2001- all rights reserved (contact: info@antelmann.com)
see www.antelmann.com/developer for further details and available downloads