1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * https://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17 package org.apache.commons.collections4.iterators;
18
19 import java.util.Iterator;
20 import java.util.NoSuchElementException;
21
22 import org.apache.commons.collections4.ResettableIterator;
23
24 /**
25 * {@code SingletonIterator} is an {@link Iterator} over a single
26 * object instance.
27 *
28 * @param <E> The type of elements returned by this iterator.
29 * @since 2.0
30 */
31 public class SingletonIterator<E>
32 implements ResettableIterator<E> {
33
34 /** Whether remove is allowed */
35 private final boolean removeAllowed;
36
37 /** Is the cursor before the first element */
38 private boolean beforeFirst = true;
39
40 /** Has the element been removed */
41 private boolean removed;
42
43 /** The object */
44 private E object;
45
46 /**
47 * Constructs a new {@code SingletonIterator} where {@code remove}
48 * is a permitted operation.
49 *
50 * @param object The single object to return from the iterator
51 */
52 public SingletonIterator(final E object) {
53 this(object, true);
54 }
55
56 /**
57 * Constructs a new {@code SingletonIterator} optionally choosing if
58 * {@code remove} is a permitted operation.
59 *
60 * @param object The single object to return from the iterator
61 * @param removeAllowed true if remove is allowed
62 * @since 3.1
63 */
64 public SingletonIterator(final E object, final boolean removeAllowed) {
65 this.object = object;
66 this.removeAllowed = removeAllowed;
67 }
68
69 /**
70 * Is another object available from the iterator?
71 * <p>
72 * This returns true if the single object hasn't been returned yet.
73 *
74 * @return true if the single object hasn't been returned yet
75 */
76 @Override
77 public boolean hasNext() {
78 return beforeFirst && !removed;
79 }
80
81 /**
82 * Gets the next object from the iterator.
83 * <p>
84 * This returns the single object if it hasn't been returned yet.
85 *
86 * @return The single object
87 * @throws NoSuchElementException if the single object has already
88 * been returned
89 */
90 @Override
91 public E next() {
92 if (!beforeFirst || removed) {
93 throw new NoSuchElementException();
94 }
95 beforeFirst = false;
96 return object;
97 }
98
99 /**
100 * Remove the object from this iterator.
101 *
102 * @throws IllegalStateException if the {@code next} method has not
103 * yet been called, or the {@code remove} method has already
104 * been called after the last call to the {@code next}
105 * method.
106 * @throws UnsupportedOperationException if remove is not supported
107 */
108 @Override
109 public void remove() {
110 if (!removeAllowed) {
111 throw new UnsupportedOperationException();
112 }
113 if (removed || beforeFirst) {
114 throw new IllegalStateException();
115 }
116 object = null;
117 removed = true;
118 }
119
120 /**
121 * Reset the iterator to the start.
122 */
123 @Override
124 public void reset() {
125 beforeFirst = true;
126 }
127
128 }