//==============================================================================
// StorableDocument.java
//==============================================================================

package tribble.repository;

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

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


/*******************************************************************************
* Generic storable (writable) repository document.
*
* <p>
* This interface extends {@link Document} by adding methods that allow
* a document to be created and modified.  This is necessary for applications
* that create document objects, allowing them to set the document properties,
* data contents, etc., prior to storing it into a repository system.
*
* <p>
* Note that subclasses of this interface should <i>not</i> provide a public
* constructor, since document objects are meant to be created using the
* {@link FolderWriter#createDocument FolderWriter.createDocument()}
* method instead.  This is so that document IDs and default document properties
* can be established for newly created documents by the {@link FolderWriter}
* implementation as soon as possible, at the time that the document objects are
* created.
*
* <!-- ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ -->
* <dl>
* <dt> <b>Source code:</b> </dt>
*  <dd>
*   <a href="../../../src/java/tribble/repository/StorableDocument.java"
*    >http://david.tribble.com/src/java/tribble/repository/StorableDocument.java</a>
*  </dd>
* <dt> <b>Documentation:</b> </dt>
*  <dd>
*   <a href="StorableDocument.html"
*    >http://david.tribble.com/docs/tribble/repository/StorableDocument.html</a>
*  </dd>
* </dl>
*
* <!-- ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ -->
* @version	API 3.0, $Revision: 1.2 $ $Date: 2012/03/17 23:01:58 $
* @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.
*
* @see	AbstractStorableDocument
* @see	RepositoryWriter
* @see	WritableFolder
*/

public interface StorableDocument
    extends Document
{
    static final String		REV =
        "@(#)tribble/repository/StorableDocument.java $Revision: 1.2 $ $Date: 2012/03/17 23:01:58 $\n";


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

    /***************************************************************************
    * Establish the ID of this repository document.
    *
    * @param	id
    * A name that identifies the document within the repository.
    * Whether or not this name must be unique within the repository folder
    * containing it depends on the implementation.
    *
    * @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.
    *
    * @since	API 2.0, 2008-04-10
    */
    public abstract void setID(String id)
        throws IOException, UnsupportedOperationException;


    /***************************************************************************
    * 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
    * indeterminate.
    *
    * @throws	IOException
    * Thrown if an error occurred while modifying the document.
    *
    * @throws	UnsupportedOperationException (unchecked)
    * Thrown if this operation is not allowed by the implementation, i.e.,
    * if sizes are assigned to repository documents by some other means.
    *
    * @since	API 2.0, 2008-04-10
    */
    public abstract void setSize(long len)
        throws IOException, UnsupportedOperationException;


    /***************************************************************************
    * Establish 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, or
    * if the document does not have the specified property.
    *
    * @since	API 2.0, 2008-04-10
    */
    public abstract void setProperty(String prop, Object val)
        throws IOException;


    /***************************************************************************
    * Add a property to this repository document.
    *
    * @param	prop
    * A property to associate with this document.
    *
    * @throws	IOException
    * Thrown if an error occurred while modifying the document.
    *
    * @throws	UnsupportedOperationException (unchecked)
    * Thrown if this method is not supported by the implementation of this
    * interface, i.e., the implementation assigns properties to documents by
    * some other means.
    *
    * @since	API 2.0, 2008-04-10
    */
    public abstract void addProperty(DocumentProperty prop)
        throws UnsupportedOperationException, IOException;


    /***************************************************************************
    * 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-16
    */
    public abstract void setInputStream(InputStream in)
        throws IOException;


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


    /***************************************************************************
    * 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
    */
    public abstract void doneReading();
}

// End StorableDocument.java