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