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 "AS IS", 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>