//==============================================================================
// AbstractDocumentSet.java
//==============================================================================

package tribble.archive;

import java.io.IOException;

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

import java.util.AbstractSet;
import java.util.ArrayList;
import java.util.Set;


/*******************************************************************************
* Asbtract generic document set.
*
* <p>
* An <i>archive document set</i> is a collection of zero or more
* <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/AbstractDocumentSet.java"
*    >http://david.tribble.com/src/java/tribble/archive/AbstractDocumentSet.java</a>
*  </dd>
* <dt> <b>Documentation:</b> </dt>
*  <dd>
*   <a href="AbstractDocumentSet.html"
*    >http://david.tribble.com/docs/tribble/archive/AbstractDocumentSet.html</a>
*  </dd>
* </dl>
*
* <!-- ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ -->
* @version	API 2.0, $Revision: 1.1 $ $Date: 2008/04/03 21:53:34 $
* @since	2008-04-03
* @author	David R. Tribble (david&#64;tribble.com)
*	Copyright ©2009 by David R. Tribble, all rights reserved.
*
* @see	AbstractDocumentIterator
* @see	ArchiveReader
*/

public class AbstractDocumentSet
    extends java.util.AbstractSet<AbstractDocument>
    implements Set<AbstractDocument>
{
    static final String		REV =
        "@(#)tribble/archive/AbstractDocumentSet.java $Revision: 1.1 $ $Date: 2008/04/03 21:53:34 $\n";


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

    /** Document set. */
    protected ArrayList<AbstractDocument>	m_docs;

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


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

    /***************************************************************************
    * Constructor.
    *
    * @since	API 2.0, 2008-04-03
    */
    protected AbstractDocumentSet()
    { }


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

    /***************************************************************************
    * Determine the number of documents within this document set.
    *
    * @return
    * The count of documents contained within the document set (which can be
    * zero).
    *
    * @since	API 2.0, 2008-04-03
    */
    @Override
    public int size()
    {
        return m_docs.size();
    }


    /***************************************************************************
    * Get an iterator for the documents in this document set.
    *
    * @since	API 2.0, 2008-04-03
    */
    @Override
    public AbstractDocumentIterator iterator()
    {
        return new AbstractDocumentIterator(this);
    }


    /***************************************************************************
    * Add a document to this document set.
    *
    * <p>
    * Note: This method always throws <tt>UnsupportedOperationException</tt>.
    *
    * @since	API 2.0, 2008-04-03
    */
    @Override
    public boolean add(AbstractDocument doc)
        throws UnsupportedOperationException
    {
        throw new UnsupportedOperationException();
    }


    /***************************************************************************
    * Add a document to this document set.
    *
    * <p>
    * Note: This method differs from {@link #add add()} in that it is meant to
    * be called only by the subclasses implementing an {@link ArchiveReader}.
    *
    * @since	API 2.0, 2008-04-03
    */
    protected boolean addDocument(AbstractDocument doc)
    {
        if (m_docs == null)
            m_docs = new ArrayList<AbstractDocument>();
        return m_docs.add(doc);
    }
}

// End AbstractDocumentSet.java