001 package com.softnetConsult.utils.collections;
002
003 import java.util.Iterator;
004 import java.util.NoSuchElementException;
005
006
007 /**
008 * Provides an Null Iterator: the methods of this class perform no action and no elements
009 * are ever returned - this class can be used when a non-{@code null} {@code Iterator} object
010 * must be specified, but no actual iteration indended.
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: NullIterator.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 <ET>
049 */
050 public final class NullIterator<ET> implements Iterator<ET> {
051
052 /**
053 * A singleton instance of the {@code NullIterator}.
054 */
055 private static NullIterator<?> singeltonInstance = null;
056
057 /**
058 * Returns a singleton instance of {@code NullIterator}.
059 *
060 * @param <T> The type for the hypothetically iterated items.
061 * @return A singleton {@code NullIterator} instance.
062 */
063 @SuppressWarnings("unchecked")
064 public static <T> NullIterator<T> getSingeltonInstance() {
065 if (null == singeltonInstance)
066 singeltonInstance = new NullIterator<Object>();
067 return (NullIterator<T>) singeltonInstance;
068 }
069
070 /**
071 * Returns a singleton instance of {@code NullIterator}.
072 * This method works in the same way as {@link #getSingeltonInstance()}, the
073 * parameter can be used to explicity specify the iterator type.
074 *
075 * @param <T> The type for the hypothetically iterated items.
076 * @param iteratorElementType The type for the hypothetically iterated items.
077 * @return A singleton {@code NullIterator} instance.
078 */
079 @SuppressWarnings("unchecked")
080 public static <T> NullIterator<T> getSingeltonInstance(Class<T> iteratorElementType) {
081 if (null == singeltonInstance)
082 singeltonInstance = new NullIterator<Object>();
083 return (NullIterator<T>) singeltonInstance;
084 }
085
086 /**
087 * Constructs a new {@code NullIterator}.
088 */
089 public NullIterator() { }
090
091 /**
092 * Returns {@code false} as the {@code NullIterator} has nothing to iterate over.
093 *
094 * @return {@code false}.
095 */
096 public boolean hasNext() {
097 return false;
098 }
099
100 /**
101 * Always throws a {@code NoSuchElementException} as the {@code NullIterator} has
102 * nothing to iterate over.
103 *
104 * @return Never returns normally as an exception is always thrown.
105 * @throws NoSuchElementException Always, as the {@code NullIterator} has nothing
106 * to iterate over.
107 */
108 public ET next() {
109 throw new NoSuchElementException("Null iterator has no elements");
110 }
111
112 /**
113 * Always throws a {@code IllegalStateException} as the {@code NullIterator} has
114 * nothing to remove.
115 *
116 * @throws IllegalStateException Always, as the {@code NullIterator} has nothing
117 * to remove.
118 */
119 public void remove() {
120 throw new IllegalStateException("Null iterator has no elements to return");
121 }
122
123 } // public final class NullIterator<ET>