//==============================================================================
// WritableFolder.java
//==============================================================================

package tribble.repository;

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

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


/*******************************************************************************
* Generic read-only repository document folder.
*
* <p>
* A <i>repository folder</i> contains zero or more <i>repository documents</i>.
*
* <p>
* A repository folder has an identifying <i>folder&nbsp;ID</i> which provides a
* means for locating it within the repository system.  This is generally some
* kind of identifier string that uniquely designates a single folder within the
* repository with respect to the context that the repository is being accessed
* (i.e., with respect to the configuration properties that were use to
* initialize and open the repository handler).
*
* <p>
* A repository folder may also possess a <i>size</i>, which specifies the
* number of documents currently residing in the folder.  Note that this
* information might not be available in all implementations.
*
* <p>
* Each repository folder has a set of zero or more default
* <i>document properties</i> associated with it.  These properties
* ({@link DocumentProperty} objects) specify default attributes of the documents
* contained within the folder; these default properties are inherited by
* documents as they are added into the repository folder (unless overridden by
* the {@link RepositoryWriter}).
*
* <p>
* Note: This requires Java 1.5 or later.
*
* <!-- ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ -->
* <dl>
* <dt> <b>Source code:</b> </dt>
*  <dd>
*   <a href="../../../src/java/tribble/repository/WritableFolder.java"
*    >http://david.tribble.com/src/java/tribble/repository/WritableFolder.java</a>
*  </dd>
* <dt> <b>Documentation:</b> </dt>
*  <dd>
*   <a href="WritableFolder.html"
*    >http://david.tribble.com/docs/tribble/repository/WritableFolder.html</a>
*  </dd>
* </dl>
*
* <!-- ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ -->
* @version	API 3.0, $Revision: 1.1 $ $Date: 2012/03/17 22:55:25 $
* @since	2012-02-16
* @author	David R. Tribble (david&#64;tribble.com)<br/>
*	Copyright ©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	Document
* @see	DocumentProperty
* @see	RepositoryReader
* @see	RepositoryWriter
*/

public interface WritableFolder<DocType extends Document>
    extends java.io.Closeable, Folder<DocType>
{
    static final String		REV =
        "@(#)tribble/repository/WritableFolder.java $Revision: 1.1 $ $Date: 2012/03/17 22:55:25 $\n";


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

    /***************************************************************************
//FIXME, change to setDefaultProperty()
    * Retrieve the value of a default document property in this repository
    * folder.
    *
    * @param	prop
    * The name of the document property value to retrieve.
    *
    * @return
    * The default property value (which may be null).
    *
    * @throws	IOException
    * Thrown if an error occurred while accessing the folder, or
    * if the folder does not have the specified property.
    *
    * @since	API 3.0, 2012-02-05
    */
    public abstract void setDefaultProperty(String prop, Object val)
        throws IOException;


    /***************************************************************************
//FIXME, change to setDefaultProperties()
    * Retrieve the default document properties associated with this repository
    * folder.
    *
    * @return
    * The default document properties defined for this folder.
    *
    * @throws	IOException
    * Thrown if an error occurred while accessing the folder.
    *
    * @since	API 3.0, 2012-02-05
    */
    public abstract void setDefaultProperties(DocumentProperty[] props)
        throws IOException;


    /***************************************************************************
    * Store a document into the repository attached to this repository folder.
    *
    * @param	doc
    * Document to store into the repository.
    *
    * @return
    * The ID of the stored document.
    *
    * @throws	IOException
    * Thrown if an error occurs while storing the document in the repository
    * system.
    *
    * @throws	IllegalStateException (unchecked)
    * Thrown if the folder is not open.
    *
    * @since	API 3.0, 2012-02-16
    */
    public abstract String storeDocument(DocType doc)
        throws IOException;


    /***************************************************************************
    * Remove a document from the repository attached to this repository folder.
    *
    * @param	id
    * ID of a previously stored document to remove from the repository.
    *
    * @throws	IOException
    * Thrown if an error occurs while removing the document from the repository
    * system.
    *
    * @throws	UnsupportedOperationException (unchecked)
    * Thrown if this operation is not allowed by the implementation, i.e.,
    * if documents cannot be deleted from the repository.
    *
    * @throws	IllegalStateException (unchecked)
    * Thrown if the folder is not open.
    *
    * @since	API 3.0, 2012-02-16
    */
    public abstract void removeDocument(String id)
        throws IOException, UnsupportedOperationException;
}

// End WritableFolder.java