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.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}