001    package com.softnetConsult.utils.collections;
002    
003    import java.util.Iterator;
004    
005    
006    /**
007     * A generic read-only iterator.
008     * A {@code ReadOnlyIterator<T>} object wraps around an {@code Iterator<? extends T>}
009     * object and simply forwards all read-only method calls to it. Modifying
010     * operations (i.e. {@code remove} throw a {@code UnsupportedOperationException}.
011     * 
012     * <p style="font-size:smaller;">This product includes software developed by the
013     *    <strong>SoftNet-Consult Java Utility Library</strong> project and its contributors.<br />
014     *    (<a href="http://java-tools.sourceforge.net" target="_blank">http://java-tools.sourceforge.net</a>)<br />
015     *    Copyright (c) 2007-2008 SoftNet-Consult.<br />
016     *    Copyright (c) 2007-2008 G. Paperin.<br />
017     *    All rights reserved.
018     * </p>
019     * <p style="font-size:smaller;">File: ReadOnlyIterator.java<br />
020     *    Library API version: {@value com.softnetConsult.utils.APIProperties#apiVersion}<br />
021     *    Java compliance version: {@value com.softnetConsult.utils.APIProperties#javaComplianceVersion}
022     * </p>
023     * <p style="font-size:smaller;">Redistribution and use in source and binary forms, with or
024     *    without modification, are permitted provided that the following terms and conditions are met:
025     * </p>
026     * <p style="font-size:smaller;">1. Redistributions of source code must retain the above
027     *    acknowledgement of the SoftNet-Consult Java Utility Library project, the above copyright
028     *    notice, this list of conditions and the following disclaimer.<br />
029     *    2. Redistributions in binary form must reproduce the above acknowledgement of the
030     *    SoftNet-Consult Java Utility Library project, the above copyright notice, this list of
031     *    conditions and the following disclaimer in the documentation and/or other materials
032     *    provided with the distribution.<br />
033     *    3. All advertising materials mentioning features or use of this software or any derived
034     *    software must display the following acknowledgement:<br />
035     *    <em>This product includes software developed by the SoftNet-Consult Java Utility Library
036     *    project and its contributors.</em>
037     * </p>
038     * <p style="font-size:smaller;">THIS SOFTWARE IS PROVIDED &quot;AS IS&quot;, WITHOUT WARRANTY
039     *    OF ANY KIND, EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
040     *    MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND  NONINFRINGEMENT. IN NO EVENT SHALL
041     *    THE AUTHORS, CONTRIBUTORS OR COPYRIGHT  HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
042     *    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING  FROM, OUT OF OR
043     *    IN CONNECTION WITH THE SOFTWARE OR THE USE OR  OTHER DEALINGS IN THE SOFTWARE.
044     * </p> 
045     * @author Greg Paperin (<a href="http://www.paperin.org" target="_blank">http://www.paperin.org</a>)
046     * @version {@value com.softnetConsult.utils.APIProperties#apiVersion}
047     *
048     * @param <T> A class type of the objects over which this iterator iterates.
049     */
050    public class ReadOnlyIterator<T> implements Iterator<T> {
051    
052    /**
053     * The encapsulated generic iterator;
054     */
055    private Iterator<? extends T> iterator = null;
056    
057    /**
058     * Creates a read-only iteretor for the specified iterator.
059     * @param iterator An iterator.
060     */
061    public ReadOnlyIterator(Iterator<? extends T> iterator) {
062            if (null == iterator)
063                    throw new NullPointerException("Cannot write-protect a null iterator");
064            this.iterator = iterator;
065    }
066    
067    /**
068     * Creates a read-only iteretor for the iterator over the specified iterable object.
069     * @param iterable An iterable object whose iterator will be wraped by this read only iterator.
070     */
071    public ReadOnlyIterator(Iterable<? extends T> iterable) {
072            if (null == iterator)
073                    throw new NullPointerException("Cannot create a read-only iterator over null");
074            this.iterator = iterable.iterator();
075    }
076    
077    /**
078     * Returns {@code true} if the iteration has more elements.
079     * (In other words, returns {@code true} if {@code true} would return an
080     * element rather than throwing an exception.)
081     * 
082     * @return {@code true} if the iterator has more elements.
083     */
084    public boolean hasNext() {
085            return iterator.hasNext();
086    }
087    
088    /**
089     * Returns the next element in the iteration.
090     * @return the next element in the iteration.
091     * @throws java.util.NoSuchElementException iteration has no more elements.
092     */
093    public T next() {
094            return iterator.next();
095    }
096    
097    /**
098     * Always throws {@code UnsupportedOperationException}.
099     * @throws UnsupportedOperationException Always thrown since this is a read-only iterator.
100     */
101    public void remove() {
102            throw new UnsupportedOperationException("Cannot use this iterator to remove items.");       
103    }
104    
105    } // public class ReadOnlyIterator<T>