package Torello.Java.Additional;

import java.util.Iterator;

/**
 * This functions identically to the normal {@code Iterator<E>} class, but prevents
 * <CODE>Iterator&#46;remove()</CODE> from ever being invoked.  It does not seem clear why such an
 * option is not included for the standard {@code Iterator} producing methods in java.  There are
 * many times when an {@code Iterator} of the contents of a {@code Vector} would be useful, but
 * allowing the user to modify the contents would not be.
 * 
 * @param <E> The type that this {@code Iterator} will iterate.
 */
public class RemoveUnsupportedIterator<E> implements Iterator<E>
{
    /** This class just wraps a standard java iterator */
    private final Iterator<E> iterator;

    /**
     * This constructor is the only offered constructor.  All it does is "wrap" one iterator that
     * throws the {@code UnsupportedOperationException} if a user attempts to invoke the
     * {@code 'remove()'} method.
     * @param iterator This should be any java iterator.  Regardless of whether this iterator
     * already throws the UnsupportedOperationException on an invocation of the 'remove()' method,
     * this class will guarantee that the exception is thrown.
     */
    public RemoveUnsupportedIterator(Iterator<E> iterator) { this.iterator = iterator; }

    /**
     * This is a standard Java Iterator-provided method.
     * @param action This (<B><I>should</I></B>) accept an instance of the {@code 'Consumer<E>'}
     * functional interface, but indeed it uses a "Raw-Type" and will accept any instance of
     * class {@code 'Consumer'}.
     *
     * @throws ClassCastException This will throw if you "screw it up" (and pass a consumer that
     * cannot accept variable type {@code 'E'}.  This will throw at RunTime, and there is no way
     * to check this at compile-type, unfortunately.
     * <BR /><BR />Lucky for you, it is extremely unlikely you would ever need to invoke this
     * method on a {@code 'RemoveUnsupportedIterator'}.  Have a nice day!
     */
    @SuppressWarnings("unchecked")
    public void forEachRemaining(java.util.function.Consumer<? super E> action)
    { this.iterator.forEachRemaining(action); }

    /**
     * This method is identical to the standard java iterator {@code 'hasNext()'} method.
     * It merely invokes {@code 'hasNext()'} on the internally stored reference to the original
     * {@code Iterator} reference.
     (
     * @return This will return {@code TRUE} if the internally stored iterator reference has more
     * elements to return.  It will return {@code FALSE} otherwise.
     */
    public boolean  hasNext() { return this.iterator.hasNext(); }

    /**
     * This method is identical to the standard java iterator {@code 'next()'} method.
     * It merely invokes {@code 'next()'} on the internally stored reference to the original
     * {@code Iterator} reference.
     *
     * @return returns the next element available.
     */
    public E next() { return this.iterator.next(); }

    /**
     * This ensures that any attempt to modify the internal data structure will cause the
     * {@code Iterator} to throw {@code 'UnsupportedOperationException'} to throw.
     *
     * @throws UnsupportedOperationException If this method is invoked for any reason, and under
     * any circumstances.
     */
    public final void remove()
    { throw new UnsupportedOperationException("Remove Operation is not supported."); }
}