//==============================================================================
// AbstractDocumentIterator.java
//==============================================================================

package tribble.archive;

import java.io.IOException;

import java.lang.Exception;
import java.lang.UnsupportedOperationException;
import java.lang.String;

import java.util.ConcurrentModificationException;
import java.util.Iterator;
import java.util.NoSuchElementException;


/*******************************************************************************
* Abstract generic document set iterator.
*
* <p>
* An <i>archive document set iterator</i> is an iterator over a collection of
* <i>archive documents</i>.  Such a set is typically the result of a query
* performed on an <i>archive</i>.
*
* <p>
* Note: This requires Java 1.5 or later.
*
* <!-- ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ -->
* <dl>
* <dt> <b>Source code:</b> </dt>
*  <dd>
*   <a href="../../../src/java/tribble/archive/AbstractDocumentIterator.java"
*    >http://david.tribble.com/src/java/tribble/archive/AbstractDocumentIterator.java</a>
*  </dd>
* <dt> <b>Documentation:</b> </dt>
*  <dd>
*   <a href="AbstractDocumentIterator.html"
*    >http://david.tribble.com/docs/tribble/archive/AbstractDocumentIterator.html</a>
*  </dd>
* </dl>
*
* <!-- ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ -->
* @version	API 2.0, $Revision: 1.1 $ $Date: 2008/04/03 21:52:56 $
* @since	2008-04-03
* @author	David R. Tribble (david&#64;tribble.com)
*	Copyright ©2009 by David R. Tribble, all rights reserved.
*
* @see	AbstractDocumentSet
*/

public class AbstractDocumentIterator
    implements Iterator<AbstractDocument>
{
    static final String		REV =
        "@(#)tribble/archive/AbstractDocumentIterator.java $Revision: 1.1 $ $Date: 2008/04/03 21:52:56 $\n";


// ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~
// Variables

    /** Parent document set. */
    protected AbstractDocumentSet	m_set;

    /** Current document index within the set. */
    protected int			m_pos;

    /** Modification serial number. */
    protected int			m_modCount;


// ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~
// Constructors

    /***************************************************************************
    * Constructor.
    *
    * @param	set
    * Parent document set for which this iterator was created.
    *
    * @since	API 2.0, 2008-04-03
    */
    protected AbstractDocumentIterator(AbstractDocumentSet set)
    {
        m_set = set;
    }


// ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~
// Methods

    /***************************************************************************
    * Determine if there are any more documents within the document set.
    *
    * @return
    * True if one or more documents remain within the document set, false
    * otherwise.
    *
    * @throws	IOException
    * Thrown if an error occurred while accessing the document
    * iterator.
    *
    * @since	API 2.0, 2008-04-03
    */
    //@Override
    public boolean hasNext()
    {
        if (m_set == null)
            return false;
        return (m_pos < m_set.size());
    }


    /***************************************************************************
    * Retrieve the next document within the document set.
    * Also advances the iterator to the next document in the set.
    *
    * <p>
    * Note that this method also removes the previous document from the document
    * set, so calling {@link #remove remove()} is not necessary.
    * Note also that removed documents do not have their
    * {@link ArchiveDocument#close close()} methods called, which could leave
    * them in an unstable state.
    *
    * @return
    * The next archive document in the set.
    *
    * @since	API 2.0, 2008-04-03
    */
    //@Override
    public AbstractDocument next()
    {
        AbstractDocument	doc;

        // Sanity checks
        if (m_set == null)
            throw new NoSuchElementException();
        if (m_modCount != m_set.m_modCount)
            throw new ConcurrentModificationException();
        if (m_pos >= m_set.size())
            throw new NoSuchElementException();

        // Remove the previous document from the set,
        //  since it is no longer needed
        if (m_pos > 0)
        {
            m_set.m_modCount = ++m_modCount;
            m_set.m_docs.set(m_pos - 1, null);
        }

        // Get the next document and advance the pointer
        doc = m_set.m_docs.get(m_pos++);
        return doc;
    }


    /***************************************************************************
    * Remove the current document from the document set.
    *
    * <p>
    * Note that calling this method is not necessary, since {@link #next}
    * automatically removes each document it previously returned.
    * Note also that removed documents do not have their
    * {@link ArchiveDocument#close close()} methods called, which could leave
    * them in an unstable state.
    *
    * @throws	UnsupportedOperationException (unchecked)
    * Thrown if this operation is not supported by this iterator.
    *
    * @throws	IllegalStateException (unchecked)
    * Thrown if {@link #next} has not been called, or if {@link #remove} has
    * already been called on the same item in the set.
    *
    * @since	API 2.0, 2008-04-03
    */
    //@Override
    public void remove()
        throws UnsupportedOperationException, IllegalStateException
    {
        // Sanity checks
        if (m_set == null)
            throw new NoSuchElementException();
        if (m_pos == 0)
            throw new IllegalStateException("next() not called yet");
        if (m_modCount != m_set.m_modCount)
            throw new ConcurrentModificationException();
        if (m_set.m_docs.get(m_pos) == null)
            throw new IllegalStateException("Document already removed");

        // Remove the document from the document set
        m_set.m_modCount = ++m_modCount;
        m_set.m_docs.set(m_pos, null);
    }
}

// End AbstractDocumentIterator.java