//==============================================================================
// AbstractDocument.java
//==============================================================================

package tribble.archive;

import java.io.IOException;

import java.lang.String;
import java.lang.System;
import java.lang.Throwable;


/*******************************************************************************
* Generic read-only archive document.
*
* <p>
* An <i>archive document</i> is composed of content data (such as an image,
* text, or other kind of user data) and one or more <i>properties</i>.
*
* <p>
* Most of the methods in this class do not throw any checked exceptions.
*
* <p>
* Note: This requires Java 1.5 or later.
*
* <!-- ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ -->
* <dl>
* <dt> <b>Source code:</b> </dt>
*  <dd>
*   <a href="../../../src/java/tribble/archive/AbstractDocument.java"
*    >http://david.tribble.com/src/java/tribble/archive/AbstractDocument.java</a>
*  </dd>
* <dt> <b>Documentation:</b> </dt>
*  <dd>
*   <a href="AbstractDocument.html"
*    >http://david.tribble.com/docs/tribble/archive/AbstractDocument.html</a>
*  </dd>
* </dl>
*
* <!-- ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ -->
* @version	API 2.0, $Revision: 1.1 $ $Date: 2008/04/03 22:05:46 $
* @since	2008-04-03
* @author	David R. Tribble (david&#64;tribble.com)
*	Copyright ©2004 by David R. Tribble, all rights reserved.
*
* @see	AbstractWritableDocument
*/

public abstract class AbstractDocument
    implements ArchiveDocument
{
    static final String		REV =
        "@(#)tribble/archive/AbstractDocument.java $Revision: 1.1 $ $Date: 2008/04/03 22:05:46 $\n";


// ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~
// Constants

    /** Dummy value denoting a closed document. */
    private static final DocumentProperty[]	CLOSED =
        new DocumentProperty[0];


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

    /** Document ID. */
    protected String			m_id;

    /** Document size (typically in bytes). */
    protected long			m_size =	-1;

    /** Properties. */
    protected DocumentProperty[]	m_props;

    /** Property values. */
    protected Object[]			m_propVals;


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

    /***************************************************************************
    * Constructor.
    *
    * @param	props
    * The properties which define the documents in the archive.
    * This can be null.
    *
    * @since	API 2.0, 2008-04-03
    */
    protected AbstractDocument(DocumentProperty[] props)
    {
        // Initialize
        m_props = props;
        if (props != null)
            m_propVals = new Object[m_props.length];
    }


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

    /***************************************************************************
    * Finalization.
    *
    * @since	API 2.0, 2008-04-03
    */
    @Override
    protected void finalize()
        throws Throwable
    {
        close();
        super.finalize();
    }


    /***************************************************************************
    * Check that this archive document has not been closed.
    *
    * @throws	IllegalStateException (unchecked)
    * Thrown if {@link #close} has been called for this object.
    *
    * @since	API 2.0, 2008-04-03
    */
    protected void checkOpen()
        throws IllegalStateException
    {
        if (m_props == CLOSED)
            throw new IllegalStateException("Document is closed");
    }


    /***************************************************************************
    * Close this archive document.
    * Deallocates all resources associated with the document.  Any further use
    * of the document will result in exceptions.
    *
    * <p>
    * Note that this method can be called multiple times with no ill effects.
    *
    * <p>
    * Note that this method does not throw any exceptions.
    *
    * @since	API 2.0, 2008-04-03
    */
    //@Override
    public void close()
    {
        m_props = CLOSED;
    }


    /***************************************************************************
    * Retrieve the ID of this archive document.
    *
    * @return
    * A name that identifies the document within the archive.
    *
    * @throws	IOException
    * Thrown if an error occurred while accessing the document.
    *
    * @since	API 2.0, 2008-04-03
    */
    //@Override
    public String getID()
    {
        return m_id;
    }


    /***************************************************************************
    * Retrieve the size of the data for this archive document.
    *
    * @return
    * The size (typically in bytes) of the document data, or -1 if the size is
    * not known.
    *
    * @throws	IllegalStateException (unchecked)
    * Thrown if {@link #close} has been called for this object.
    *
    * @since	API 2.0, 2008-04-03
    */
    //@Override
    public long getSize()
    {
        checkOpen();
        return m_size;
    }


    /***************************************************************************
    * Retrieve the properties for this archive document.
    *
    * @return
    * The properties defined for this document.
    *
    * @throws	IllegalStateException (unchecked)
    * Thrown if {@link #close} has been called for this object.
    *
    * @since	API 2.0, 2008-04-03
    */
    //@Override
    public DocumentProperty[] getProperties()
    {
        DocumentProperty[]	copy;

        // Build a copy of the properties
        checkOpen();
        copy = new DocumentProperty[m_props.length];
        System.arraycopy(m_props, 0, copy, 0, m_props.length);
        return copy;
    }


    /***************************************************************************
    * Retrieve the value of a property in this archive document.
    *
    * @param	prop
    * The name of the document property value to retrieve.
    *
    * @return
    * The property value (which may be null).
    *
    * @throws	IOException
    * Thrown if the document does not have the specified property.
    *
    * @throws	IllegalStateException (unchecked)
    * Thrown if {@link #close} has been called for this object.
    *
    * @since	API 2.0, 2008-04-03
    */
    //@Override
    public Object getProperty(String prop)
        throws IOException
    {
        // Sanity checks
        checkOpen();
        if (m_propVals == null)
            throw new IOException("Document has no properties");

        for (int i = 0;  i < m_props.length;  i++)
        {
            if (m_props[i].getName().equals(prop))
                return m_propVals[i];
        }

        throw new IOException("No such document property: " + prop);
    }
}

// End AbstractDocument.java