    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 * subclasses 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 * @param <E> the type of elements in this iterator.
    047 * @since 4.0
    048 */
    049public abstract class LazyIteratorChain<E> implements Iterator<E> {
    050
    051    /** The number of times {@link #next()} was already called. */
    052    private int callCounter;
    053
    054    /** Indicates that the Iterator chain has been exhausted. */
    055    private boolean chainExhausted;
    056
    057    /** The current iterator. */
    058    private Iterator<? extends E> currentIterator;
    059
    060    /**
    061     * The "last used" Iterator is the Iterator upon which next() or hasNext()
    062     * was most recently called used for the remove() operation only.
    063     */
    064    private Iterator<? extends E> lastUsedIterator;
    065
    066    /**
    067     * Return true if any Iterator in the chain has a remaining element.
    068     *
    069     * @return true if elements remain
    070     */
    071    @Override
    072    public boolean hasNext() {
    073        updateCurrentIterator();
    074        lastUsedIterator = currentIterator;
    075
    076        return currentIterator.hasNext();
    077    }
    078
    079    /**
    080     * Returns the next element of the current Iterator
    081     *
    082     * @return element from the current Iterator
    083     * @throws java.util.NoSuchElementException if all the Iterators are exhausted
    084     */
    085    @Override
    086    public E next() {
    087        updateCurrentIterator();
    088        lastUsedIterator = currentIterator;
    089
    090        return currentIterator.next();
    091    }
    092
    093    /**
    094     * Gets the next iterator after the previous one has been exhausted.
    095     * <p>
    096     * This method <b>MUST</b> return null when there are no more iterators.
    097     *
    098     * @param count the number of time this method has been called (starts with 1)
    099     * @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}