// This Source Code is in the Public Domain per: http://litesoft.org/License.txt
package org.litesoft.core.util;

import java.util.*;

/**
 * There are two points for having this class:<p>
 * <p/>
 * First, that all Iterators need to be able to throw NoSuchElementException if
 * next is inappropriately called.  The easiest way is to simply implement a
 * dumb next at a superclass level that always throws it.<p>
 * <p/>
 * Second, the SUN/Java Iterators should NOT have supported <i>remove()</i>.
 * The GOF (Gang Of Four) Iterator not only provided more funcationality
 * (supporting both multiple reads of the current item AND the ability to pass
 * over the collection multiple times), but provided a nice <i>read only</i>
 * view of an arbitrarily stored collection.  To <i>restore</i> the read only
 * view aspect of an Iterator, this class provides a <i>final</i> implimentation
 * of <i>remove()</i>.<p>
 *
 * @author George Smith
 * @version 1.0 7/28/01
 * @see <a href="http://java.sun.com/j2se/1.3/docs/api/java/lang/Util/Iterator.html">java.util.Iterator</a>
 */

public abstract class AbstractReadOnlyIterator<T> implements Iterator<T>,
                                                             Disposable
{
    /**
     * hasNext() is part of the Iterator interface.  It is abtract here
     * because there is no reasonable, common, implementation and to
     * remind the developer who extends this class that they, at a
     * minimum, need to implement it.<p>
     *
     * @see <a href="http://java.sun.com/j2se/1.3/docs/api/java/lang/Util/Iterator.html#hasNext()">java.util.Iterator#hasNext()</a>
     */
    @Override
    abstract public boolean hasNext();

    /**
     * All most all Iterators will need to throw NoSuchElementException
     * at some point, so this is simply a convenience implementation.<p>
     *
     * @throws NoSuchElementException
     * @see <a href="http://java.sun.com/j2se/1.3/docs/api/java/lang/Util/Iterator.html#next()">java.util.Iterator#next()</a>
     */
    @Override
    public T next()
    {
        throw new NoSuchElementException();
    }

    /**
     * As mentioned above, the SUN/Java Iterators should NOT have supported
     * <i>remove()</i>.<p>
     * <p/>
     * Therefor, this method is a <i>final</i> version that throws
     * UnsupportedOperationException.<p>
     *
     * @throws UnsupportedOperationException
     * @see <a href="http://java.sun.com/j2se/1.3/docs/api/java/lang/Util/Iterator.html#remove()">java.util.Iterator.remove()</a>
     */
    @Override
    public final void remove()
    {
        throw new UnsupportedOperationException();
    }

    @Override
    public void dispose()
    {
    }
}