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}