//==============================================================================
// AbstractStorableDocument.java
//==============================================================================

package tribble.repository;

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

import java.lang.NullPointerException;
import java.lang.String;
import java.lang.System;
import java.lang.UnsupportedOperationException;


/*******************************************************************************
* Generic storable 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 base class that implement the
* {@link Document} interface do not throw any checked exceptions.
*
* <!-- ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ -->
* <dl>
* <dt> <b>Source code:</b> </dt>
*  <dd>
*   <a href="../../../src/java/tribble/repository/AbstractStorableDocument.java"
*    >http://david.tribble.com/src/java/tribble/repository/AbstractStorableDocument.java</a>
*  </dd>
* <dt> <b>Documentation:</b> </dt>
*  <dd>
*   <a href="AbstractStorableDocument.html"
*    >http://david.tribble.com/docs/tribble/repository/AbstractStorableDocument.html</a>
*  </dd>
* </dl>
*
* <!-- ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ -->
* @version	API 3.0, $Revision: 1.2 $ $Date: 2012/03/17 23:00:11 $
* @since	2008-04-10
* @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.
*/

public abstract class AbstractStorableDocument
    extends AbstractDocument
    implements StorableDocument
{
    static final String		REV =
        "@(#)tribble/repository/AbstractStorableDocument.java $Revision: 1.2 $ $Date: 2012/03/17 23:00:11 $\n";


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

    /** Input stream containing the contents of this document. */
    protected InputStream	m_in;


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

    /***************************************************************************
    * Constructor.
    *
    * @param	folder
    * The parent document folder that contains this document.
    *
    * @param	props
    * The properties which define the documents in the repository.
    *
    * @since	API 3.0, 2012-02-17
    */
    protected AbstractStorableDocument(Folder folder, DocumentProperty[] props)
    {
        super(folder, props);
    }


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

    /***************************************************************************
    * Close the input syteam for 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-10
    */
    protected void closeDataStream()
    {
        if (m_in != null)
        {
            try
            {
                m_in.close();
            }
            catch (IOException ex)
            { }

            m_in = null;
        }
    }


    /***************************************************************************
    * 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-10
    */
    @Override
    public void close()
    {
        // Close the data stream
        closeDataStream();
        super.close();
    }


    /***************************************************************************
    * Establish the ID of this repository document.
    *
    * @param	id
    * A name that identifies the document within the repository.
    * Whether or not this name is unique depends on the implementation.
    * This cannot be null.
    *
    * @throws	IOException
    * Thrown if an error occurred while accessing the document.
    *
    * @throws	UnsupportedOperationException (unchecked)
    * Thrown if this operation is not allowed by the implementation, i.e.,
    * if IDs are assigned to repository documents by some other means.
    *
    * @throws	NullPointerException (unchecked)
    * Thrown if <tt>id</tt> is null.
    *
    * @throws	IllegalStateException (unchecked)
    * Thrown if {@link #close()} has been called for this object.
    *
    * @since	API 2.0, 2008-04-10
    */
    //@Override
    public void setID(String id)
        throws IOException, UnsupportedOperationException
    {
        checkOpen();
        if (id == null)
            throw new NullPointerException();
        m_id = id;
    }


    /***************************************************************************
    * Establish the data size for this repository document.
    *
    * @param	len
    * 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-10
    */
    //@Override
    public void setSize(long len)
    {
        checkOpen();
        m_size = len;
    }


    /***************************************************************************
    * Set the value of a property in this repository document.
    *
    * @param	prop
    * The name of the document property to set.
    *
    * @param	val
    * The new property value.
    *
    * @throws	IOException
    * Thrown if an error occurred while modifying the document.
    *
    * @throws	IllegalStateException (unchecked)
    * Thrown if {@link #close()} has been called for this object.
    *
    * @since	API 2.0, 2008-04-10
    */
    //@Override
    public void setProperty(String prop, Object val)
        throws IOException
    {
        // Sanity checks
        checkOpen();
        if (m_props == null)
            throw new IOException("Document has no properties");

        // Set the document property value
        for (int i = 0;  i < m_props.length;  i++)
        {
            if (m_props[i].getName().equals(prop))
            {
                m_propVals[i] = val;
                return;
            }
        }

        throw new IOException("Document has no such property: " + prop);
    }


    /***************************************************************************
    * Add a property to this repository document.
    *
    * @param	prop
    * A property to add to this document.
    *
    * @throws	IOException
    * Thrown if the property already exists in this document, or if an error
    * occurred while modifying the document.
    *
    * @throws	UnsupportedOperationException (unchecked)
    * Thrown if this method is not supported by the implementation of this
    * interface.
    *
    * @throws	IllegalStateException (unchecked)
    * Thrown if {@link #close()} has been called for this object.
    *
    * @since	API 2.0, 2008-04-10
    */
    //@Override
    public void addProperty(DocumentProperty prop)
        throws UnsupportedOperationException, IOException
    {
        // Sanity check
        checkOpen();

        // Ensure that there are properties
        if (m_props == null)
            m_props = new DocumentProperty[0];

        synchronized (m_props)
        {
            String		name;
            int			nProps;
            DocumentProperty[]	newProps;

            // Ensure that the document property does not already exist
            name = prop.getName();
            nProps = m_props.length;

            for (int i = 0;  i < nProps;  i++)
            {
                if (m_props[i].getName().equals(name))
                    throw new IOException("Document property already exists: "
                        + name);
            }

            // Add the new property to the document
            newProps = new DocumentProperty[nProps + 1];
            for (int i = 0;  i < nProps;  i++)
            {
                newProps[i] = m_props[i];
                m_props[i] = null;
            }
            newProps[nProps] = prop;
            m_props = newProps;
        }
    }


    /***************************************************************************
    * Establish the input data stream containing the contents of this repository
    * document.
    *
    * @param	in
    * A binary data stream from which the contents of the document are to be
    * read.  The reading occurs when the
    * {@link WritableFolder#storeDocument WritableFolder.storeDocument()}
    * method is called and passed this document object.  The stream will be
    * closed (by calling its <tt>close()</tt> method) after the data is
    * completely read from the stream (i.e., its <tt>read()</tt> method returns
    * -1).  The stream will also be closed (if it is still open) when this
    * document object's {@link #close close()} method is called.
    *
    * @throws	IOException
    * Thrown if an error occurred while accessing the document.
    *
    * @throws	NullPointerException (unchecked)
    * Thrown if <tt>in</tt> is null.
    *
    * @since API 3.0, 2012-02-17
    */
    public void setInputStream(InputStream in)
        throws IOException
    {
        checkOpen();
        if (in == null)
            throw new NullPointerException();
        m_in = in;
    }


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


    /***************************************************************************
    * Indicate that reading of the input data stream for this repository
    * document is complete.
    *
    * <p>
    * This method is called when the
    * {@link RepositoryWriter#storeDocument RepositoryWriter.storeDocument()}
    * method is called and passed this document object, once all of the content
    * data for the document has been read.  The input stream is closed (by
    * calling its {@link #close close()} method), and then this method is
    * called.  Any other resources associated with this document should then be
    * deallocated.
    *
    * @since	API 2.0, 2008-04-10
    */
    //@Override
    public void doneReading()
    {
        // Close the input data stream
        checkOpen();
        closeDataStream();
    }
}

// End AbstractStorableDocument.java