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 }