//==============================================================================
// WritableDocumentI.java
//==============================================================================

package tribble.search;


// System imports

import java.io.OutputStream;

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

import java.util.Date;


// Local imports

import tribble.search.DocumentI;


/*******************************************************************************
* Generic writable document object.
*
* <p>
* A <i>writable document</i> is a document to which new data can be written,
* i.e., whose contents can be modified.  Its <i>attributes</i> can also be
* modified, and new attributes can also be added to it.
*
* <p>
* A <i>document</i> is an object representing information about a piece of data,
* much like a directory entry represents information for files in a file system.
* It also contains additional information associated with the document, called
* <i>attributes</i>, such as its length and the date it was last modified.
*
* <p>
* Some of the methods of this interface were modeled after the
* {@link java.io.File} and {@link java.util.zip.ZipFile} classes.
*
* <!------------------------------------------------------------------------ -->
* @version	$Revision: 1.1 $ $Date: 2001/07/02 18:50:25 $
* @since	2001-07-02
* @author
*	David R. Tribble
*	(<a href="mailto:david@tribble.com">david@tribble.com</a>).
*	<br>
*	<a href="../Copyright.html">Copyright</a>
*	©2001 by David R. Tribble, all rights reserved. <br>
*
* @see	DocumentSearcherI
* @see	DocumentStorerI
*/

public interface WritableDocumentI
    extends tribble.search.DocumentI
{
// Identification

    /** Revision information. */
    static final String		REV =
        "@(#)tribble/search/WritableDocumentI.java $Revision: 1.1 $ $Date: 2001/07/02 18:50:25 $\n";


// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
// Public constants

    /** Series number. */
    public static final int	SERIES =	100;


// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
// Public methods

    /***************************************************************************
    * Set the contents of this document to be writable.
    *
    * <p>
    * The meaning of <i>writable</i> depends on the particular implementation of
    * this interface.  It is up to the implementation whether newly created
    * documents by default are writable or not.
    *
    * @param	flag
    * True if the document is to be made writable, false if it is not.
    *
    * @throws	Exception
    * Thrown if the access mode of the document cannot be altered, or if some
    * other error occurs.
    *
    * @see	#canWrite
    *
    * @since	1.1, 2001-07-02
    */

    public void makeWritable(boolean flag)
        throws Exception;


    /***************************************************************************
    * Set the length of the contents of this document.
    *
    * @param	len
    * The new length (size) of this document, in units meaningful to the
    * implementation of this interface (typically bytes).
    *
    * @throws	Exception
    * Thrown if the document cannot be modified, or if some other error occurs.
    *
    * @see	#length
    *
    * @since	1.1, 2001-07-02
    */

    public void setLength(long len)
        throws Exception;


    /***************************************************************************
    * Set the date that this document was last modified.
    *
    * @param	when
    * The new date that this document was last modified, or null if it is
    * unknown or unobtainable.  Implementations should typically make a private
    * copy of this object, so that its value cannot inadvertently be modified
    * later.
    *
    * @throws	Exception
    * Thrown if the document cannot be modified, or if some other error occurs.
    *
    * @see	#lastModified
    *
    * @since	1.1, 2001-07-02
    */

    public void setLastModified(Date when)
        throws Exception;


    /***************************************************************************
    * Set the type of this document.
    *
    * @param	type
    * The new type of this document (which can be anything meaningfully
    * interpreted as a <i>document type</i>, typically a filename extension or
    * suffix).  Such a type name is typically suitable for display by some user
    * interface.
    *
    * @throws	Exception
    * Thrown if the document cannot be modified, or if some other error occurs.
    *
    * @see	#getType
    *
    * @since	1.1, 2001-07-02
    */

    public void setType(String type)
        throws Exception;


    /***************************************************************************
    * Add a new attribute name to this document.
    *
    * <p>
    * The attributes associated with a given document, if any, are specific to
    * the particular implementation of this interface.
    *
    * @param	name
    * The name of a new attribute to associate with this document.
    *
    * @throws	Exception
    * Thrown if the document cannot be modified, or if the attribute name
    * already exists for this document, or if some other error occurs.
    *
    * @see	#getAttribute
    * @see	#setAttribute
    * @see	#getAttributeNames
    *
    * @since	1.1, 2001-07-02
    */

    public void addAttribute(String name)
        throws Exception;


    /***************************************************************************
    * Get a writable output stream for this document.
    *
    * @return
    * An output stream, to which data can be written to set the data contents of
    * this document.
    *
    * @throws	Exception
    * Thrown if the output stream cannot be obtained, or if some other error
    * occurs.
    *
    * @throws	UnsupportedOperationException (unchecked)
    * Thrown if the document cannot be modified (i.e., is read only), or if this
    * method is not supported for this document type.
    *
    * @see	#getInputStream
    *
    * @since	1.1, 2001-07-02
    */

    public OutputStream getOutputStream()
        throws Exception, UnsupportedOperationException;
}

// End WritableDocumentI.java