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.Collection;
20 import java.util.Iterator;
21 import java.util.NoSuchElementException;
22 import java.util.Objects;
23
24 import org.apache.commons.collections4.ResettableIterator;
25
26 /**
27 * An Iterator that restarts when it reaches the end.
28 * <p>
29 * The iterator will loop continuously around the provided elements, unless
30 * there are no elements in the collection to begin with, or all the elements
31 * have been {@link #remove removed}.
32 * <p>
33 * Concurrent modifications are not directly supported, and for most collection
34 * implementations will throw a ConcurrentModificationException.
35 *
36 * @param <E> the type of elements returned by this iterator.
37 * @since 3.0
38 */
39 public class LoopingIterator<E> implements ResettableIterator<E> {
40
41 /** The collection to base the iterator on */
42 private final Collection<? extends E> collection;
43 /** The current iterator */
44 private Iterator<? extends E> iterator;
45
46 /**
47 * Constructor that wraps a collection.
48 * <p>
49 * There is no way to reset an Iterator instance without recreating it from
50 * the original source, so the Collection must be passed in.
51 *
52 * @param collection the collection to wrap
53 * @throws NullPointerException if the collection is null
54 */
55 public LoopingIterator(final Collection<? extends E> collection) {
56 this.collection = Objects.requireNonNull(collection, "collection");
57 reset();
58 }
59
60 /**
61 * Has the iterator any more elements.
62 * <p>
63 * Returns false only if the collection originally had zero elements, or
64 * all the elements have been {@link #remove removed}.
65 *
66 * @return {@code true} if there are more elements
67 */
68 @Override
69 public boolean hasNext() {
70 return !collection.isEmpty();
71 }
72
73 /**
74 * Returns the next object in the collection.
75 * <p>
76 * If at the end of the collection, return the first element.
77 *
78 * @return the next object
79 * @throws NoSuchElementException if there are no elements
80 * at all. Use {@link #hasNext} to avoid this error.
81 */
82 @Override
83 public E next() {
84 if (collection.isEmpty()) {
85 throw new NoSuchElementException("There are no elements for this iterator to loop on");
86 }
87 if (!iterator.hasNext()) {
88 reset();
89 }
90 return iterator.next();
91 }
92
93 /**
94 * Removes the previously retrieved item from the underlying collection.
95 * <p>
96 * This feature is only supported if the underlying collection's
97 * {@link Collection#iterator iterator} method returns an implementation
98 * that supports it.
99 * <p>
100 * This method can only be called after at least one {@link #next} method call.
101 * After a removal, the remove method may not be called again until another
102 * next has been performed. If the {@link #reset} is called, then remove may
103 * not be called until {@link #next} is called again.
104 */
105 @Override
106 public void remove() {
107 iterator.remove();
108 }
109
110 /**
111 * Resets the iterator back to the start of the collection.
112 */
113 @Override
114 public void reset() {
115 iterator = collection.iterator();
116 }
117
118 /**
119 * Gets the size of the collection underlying the iterator.
120 *
121 * @return the current collection size
122 */
123 public int size() {
124 return collection.size();
125 }
126
127 }