//==============================================================================
// WritableDocument.java
//==============================================================================

package tribble.archive;

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

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


/*******************************************************************************
* Generic writable archive document.
*
* <p>
* This interface extends {@link ArchiveDocument} 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 an archive system.
*
* <p>
* Note that subclasses should <i>not</i> provide a public constructor, since
* document objects are meant to be created using the
* {@link ArchiveWriter#createDocument ArchiveWriter.createDocument()}
* method instead.  This is so that document IDs and default document properties
* can be established for newly created documents by the {@link ArchiveWriter}
* implementation as soon as possible, at the time that the document objects are
* created.
*
* <p>
* Note: This requires Java 1.5 or later.
*
* <!-- ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ -->
* <dl>
* <dt> <b>Source code:</b> </dt>
*  <dd>
*   <a href="../../../src/java/tribble/archive/WritableDocument.java"
*    >http://david.tribble.com/src/java/tribble/archive/WritableDocument.java</a>
*  </dd>
* <dt> <b>Documentation:</b> </dt>
*  <dd>
*   <a href="WritableDocument.html"
*    >http://david.tribble.com/docs/tribble/archive/WritableDocument.html</a>
*  </dd>
* </dl>
*
* <!-- ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ -->
* @version	API 2.0, $Revision: 1.1 $ $Date: 2008/04/03 22:05:12 $
* @since	2008-04-03
* @author	David R. Tribble (david&#64;tribble.com)
*	Copyright ©2004 by David R. Tribble, all rights reserved.
*
* @see	ArchiveWriter
* @see	AbstractWritableDocument
*/

public interface WritableDocument
    extends ArchiveDocument
{
    static final String		REV =
        "@(#)tribble/archive/WritableDocument.java $Revision: 1.1 $ $Date: 2008/04/03 22:05:12 $\n";


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

    /***************************************************************************
    * Establish the ID of this archive document.
    *
    * @param	id
    * A name that identifies the document within the archive.
    * Whether or not this name must be unique is up to 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 the IDs are assigned to archive documents by some other means.
    *
    * @since	API 2.0, 2008-04-03
    */
    public abstract void setID(String id)
        throws IOException, UnsupportedOperationException;


    /***************************************************************************
    * Establish the data size for this archive 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 the sizes are assigned to archive documents by some other means.
    *
    * @since	API 2.0, 2008-04-03
    */
    public abstract void setSize(long len)
        throws IOException, UnsupportedOperationException;


    /***************************************************************************
    * Establish the value of a property in this archive 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-03
    */
    public abstract void setProperty(String prop, Object val)
        throws IOException;


    /***************************************************************************
    * Add a property to this archive 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-03
    */
    public abstract void addProperty(WritableProperty prop)
        throws UnsupportedOperationException, IOException;


    /***************************************************************************
    * Open a writable data stream to the contents of this archive document.
    *
    * @return
    * A writable binary data stream to which the contents of the document are to
    * be written.  Note that the stream must be flushed and closed (by calling
    * its <tt>close()</tt> method) after the data is completely written in order
    * to commit the data to the archive.
    *
    * @throws	IOException
    * Thrown if an error occurred while accessing the document.
    *
    * @since	API 2.0, 2008-04-03
    */
    public abstract OutputStream putDataStream()
        throws IOException;
}

// End WritableDocument.java