001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.commons.collections4.iterators;
018
019import java.util.Collection;
020import java.util.Iterator;
021import java.util.NoSuchElementException;
022import java.util.Objects;
023
024import org.apache.commons.collections4.ResettableIterator;
025
026/**
027 * An Iterator that restarts when it reaches the end.
028 * <p>
029 * The iterator will loop continuously around the provided elements, unless
030 * there are no elements in the collection to begin with, or all the elements
031 * have been {@link #remove removed}.
032 * <p>
033 * Concurrent modifications are not directly supported, and for most collection
034 * implementations will throw a ConcurrentModificationException.
035 *
036 * @param <E> the type of elements returned by this iterator.
037 * @since 3.0
038 */
039public class LoopingIterator<E> implements ResettableIterator<E> {
040
041    /** The collection to base the iterator on */
042    private final Collection<? extends E> collection;
043    /** The current iterator */
044    private Iterator<? extends E> iterator;
045
046    /**
047     * Constructor that wraps a collection.
048     * <p>
049     * There is no way to reset an Iterator instance without recreating it from
050     * the original source, so the Collection must be passed in.
051     *
052     * @param collection  the collection to wrap
053     * @throws NullPointerException if the collection is null
054     */
055    public LoopingIterator(final Collection<? extends E> collection) {
056        this.collection = Objects.requireNonNull(collection, "collection");
057        reset();
058    }
059
060    /**
061     * Has the iterator any more elements.
062     * <p>
063     * Returns false only if the collection originally had zero elements, or
064     * all the elements have been {@link #remove removed}.
065     *
066     * @return {@code true} if there are more elements
067     */
068    @Override
069    public boolean hasNext() {
070        return !collection.isEmpty();
071    }
072
073    /**
074     * Returns the next object in the collection.
075     * <p>
076     * If at the end of the collection, return the first element.
077     *
078     * @return the next object
079     * @throws NoSuchElementException if there are no elements
080     *         at all.  Use {@link #hasNext} to avoid this error.
081     */
082    @Override
083    public E next() {
084        if (collection.isEmpty()) {
085            throw new NoSuchElementException("There are no elements for this iterator to loop on");
086        }
087        if (!iterator.hasNext()) {
088            reset();
089        }
090        return iterator.next();
091    }
092
093    /**
094     * Removes the previously retrieved item from the underlying collection.
095     * <p>
096     * This feature is only supported if the underlying collection's
097     * {@link Collection#iterator iterator} method returns an implementation
098     * that supports it.
099     * <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}