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

package tribble.repository;

import java.io.IOException;
import java.io.InputStream;

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


/*******************************************************************************
* Generic read-only repository document.
*
* <p>
* A <i>repository document</i> is composed of content data (such as an image,
* text, or other kind of user data) and zero 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/repository/AbstractDocument.java"
*    >http://david.tribble.com/src/java/tribble/repository/AbstractDocument.java</a>
*  </dd>
* <dt> <b>Documentation:</b> </dt>
*  <dd>
*   <a href="AbstractDocument.html"
*    >http://david.tribble.com/docs/tribble/repository/AbstractDocument.html</a>
*  </dd>
* </dl>
*
* <!-- ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ -->
* @version	API 3.0, $Revision: 1.2 $ $Date: 2012/03/17 22:53:47 $
* @since	2008-04-03
* @author	David R. Tribble (david&#64;tribble.com)<br/>
*	Copyright ©2008-2012 by David R. Tribble, all rights reserved.<br/>
*	Permission is granted to any person or entity except those designated
*	by the United States Department of State as a terrorist or terrorist
*	government or agency, to use and distribute this source code provided
*	that the original copyright notice remains present and unaltered.
*
* @see	AbstractStorableDocument
*/

public abstract class AbstractDocument
    implements Document
{
    static final String		REV =
        "@(#)tribble/repository/AbstractDocument.java $Revision: 1.2 $ $Date: 2012/03/17 22:53:47 $\n";


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

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


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

    /** Parent folder. */
    protected Folder			m_folder;

    /** 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	folder
    * The parent document folder that contains this document.
    *
    * @param	props
    * The properties which define the documents in the repository.
    * This can be null.
    *
    * @since	API 3.0, 2012-02-17
    */
    protected AbstractDocument(Folder folder, DocumentProperty[] props)
    {
        // Initialize
        m_folder = folder;
        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 repository 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 repository 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 repository folder that contains this document.
    *
    * @return
    * The parent folder for this document, or null if the document does not have
    * a parent folder.
    *
    * @throws       IOException
    * Thrown if an error occurred while accessing the document.
    *
    * @since API 3.0, 2012-02-17
    */
    //@Override
    public Folder getFolder()
    {
        return m_folder;
    }


    /***************************************************************************
    * Retrieve the ID of this repository document.
    *
    * @return
    * A name that identifies the document within the repository.
    *
    * @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 repository 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 value of a property in this repository 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");

        // Find the specified property
        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);
    }


    /***************************************************************************
    * Retrieve the properties for this repository 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;
    }


    /***************************************************************************
    * Open a readable data stream to the contents of this repository document.
    *
    * @return
    * A readable binary data stream containing the contents of the document.
    * Note that the stream must be closed (by calling its <tt>close()</tt>
    * method) after the data is read.
    *
    * @throws	IOException
    * Thrown if an error occurred while accessing the document.
    *
    * @since API 3.0, 2012-02-17
    */
    public abstract InputStream getInputStream()
        throws IOException;


    /***************************************************************************
    * @deprecated
    * <!-- Since 3.0, 2012-02-16 -->
    * Use {@link #getInputStream()} instead.
    *
    * @since	API 2.0, 2008-04-03
    */
    public InputStream getDataStream()
        throws IOException
    {
        throw new IOException("Deprecated. Use setInputStream() instead.");
    }
}

// End AbstractDocument.java