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.Iterator; 020 021/** 022 * An LazyIteratorChain is an Iterator that wraps a number of Iterators in a lazy manner. 023 * <p> 024 * This class makes multiple iterators look like one to the caller. When any 025 * method from the Iterator interface is called, the LazyIteratorChain will delegate 026 * to a single underlying Iterator. The LazyIteratorChain will invoke the Iterators 027 * in sequence until all Iterators are exhausted. 028 * <p> 029 * The Iterators are provided by {@link #nextIterator(int)} which has to be overridden by 030 * subclasses and allows to lazily create the Iterators as they are accessed: 031 * <pre> 032 * return new LazyIteratorChain<String>() { 033 * protected Iterator<String> nextIterator(int count) { 034 * return count == 1 ? Arrays.asList("foo", "bar").iterator() : null; 035 * } 036 * }; 037 * </pre> 038 * <p> 039 * Once the inner Iterator's {@link Iterator#hasNext()} method returns false, 040 * {@link #nextIterator(int)} will be called to obtain another iterator, and so on 041 * until {@link #nextIterator(int)} returns null, indicating that the chain is exhausted. 042 * <p> 043 * NOTE: The LazyIteratorChain may contain no iterators. In this case the class will 044 * function as an empty iterator. 045 * 046 * @param <E> the type of elements in this iterator. 047 * @since 4.0 048 */ 049public abstract class LazyIteratorChain<E> implements Iterator<E> { 050 051 /** The number of times {@link #next()} was already called. */ 052 private int callCounter; 053 054 /** Indicates that the Iterator chain has been exhausted. */ 055 private boolean chainExhausted; 056 057 /** The current iterator. */ 058 private Iterator<? extends E> currentIterator; 059 060 /** 061 * The "last used" Iterator is the Iterator upon which next() or hasNext() 062 * was most recently called used for the remove() operation only. 063 */ 064 private Iterator<? extends E> lastUsedIterator; 065 066 /** 067 * Return true if any Iterator in the chain has a remaining element. 068 * 069 * @return true if elements remain 070 */ 071 @Override 072 public boolean hasNext() { 073 updateCurrentIterator(); 074 lastUsedIterator = currentIterator; 075 076 return currentIterator.hasNext(); 077 } 078 079 /** 080 * Returns the next element of the current Iterator 081 * 082 * @return element from the current Iterator 083 * @throws java.util.NoSuchElementException if all the Iterators are exhausted 084 */ 085 @Override 086 public E next() { 087 updateCurrentIterator(); 088 lastUsedIterator = currentIterator; 089 090 return currentIterator.next(); 091 } 092 093 /** 094 * Gets the next iterator after the previous one has been exhausted. 095 * <p> 096 * This method <b>MUST</b> return null when there are no more iterators. 097 * 098 * @param count the number of time this method has been called (starts with 1) 099 * @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}