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 * http://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.NoSuchElementException;
20
21 import org.apache.commons.collections4.ResettableIterator;
22
23 /**
24 * {@code SingletonIterator} is an {@link java.util.Iterator} over a single
25 * object instance.
26 *
27 * @param <E> the type of elements returned by this iterator.
28 * @since 2.0
29 */
30 public class SingletonIterator<E>
31 implements ResettableIterator<E> {
32
33 /** Whether remove is allowed */
34 private final boolean removeAllowed;
35 /** Is the cursor before the first element */
36 private boolean beforeFirst = true;
37 /** Has the element been removed */
38 private boolean removed;
39 /** The object */
40 private E object;
41
42 /**
43 * Constructs a new {@code SingletonIterator} where {@code remove}
44 * is a permitted operation.
45 *
46 * @param object the single object to return from the iterator
47 */
48 public SingletonIterator(final E object) {
49 this(object, true);
50 }
51
52 /**
53 * Constructs a new {@code SingletonIterator} optionally choosing if
54 * {@code remove} is a permitted operation.
55 *
56 * @param object the single object to return from the iterator
57 * @param removeAllowed true if remove is allowed
58 * @since 3.1
59 */
60 public SingletonIterator(final E object, final boolean removeAllowed) {
61 this.object = object;
62 this.removeAllowed = removeAllowed;
63 }
64
65 /**
66 * Is another object available from the iterator?
67 * <p>
68 * This returns true if the single object hasn't been returned yet.
69 *
70 * @return true if the single object hasn't been returned yet
71 */
72 @Override
73 public boolean hasNext() {
74 return beforeFirst && !removed;
75 }
76
77 /**
78 * Gets the next object from the iterator.
79 * <p>
80 * This returns the single object if it hasn't been returned yet.
81 *
82 * @return the single object
83 * @throws NoSuchElementException if the single object has already
84 * been returned
85 */
86 @Override
87 public E next() {
88 if (!beforeFirst || removed) {
89 throw new NoSuchElementException();
90 }
91 beforeFirst = false;
92 return object;
93 }
94
95 /**
96 * Remove the object from this iterator.
97 *
98 * @throws IllegalStateException if the {@code next} method has not
99 * yet been called, or the {@code remove} method has already
100 * been called after the last call to the {@code next}
101 * method.
102 * @throws UnsupportedOperationException if remove is not supported
103 */
104 @Override
105 public void remove() {
106 if (!removeAllowed) {
107 throw new UnsupportedOperationException();
108 }
109 if (removed || beforeFirst) {
110 throw new IllegalStateException();
111 }
112 object = null;
113 removed = true;
114 }
115
116 /**
117 * Reset the iterator to the start.
118 */
119 @Override
120 public void reset() {
121 beforeFirst = true;
122 }
123
124 }