//============================================================================== // ArchiveDocument.java //============================================================================== package tribble.archive; import java.io.Closeable; import java.io.InputStream; import java.io.IOException; import java.lang.Exception; import java.lang.String; /******************************************************************************* * Generic read-only archive document. * *
* An archive document is composed of content data (such as an image, * text, or other kind of data) and one or more properties. * *
* An archive document has an identifying document ID which provides * a means for locating it within the archive system. This is generally some * kind of identifier string that uniquely designates a single document within * the archive with respect to the context that the archive is being accessed * (i.e., with respect to the configuration properties that were use to * initialize and open the archive handler). * *
* An archive document may also possess a size, which specifies the * length of the document in units defined by the implementation (not necessarily * bytes). * *
* In addition, each archive document has a set of zero or more * document properties associated with it. These properties * ({@link DocumentProperty} objects) specify attributes of the document beyond * its content data, the meaning of which are defined by the implementation. * For example, a given implementation might provide properties specifying things * like a document's modification date, number of pages it contains, the names * of its authors, its access permissions, its expiration date, an identification * number shared by other related documents within the same batch, and so forth. * In addition to the document ID, one or more of these properties might be * used as the indices to store the document in the archive system. * *
* Note: This requires Java 1.5 or later. * * *
* Note that this method does not throw any exceptions. * *
* Implementations may allow this method to be called more than once. * * @since API 2.0, 2008-04-03 */ //@Override public abstract void close(); /*************************************************************************** * Retrieve the ID of this archive document. * * @return * A name that identifies the document within the archive. * * @throws IOException * Thrown if an error occurred while accessing the document. * * @since API 2.0, 2008-04-03 */ public abstract String getID() throws IOException; /*************************************************************************** * Retrieve the size of the data for this archive document. * * @return * The size (typically in bytes) of the document data, or -1 if the size is * not known. * * @throws IOException * Thrown if an error occurred while accessing the document. * * @since API 2.0, 2008-04-03 */ public abstract long getSize() throws IOException; /*************************************************************************** * Retrieve the value of a property in this archive document. * * @param prop * The name of the document property value to retrieve. * * @return * The property value (which may be null). * * @throws IOException * Thrown if an error occurred while accessing the document, or * if the document does not have the specified property. * * @since API 2.0, 2008-04-03 */ public abstract Object getProperty(String prop) throws IOException; /*************************************************************************** * Retrieve the properties associated with this archive document. * * @return * The properties defined for this document. * * @throws IOException * Thrown if an error occurred while accessing the document. * * @since API 2.0, 2008-04-03 */ public abstract DocumentProperty[] getProperties() throws IOException; /*************************************************************************** * Open a readable data stream to the contents of this archive document. * * @return * A readable binary data stream containing the contents of the document. * Note that the stream must be closed (by calling its close() * method) after the data is read. * * @throws IOException * Thrown if an error occurred while accessing the document. * * @since API 2.0, 2008-04-03 */ public abstract InputStream getDataStream() throws IOException; } // End ArchiveDocument.java