//============================================================================== // DocumentI.java //============================================================================== package tribble.search; // System imports import java.io.InputStream; import java.io.OutputStream; import java.lang.Exception; import java.lang.String; import java.lang.UnsupportedOperationException; import java.util.Date; // Local imports // (None) /******************************************************************************* * 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 * {@link 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 * {@link java.io.File} and {@link java.util.zip.ZipFile} classes. * * * @version $Revision: 1.5 $ $Date: 2001/07/02 22:50:08 $ * @since 2001-02-27 * @author * David R. Tribble * (david@tribble.com). *
* Copyright * ©2001 by David R. Tribble, all rights reserved.
* * @see DocumentSearcherI * @see WritableDocumentI */ public interface DocumentI { // Identification /** Revision information. */ static final String REV = "@(#)tribble/search/DocumentI.java $Revision: 1.5 $ $Date: 2001/07/02 22:50:08 $\n"; // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - // Public constants /** Series number. */ public static final int SERIES = 400; // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - // Public methods /*************************************************************************** * Determine if the actual contents of this document exist. * * @return * True if the document contents exist, otherwise false. * * @throws Exception * Thrown if the information about the document is unobtainable, or if some * other error occurs. * * @since 1.2, 2001-06-15 */ public boolean exists() throws Exception; /*************************************************************************** * Determine if this document specifies a directory entry. * * @return * 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 Exception * Thrown if the information about the document is unobtainable, or if some * other error occurs. * * @since 1.2, 2001-06-15 */ public boolean isDirectory() throws Exception; /*************************************************************************** * Determine if the contents of this document are readable. * * @return * True if the document contents exist and can be read, otherwise false. * * @throws Exception * Thrown if the information about the document is unobtainable, or if some * other error occurs. * * @see #getInputStream * @see #canWrite * * @since 1.2, 2001-06-15 */ public boolean canRead() throws Exception; /*************************************************************************** * Determine if the contents of this document are writable. * * @return * True if the document contents exist and can be written to, otherwise * false. * * @throws Exception * Thrown if the information about the document is unobtainable, or if some * other error occurs. * * @see #getInputStream * @see #canRead * * @since 1.2, 2001-06-15 */ public boolean canWrite() throws Exception; /*************************************************************************** * Determine the length of the contents of this document. * * @return * The length (size) of this document, in units meaningful to the * implementation of this interface (typically bytes). * * @throws Exception * Thrown if the information about the document is unobtainable, or if some * other error occurs. * * @since 1.2, 2001-06-15 */ public long length() throws Exception; /*************************************************************************** * Determine the date that this document was last modified. * * @return * The date that this document was last modified, or null if the date is * unknown or unobtainable. * * @throws Exception * Thrown if the document cannot be accessed, or if some other error occurs. * * @since 1.2, 2001-06-15 */ public Date lastModified() throws Exception; /*************************************************************************** * Retrieve the name for this document. * * @return * 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 Exception * Thrown if the information about the document is unobtainable, or if some * other error occurs. * * @since 1.2, 2001-06-15 */ public String getName() throws Exception; /*************************************************************************** * Retrieve the type of this document. * * @return * 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 Exception * Thrown if the information about the document is unobtainable, or if some * other error occurs. * * @since 1.2, 2001-06-15 */ public String getType() throws 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. * * @return * An array containing the names of the attributes associated with this * document, or null if it has none. * * @throws Exception * Thrown if the information about the document is unobtainable, or if some * other error occurs. * * @see #getAttribute * @see #setAttribute * * @since 1.4, 2001-06-11 */ public String[] getAttributeNames() throws Exception; /*************************************************************************** * Retrieve the value of an attribute for this document. * * @param attr * The name of an attribute associated with this document. * * @return * 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 Exception * Thrown if the information about the document is unobtainable, or if some * other error occurs. * * @see #getAttributeNames * * @since 1.4, 2001-06-30 */ public Object getAttribute(String attr) throws Exception; /*************************************************************************** * Set the value of an attribute for this document. * * @param attr * The name of an attribute associated with this document. * * @param val * The new value of the specified attribute. * * @throws Exception * Thrown if the information about the document cannot be set, or if some * other error occurs. * * @throws UnsupportedOperationException (unchecked) * Thrown if this method is not implemented for this document type. * * @see #getAttributeNames * * @since 1.4, 2001-06-30 */ public void setAttribute(String attr, Object val) throws Exception, UnsupportedOperationException; /*************************************************************************** * Get a readable input stream for this document. * * @return * An input stream, from which the data contents of this document can be * read. * * @throws Exception * Thrown if the input stream cannot be obtained, or if some other error * occurs. * * @throws 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 */ public InputStream getInputStream() throws Exception, UnsupportedOperationException; } // End DocumentI.java