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}