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.Iterator; 20 21 /** 22 * An LazyIteratorChain is an Iterator that wraps a number of Iterators in a lazy manner. 23 * <p> 24 * This class makes multiple iterators look like one to the caller. When any 25 * method from the Iterator interface is called, the LazyIteratorChain will delegate 26 * to a single underlying Iterator. The LazyIteratorChain will invoke the Iterators 27 * in sequence until all Iterators are exhausted. 28 * <p> 29 * The Iterators are provided by {@link #nextIterator(int)} which has to be overridden by 30 * subclasses and allows to lazily create the Iterators as they are accessed: 31 * <pre> 32 * return new LazyIteratorChain<String>() { 33 * protected Iterator<String> nextIterator(int count) { 34 * return count == 1 ? Arrays.asList("foo", "bar").iterator() : null; 35 * } 36 * }; 37 * </pre> 38 * <p> 39 * Once the inner Iterator's {@link Iterator#hasNext()} method returns false, 40 * {@link #nextIterator(int)} will be called to obtain another iterator, and so on 41 * until {@link #nextIterator(int)} returns null, indicating that the chain is exhausted. 42 * <p> 43 * NOTE: The LazyIteratorChain may contain no iterators. In this case the class will 44 * function as an empty iterator. 45 * 46 * @param <E> the type of elements in this iterator. 47 * @since 4.0 48 */ 49 public abstract class LazyIteratorChain<E> implements Iterator<E> { 50 51 /** The number of times {@link #next()} was already called. */ 52 private int callCounter; 53 54 /** Indicates that the Iterator chain has been exhausted. */ 55 private boolean chainExhausted; 56 57 /** The current iterator. */ 58 private Iterator<? extends E> currentIterator; 59 60 /** 61 * The "last used" Iterator is the Iterator upon which next() or hasNext() 62 * was most recently called used for the remove() operation only. 63 */ 64 private Iterator<? extends E> lastUsedIterator; 65 66 /** 67 * Return true if any Iterator in the chain has a remaining element. 68 * 69 * @return true if elements remain 70 */ 71 @Override 72 public boolean hasNext() { 73 updateCurrentIterator(); 74 lastUsedIterator = currentIterator; 75 76 return currentIterator.hasNext(); 77 } 78 79 /** 80 * Returns the next element of the current Iterator 81 * 82 * @return element from the current Iterator 83 * @throws java.util.NoSuchElementException if all the Iterators are exhausted 84 */ 85 @Override 86 public E next() { 87 updateCurrentIterator(); 88 lastUsedIterator = currentIterator; 89 90 return currentIterator.next(); 91 } 92 93 /** 94 * Gets the next iterator after the previous one has been exhausted. 95 * <p> 96 * This method <b>MUST</b> return null when there are no more iterators. 97 * 98 * @param count the number of time this method has been called (starts with 1) 99 * @return the next iterator, or null if there are no more. 100 */ 101 protected abstract Iterator<? extends E> nextIterator(int count); 102 103 /** 104 * Removes from the underlying collection the last element returned by the Iterator. 105 * <p> 106 * As with next() and hasNext(), this method calls remove() on the underlying Iterator. 107 * Therefore, this method may throw an UnsupportedOperationException if the underlying 108 * Iterator does not support this method. 109 * 110 * @throws UnsupportedOperationException if the remove operator is not 111 * supported by the underlying Iterator 112 * @throws IllegalStateException if the next method has not yet been called, 113 * or the remove method has already been called after the last call to the next method. 114 */ 115 @Override 116 public void remove() { 117 if (currentIterator == null) { 118 updateCurrentIterator(); 119 } 120 lastUsedIterator.remove(); 121 } 122 123 /** 124 * Updates the current iterator field to ensure that the current Iterator 125 * is not exhausted. 126 */ 127 private void updateCurrentIterator() { 128 if (callCounter == 0) { 129 currentIterator = nextIterator(++callCounter); 130 if (currentIterator == null) { 131 currentIterator = EmptyIterator.<E>emptyIterator(); 132 chainExhausted = true; 133 } 134 // set last used iterator here, in case the user calls remove 135 // before calling hasNext() or next() (although they shouldn't) 136 lastUsedIterator = currentIterator; 137 } 138 139 while (!currentIterator.hasNext() && !chainExhausted) { 140 final Iterator<? extends E> nextIterator = nextIterator(++callCounter); 141 if (nextIterator != null) { 142 currentIterator = nextIterator; 143 } else { 144 chainExhausted = true; 145 } 146 } 147 } 148 149 }