tribble.search
Interface DocumentI

All Known Subinterfaces:

WritableDocumentI

All Known Implementing Classes:

FFile, ZFile

public interface DocumentI

Generic document.

The term document is used in its most generic sense, and can be any object that can be meaningfully interpreted as the result of a search (see the DocumentSearcherI interface), and which possesses an input or output data stream.

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. By itself, a document entry does not contain any data contents, but serves as a "pointer" or "proxy" object representing the actual document object, from which the contents of the document can be accessed. It also contains information about the actual document, such as its length and the date it was last modified.

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

Since:

2001-02-27

Version:

$Revision: 1.5 $ $Date: 2001/07/02 22:50:08 $

Author:

David R. Tribble (david@tribble.com).
Copyright ©2001 by David R. Tribble, all rights reserved.

See Also:

DocumentSearcherI, WritableDocumentI

Field Summary

static java.lang.String	REV Revision information.
static int	SERIES Series number.

Method Summary

boolean	canRead() Determine if the contents of this document are readable.
boolean	canWrite() Determine if the contents of this document are writable.
boolean	exists() Determine if the actual contents of this document exist.
java.lang.Object	getAttribute(java.lang.String attr) Retrieve the value of an attribute for this document.
java.lang.String[]	getAttributeNames() Retrieve the attribute names for this document.
java.io.InputStream	getInputStream() Get a readable input stream for this document.
java.lang.String	getName() Retrieve the name for this document.
java.lang.String	getType() Retrieve the type of this document.
boolean	isDirectory() Determine if this document specifies a directory entry.
java.util.Date	lastModified() Determine the date that this document was last modified.
long	length() Determine the length of the contents of this document.
void	setAttribute(java.lang.String attr, java.lang.Object val) Set the value of an attribute for this document.

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

exists

public boolean exists()
               throws java.lang.Exception

Determine if the actual contents of this document exist.

Returns:

True if the document contents exist, otherwise false.

Throws:

java.lang.Exception - Thrown if the information about the document is unobtainable, or if some other error occurs.

Since:

1.2, 2001-06-15

isDirectory

public boolean isDirectory()
                    throws java.lang.Exception

Determine if this document specifies a directory entry.

Returns:

True if this document is a directory (where directory is a general term that means that such an entry is itself searchable, containing other documents), otherwise false.

Throws:

java.lang.Exception - Thrown if the information about the document is unobtainable, or if some other error occurs.

Since:

1.2, 2001-06-15

canRead

public boolean canRead()
                throws java.lang.Exception

Determine if the contents of this document are readable.

Returns:

True if the document contents exist and can be read, otherwise false.

Throws:

java.lang.Exception - Thrown if the information about the document is unobtainable, or if some other error occurs.

Since:

1.2, 2001-06-15

See Also:

getInputStream(), canWrite()

canWrite

public boolean canWrite()
                 throws java.lang.Exception

Determine if the contents of this document are writable.

Returns:

True if the document contents exist and can be written to, otherwise false.

Throws:

java.lang.Exception - Thrown if the information about the document is unobtainable, or if some other error occurs.

Since:

1.2, 2001-06-15

See Also:

getInputStream(), canRead()

length

public long length()
            throws java.lang.Exception

Determine the length of the contents of this document.

Returns:

The length (size) of this document, in units meaningful to the implementation of this interface (typically bytes).

Throws:

java.lang.Exception - Thrown if the information about the document is unobtainable, or if some other error occurs.

Since:

1.2, 2001-06-15

lastModified

public java.util.Date lastModified()
                            throws java.lang.Exception

Determine the date that this document was last modified.

Returns:

The date that this document was last modified, or null if the date is unknown or unobtainable.

Throws:

java.lang.Exception - Thrown if the document cannot be accessed, or if some other error occurs.

Since:

1.2, 2001-06-15

getName

public java.lang.String getName()
                         throws java.lang.Exception

Retrieve the name for this document.

Returns:

The name of this document (which can be anything meaningfully interpreted as a name, such as a disk filename or URL) specifying the location of this document. Such a name is typically suitable for display by some user interface.

Throws:

java.lang.Exception - Thrown if the information about the document is unobtainable, or if some other error occurs.

Since:

1.2, 2001-06-15

getType

public java.lang.String getType()
                         throws java.lang.Exception

Retrieve the type of this document.

Returns:

The 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 information about the document is unobtainable, or if some other error occurs.

Since:

1.2, 2001-06-15

getAttributeNames

public java.lang.String[] getAttributeNames()
                                     throws java.lang.Exception

Retrieve the attribute names for this document.

The attributes associated with a given document, if any, are specific to the particular implementation of this interface. If the implementation does not support any attributes for its document class type, this method returns null.

Returns:

An array containing the names of the attributes associated with this document, or null if it has none.

Throws:

java.lang.Exception - Thrown if the information about the document is unobtainable, or if some other error occurs.

Since:

1.4, 2001-06-11

See Also:

getAttribute(java.lang.String), setAttribute(java.lang.String, java.lang.Object)

getAttribute

public java.lang.Object getAttribute(java.lang.String attr)
                              throws java.lang.Exception

Retrieve the value of an attribute for this document.

Parameters:

attr - The name of an attribute associated with this document.

Returns:

The value of the specified attribute, or null if this document has no such attribute. Note that the value is returned as a generic Object, meaning that it must be cast into the appropriate type.

Throws:

java.lang.Exception - Thrown if the information about the document is unobtainable, or if some other error occurs.

Since:

1.4, 2001-06-30

See Also:

getAttributeNames()

setAttribute

public void setAttribute(java.lang.String attr,
                         java.lang.Object val)
                  throws java.lang.Exception,
                         java.lang.UnsupportedOperationException

Set the value of an attribute for this document.

Parameters:

attr - The name of an attribute associated with this document.

val - The new value of the specified attribute.

Throws:

java.lang.Exception - Thrown if the information about the document cannot be set, or if some other error occurs.

java.lang.UnsupportedOperationException - (unchecked) Thrown if this method is not implemented for this document type.

Since:

1.4, 2001-06-30

See Also:

getAttributeNames()

getInputStream

public java.io.InputStream getInputStream()
                                   throws java.lang.Exception,
                                          java.lang.UnsupportedOperationException

Get a readable input stream for this document.

Returns:

An input stream, from which the data contents of this document can be read.

Throws:

java.lang.Exception - Thrown if the input stream cannot be obtained, or if some other error occurs.

java.lang.UnsupportedOperationException - (unchecked) Thrown if the stream cannot be read from (i.e., is write only), or if this method is not supported for this document type.

Since:

1.1, 2001-02-27