001package Torello.Java.Additional;
002
003import java.util.Iterator;
004
005/**
006 * This functions identically to the normal {@code Iterator<E>} class, but prevents
007 * <CODE>Iterator&#46;remove()</CODE> from ever being invoked.  It does not seem clear why such an
008 * option is not included for the standard {@code Iterator} producing methods in java.  There are
009 * many times when an {@code Iterator} of the contents of a {@code Vector} would be useful, but
010 * allowing the user to modify the contents would not be.
011 * 
012 * @param <E> The type that this {@code Iterator} will iterate.
013 */
014public class RemoveUnsupportedIterator<E> implements Iterator<E>
015{
016    /** This class just wraps a standard java iterator */
017    private final Iterator<E> iterator;
018
019    /**
020     * This constructor is the only offered constructor.  All it does is "wrap" one iterator that
021     * throws the {@code UnsupportedOperationException} if a user attempts to invoke the
022     * {@code 'remove()'} method.
023     * @param iterator This should be any java iterator.  Regardless of whether this iterator
024     * already throws the UnsupportedOperationException on an invocation of the 'remove()' method,
025     * this class will guarantee that the exception is thrown.
026     */
027    public RemoveUnsupportedIterator(Iterator<E> iterator) { this.iterator = iterator; }
028
029    /**
030     * This is a standard Java Iterator-provided method.
031     * @param action This (<B><I>should</I></B>) accept an instance of the {@code 'Consumer<E>'}
032     * functional interface, but indeed it uses a "Raw-Type" and will accept any instance of
033     * class {@code 'Consumer'}.
034     *
035     * @throws ClassCastException This will throw if you "screw it up" (and pass a consumer that
036     * cannot accept variable type {@code 'E'}.  This will throw at RunTime, and there is no way
037     * to check this at compile-type, unfortunately.
038     * <BR /><BR />Lucky for you, it is extremely unlikely you would ever need to invoke this
039     * method on a {@code 'RemoveUnsupportedIterator'}.  Have a nice day!
040     */
041    @SuppressWarnings("unchecked")
042    public void forEachRemaining(java.util.function.Consumer<? super E> action)
043    { this.iterator.forEachRemaining(action); }
044
045    /**
046     * This method is identical to the standard java iterator {@code 'hasNext()'} method.
047     * It merely invokes {@code 'hasNext()'} on the internally stored reference to the original
048     * {@code Iterator} reference.
049     (
050     * @return This will return {@code TRUE} if the internally stored iterator reference has more
051     * elements to return.  It will return {@code FALSE} otherwise.
052     */
053    public boolean  hasNext() { return this.iterator.hasNext(); }
054
055    /**
056     * This method is identical to the standard java iterator {@code 'next()'} method.
057     * It merely invokes {@code 'next()'} on the internally stored reference to the original
058     * {@code Iterator} reference.
059     *
060     * @return returns the next element available.
061     */
062    public E next() { return this.iterator.next(); }
063
064    /**
065     * This ensures that any attempt to modify the internal data structure will cause the
066     * {@code Iterator} to throw {@code 'UnsupportedOperationException'} to throw.
067     *
068     * @throws UnsupportedOperationException If this method is invoked for any reason, and under
069     * any circumstances.
070     */
071    public final void remove()
072    { throw new UnsupportedOperationException("Remove Operation is not supported."); }
073}