    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}