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