tribble.search
Interface WritableDocumentI

All Superinterfaces:
DocumentI
All Known Implementing Classes:
FFile

public interface WritableDocumentI
extends DocumentI

Generic writable document object.

A writable document is a document to which new data can be written, i.e., whose contents can be modified. Its attributes can also be modified, and new attributes can also be added to it.

A document 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 attributes, such as its length and the date it was last modified.

Some of the methods of this interface were modeled after the File and ZipFile classes.

Since:
2001-07-02
Version:
$Revision: 1.1 $ $Date: 2001/07/02 18:50:25 $
Author:
David R. Tribble (david@tribble.com).
Copyright 2001 by David R. Tribble, all rights reserved.
See Also:
DocumentSearcherI, DocumentStorerI

Field Summary
static java.lang.String REV
          Revision information.
static int SERIES
          Series number.
 
Method Summary
 void addAttribute(java.lang.String name)
          Add a new attribute name to this document.
 java.io.OutputStream getOutputStream()
          Get a writable output stream for this document.
 void makeWritable(boolean flag)
          Set the contents of this document to be writable.
 void setLastModified(java.util.Date when)
          Set the date that this document was last modified.
 void setLength(long len)
          Set the length of the contents of this document.
 void setType(java.lang.String type)
          Set the type of this document.
 
Methods inherited from interface tribble.search.DocumentI
canRead, canWrite, exists, getAttribute, getAttributeNames, getInputStream, getName, getType, isDirectory, lastModified, length, setAttribute
 

Field Detail

REV

public static final java.lang.String REV
Revision information.

See Also:
Constant Field Values

SERIES

public static final int SERIES
Series number.

See Also:
Constant Field Values
Method Detail

makeWritable

public void makeWritable(boolean flag)
                  throws java.lang.Exception
Set the contents of this document to be writable.

The meaning of writable depends on the particular implementation of this interface. It is up to the implementation whether newly created documents by default are writable or not.

Parameters:
flag - True if the document is to be made writable, false if it is not.
Throws:
java.lang.Exception - Thrown if the access mode of the document cannot be altered, or if some other error occurs.
Since:
1.1, 2001-07-02
See Also:
DocumentI.canWrite()

setLength

public void setLength(long len)
               throws java.lang.Exception
Set the length of the contents of this document.

Parameters:
len - The new length (size) of this document, in units meaningful to the implementation of this interface (typically bytes).
Throws:
java.lang.Exception - Thrown if the document cannot be modified, or if some other error occurs.
Since:
1.1, 2001-07-02
See Also:
DocumentI.length()

setLastModified

public void setLastModified(java.util.Date when)
                     throws java.lang.Exception
Set the date that this document was last modified.

Parameters:
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:
java.lang.Exception - Thrown if the document cannot be modified, or if some other error occurs.
Since:
1.1, 2001-07-02
See Also:
DocumentI.lastModified()

setType

public void setType(java.lang.String type)
             throws java.lang.Exception
Set the type of this document.

Parameters:
type - The new type of this document (which can be anything meaningfully interpreted as a document type, typically a filename extension or suffix). Such a type name is typically suitable for display by some user interface.
Throws:
java.lang.Exception - Thrown if the document cannot be modified, or if some other error occurs.
Since:
1.1, 2001-07-02
See Also:
DocumentI.getType()

addAttribute

public void addAttribute(java.lang.String name)
                  throws java.lang.Exception
Add a new attribute name to this document.

The attributes associated with a given document, if any, are specific to the particular implementation of this interface.

Parameters:
name - The name of a new attribute to associate with this document.
Throws:
java.lang.Exception - Thrown if the document cannot be modified, or if the attribute name already exists for this document, or if some other error occurs.
Since:
1.1, 2001-07-02
See Also:
DocumentI.getAttribute(java.lang.String), DocumentI.setAttribute(java.lang.String, java.lang.Object), DocumentI.getAttributeNames()

getOutputStream

public java.io.OutputStream getOutputStream()
                                     throws java.lang.Exception,
                                            java.lang.UnsupportedOperationException
Get a writable output stream for this document.

Returns:
An output stream, to which data can be written to set the data contents of this document.
Throws:
java.lang.Exception - Thrown if the output stream cannot be obtained, or if some other error occurs.
java.lang.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.
Since:
1.1, 2001-07-02
See Also:
DocumentI.getInputStream()