//==============================================================================
// 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.
*
*
* 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.
*
*
* Note that subclasses of this interface should not 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.
*
*
*
* - Source code:
* -
* http://david.tribble.com/src/java/tribble/repository/StorableDocument.java
*
* - Documentation:
* -
* http://david.tribble.com/docs/tribble/repository/StorableDocument.html
*
*
*
*
* @version API 3.0, $Revision: 1.2 $ $Date: 2012/03/17 23:01:58 $
* @since 2008-04-10
* @author David R. Tribble (david@tribble.com)
* Copyright ©2008-2012 by David R. Tribble, all rights reserved.
* 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 close() method) after the data is
* completely read from the stream (i.e., its read() 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 in is null.
*
* @since API 3.0, 2012-02-16
*/
public abstract void setInputStream(InputStream in)
throws IOException;
/***************************************************************************
* @deprecated
*
* 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.
*
*
* 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