// This Source Code is in the Public Domain per: http://litesoft.org/License.txt
package org.litesoft.core.util;

import java.util.*;

/**
 * This class's purpose is to be extended by a concrete Filtering Iterator
 * that is wrapping/decorating another Iterator.  The Filtering works
 * by looking ahead for an entry that is acceptable.  This acceptablity
 * is determined by the <i>keepThis</i> method.<p>
 *
 * @author George Smith
 * @version 1.0 7/28/01
 * @see <a href="http://java.sun.com/j2se/1.3/docs/api/java/lang/Util/Iterator.html">java.util.Iterator</a>
 */

public abstract class AbstractFilteringIterator<T> extends AbstractWrappingIterator<T>
{
    /**
     * Construct a Filtering (of another Iterator) Iterator.<p>
     *
     * @param pIterator Iterator to be <i>Filtered</i> (!null).<p>
     *
     * @see AbstractWrappingIterator
     * @see <a href="http://java.sun.com/j2se/1.3/docs/api/java/lang/Util/Iterator.html">java.util.Iterator</a>
     */
    protected AbstractFilteringIterator( Iterator<T> pIterator )
            throws NullPointerException
    {
        super( pIterator );
    }

    private T lookAheadObject = null;
    private boolean lookAheadValid = false;

    /**
     * This method is the <i>heart</i> of a Filtering Iterator.
     * It determines if an Object from the underlying Iterator
     * is to be kept or tossed.<p>
     * <p/>
     * It is abstract here because there is no reasonable, common,
     * implementation and to remind the developer who extends
     * this class that they need to implement it.<p>
     *
     * @param pPossibleValue Object reference to test for keeping (not tossing).<p>
     *
     * @return <tt>true</tt> if the <i>pPossibleValue</i> should be kept (not tossed).
     */
    abstract protected boolean keepThis( T pPossibleValue );

    /**
     * Returns true if the iteration has more elements.<p>
     * <p/>
     * This method relies on a look-ahead buffer and keepThis() to
     * implement the filtering.<p>
     *
     * @see <a href="http://java.sun.com/j2se/1.3/docs/api/java/lang/Util/Iterator.html#hasNext()">java.util.Iterator#hasNext()</a>
     * @see #keepThis(Object)
     */
    @Override
    public final boolean hasNext()
    {
        while ( !lookAheadValid && super.hasNext() )
        {
            lookAheadValid = keepThis( lookAheadObject = super.next() );
        }

        return lookAheadValid;
    }

    /**
     * Returns the next element in the interation.
     * <p/>
     * This method relies on hasNext (and a look-ahead buffer) to
     * implement the filtering.<p>
     *
     * @see <a href="http://java.sun.com/j2se/1.3/docs/api/java/lang/Util/Iterator.html#next()">java.util.Iterator#next()</a>
     * @see #next()
     */
    @Override
    public final T next()
    {
        if ( !hasNext() )
        {
            super.next(); // throw exception
        }

        lookAheadValid = false;
        return lookAheadObject;
    }
}