/*
 * Copyright (C) 2007 The Guava Authors
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.apache.cassandra.index.sasi.utils;

import java.util.NoSuchElementException;

import com.google.common.collect.PeekingIterator;

import static com.google.common.base.Preconditions.checkState;

// This is fork of the Guava AbstractIterator, the only difference
// is that state & next variables are now protected, this was required
// for SkippableIterator.skipTo(..) to void all previous state.
public abstract class AbstractIterator<T> implements PeekingIterator<T>
{
    protected State state = State.NOT_READY;

    
Constructor for use by subclasses. /** Constructor for use by subclasses. */
    protected AbstractIterator() {}

    protected enum State
    {
        
We have computed the next element and haven't returned it yet. /** We have computed the next element and haven't returned it yet. */
        READY,

        
We haven't yet computed or have already returned the element. /** We haven't yet computed or have already returned the element. */
        NOT_READY,

        
We have reached the end of the data and are finished. /** We have reached the end of the data and are finished. */
        DONE,

        
We've suffered an exception and are kaput. /** We've suffered an exception and are kaput. */
        FAILED,
    }

    protected T next;

    
Returns the next element. Note: the implementation must call endOfData() when there are no elements left in the iteration. Failure to do so could result in an infinite loop. 
The initial invocation of hasNext() or next() calls this method, as does the first invocation of hasNext or 
next following each successful call to next. Once the implementation either invokes endOfData or throws an exception, computeNext is guaranteed to never be called again. 
If this method throws an exception, it will propagate outward to the hasNext or next invocation that invoked this method. Any further attempts to use the iterator will result in an IllegalStateException. 
The implementation of this method may not invoke the hasNext, next, or peek() methods on this instance; if it does, an IllegalStateException will result. 
Throws:
RuntimeException – if any unrecoverable error happens. This exception will propagate outward to the hasNext(), next(), or peek() invocation that invoked this method. Any further attempts to use the iterator will result in an IllegalStateException.
Returns:
the next element if there was one. If endOfData was called during execution, the return value will be ignored./**
     * Returns the next element. <b>Note:</b> the implementation must call {@link
     * #endOfData()} when there are no elements left in the iteration. Failure to
     * do so could result in an infinite loop.
     *
     * <p>The initial invocation of {@link #hasNext()} or {@link #next()} calls
     * this method, as does the first invocation of {@code hasNext} or {@code
     * next} following each successful call to {@code next}. Once the
     * implementation either invokes {@code endOfData} or throws an exception,
     * {@code computeNext} is guaranteed to never be called again.
     *
     * <p>If this method throws an exception, it will propagate outward to the
     * {@code hasNext} or {@code next} invocation that invoked this method. Any
     * further attempts to use the iterator will result in an {@link
     * IllegalStateException}.
     *
     * <p>The implementation of this method may not invoke the {@code hasNext},
     * {@code next}, or {@link #peek()} methods on this instance; if it does, an
     * {@code IllegalStateException} will result.
     *
     * @return the next element if there was one. If {@code endOfData} was called
     *     during execution, the return value will be ignored.
     * @throws RuntimeException if any unrecoverable error happens. This exception
     *     will propagate outward to the {@code hasNext()}, {@code next()}, or
     *     {@code peek()} invocation that invoked this method. Any further
     *     attempts to use the iterator will result in an
     *     {@link IllegalStateException}.
     */
    protected abstract T computeNext();

    
Implementations of computeNext must invoke this method when
there are no elements left in the iteration.
Returns:
null; a convenience so your computeNext implementation can use the simple statement return endOfData();/**
     * Implementations of {@link #computeNext} <b>must</b> invoke this method when
     * there are no elements left in the iteration.
     *
     * @return {@code null}; a convenience so your {@code computeNext}
     *     implementation can use the simple statement {@code return endOfData();}
     */
    protected final T endOfData()
    {
        state = State.DONE;
        return null;
    }

    public final boolean hasNext()
    {
        checkState(state != State.FAILED);

        switch (state)
        {
            case DONE:
                return false;

            case READY:
                return true;

            default:
        }

        return tryToComputeNext();
    }

    protected boolean tryToComputeNext()
    {
        state = State.FAILED; // temporary pessimism
        next = computeNext();

        if (state != State.DONE)
        {
            state = State.READY;
            return true;
        }

        return false;
    }

    public final T next()
    {
        if (!hasNext())
            throw new NoSuchElementException();

        state = State.NOT_READY;
        return next;
    }

    public void remove()
    {
        throw new UnsupportedOperationException();
    }

    
Returns the next element in the iteration without advancing the iteration, according to the contract of PeekingIterator.peek(). 
Implementations of AbstractIterator that wish to expose this functionality should implement PeekingIterator. /**
     * Returns the next element in the iteration without advancing the iteration,
     * according to the contract of {@link PeekingIterator#peek()}.
     *
     * <p>Implementations of {@code AbstractIterator} that wish to expose this
     * functionality should implement {@code PeekingIterator}.
     */
    public final T peek()
    {
        if (!hasNext())
            throw new NoSuchElementException();

        return next;
    }
}