    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 * sub-classes and allows to lazily create the Iterators as they are accessed:
    031 * <pre>
    032 * return new LazyIteratorChain&lt;String&gt;() {
    033 *     protected Iterator&lt;String&gt; 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 * @since 4.0
    047 */
    048public abstract class LazyIteratorChain<E> implements Iterator<E> {
    049
    050    /** The number of times {@link #next()} was already called. */
    051    private int callCounter = 0;
    052
    053    /** Indicates that the Iterator chain has been exhausted. */
    054    private boolean chainExhausted = false;
    055
    056    /** The current iterator. */
    057    private Iterator<? extends E> currentIterator = null;
    058
    059    /**
    060     * The "last used" Iterator is the Iterator upon which next() or hasNext()
    061     * was most recently called used for the remove() operation only.
    062     */
    063    private Iterator<? extends E> lastUsedIterator = null;
    064
    065    //-----------------------------------------------------------------------
    066
    067    /**
    068     * Gets the next iterator after the previous one has been exhausted.
    069     * <p>
    070     * This method <b>MUST</b> return null when there are no more iterators.
    071     *
    072     * @param count the number of time this method has been called (starts with 1)
    073     * @return the next iterator, or null if there are no more.
    074     */
    075    protected abstract Iterator<? extends E> nextIterator(int count);
    076
    077    /**
    078     * Updates the current iterator field to ensure that the current Iterator
    079     * is not exhausted.
    080     */
    081    private void updateCurrentIterator() {
    082        if (callCounter == 0) {
    083            currentIterator = nextIterator(++callCounter);
    084            if (currentIterator == null) {
    085                currentIterator = EmptyIterator.<E>emptyIterator();
    086                chainExhausted = true;
    087            }
    088            // set last used iterator here, in case the user calls remove
    089            // before calling hasNext() or next() (although they shouldn't)
    090            lastUsedIterator = currentIterator;
    091        }
    092
    093        while (currentIterator.hasNext() == false && !chainExhausted) {
    094            final Iterator<? extends E> nextIterator = nextIterator(++callCounter);
    095            if (nextIterator != null) {
    096                currentIterator = nextIterator;
    097            } else {
    098                chainExhausted = true;
    099            }
    100        }
    101    }
    102
    103    //-----------------------------------------------------------------------
    104
    105    /**
    106     * Return true if any Iterator in the chain has a remaining element.
    107     *
    108     * @return true if elements remain
    109     */
    110    @Override
    111    public boolean hasNext() {
    112        updateCurrentIterator();
    113        lastUsedIterator = currentIterator;
    114
    115        return currentIterator.hasNext();
    116    }
    117
    118    /**
    119     * Returns the next element of the current Iterator
    120     *
    121     * @return element from the current Iterator
    122     * @throws java.util.NoSuchElementException if all the Iterators are exhausted
    123     */
    124    @Override
    125    public E next() {
    126        updateCurrentIterator();
    127        lastUsedIterator = currentIterator;
    128
    129        return currentIterator.next();
    130    }
    131
    132    /**
    133     * Removes from the underlying collection the last element returned by the Iterator.
    134     * <p>
    135     * As with next() and hasNext(), this method calls remove() on the underlying Iterator.
    136     * Therefore, this method may throw an UnsupportedOperationException if the underlying
    137     * Iterator does not support this method.
    138     *
    139     * @throws UnsupportedOperationException if the remove operator is not
    140     *   supported by the underlying Iterator
    141     * @throws IllegalStateException if the next method has not yet been called,
    142     *   or the remove method has already been called after the last call to the next method.
    143     */
    144    @Override
    145    public void remove() {
    146        if (currentIterator == null) {
    147            updateCurrentIterator();
    148        }
    149        lastUsedIterator.remove();
    150    }
    151
    152}