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()