//============================================================================== // Document.java //============================================================================== package tribble.repository; import java.io.Closeable; import java.io.InputStream; import java.io.IOException; import java.lang.Exception; import java.lang.String; /******************************************************************************* * Generic read-only repository document. * *

* A repository document is composed of content data (such as an image, * text, or other kind of data) and zero or more properties. * *

* A repository document has an identifying document ID which * provides a means for locating it within its parent document folder within the * repository system. This is generally some kind of identifier string that * uniquely designates a single document within the repository folder. * *

* A repository document may possess a size, which specifies the length of * the document in units defined by the implementation (usually, but not * necessarily, bytes). * *

* A repository 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 keys to * store the document in the repository system. * *

* Note: This requires Java 1.5 or later. * * *

*
Source code:
*
* http://david.tribble.com/src/java/tribble/repository/Document.java *
*
Documentation:
*
* http://david.tribble.com/docs/tribble/repository/Document.html *
*
* * * @version API 3.0, $Revision: 1.2 $ $Date: 2012/03/17 22:50:55 $ * @since 2008-04-03 * @author David R. Tribble (david@tribble.com)
* Copyright ©2008-2012 by David R. Tribble, all rights reserved.
* Permission is granted to any person or entity except those designated * by the United States Department of State as a terrorist or terrorist * government or agency, to use and distribute this source code provided * that the original copyright notice remains present and unaltered. * * @see StorableDocument * @see DocumentProperty * @see Folder * @see RepositoryReader * @see AbstractDocument */ public interface Document extends java.io.Closeable { static final String REV = "@(#)tribble/repository/Document.java $Revision: 1.2 $ $Date: 2012/03/17 22:50:55 $\n"; // ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ // Methods /*************************************************************************** * Close this repository document. * Deallocates all resources associated with the document. Any further use * of the document will result in exceptions. * *

* 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 repository folder that contains this document. * * @return * The parent folder for this document, or null if the document does not have * a parent folder. * * @throws IOException * Thrown if an error occurred while accessing the document. * * @since API 3.0, 2012-02-16 */ public abstract Folder getFolder() throws IOException; /*************************************************************************** * Retrieve the ID of this repository document. * * @return * A name that identifies the document within the repository. * * @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 repository 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 repository 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 repository 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 repository 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 3.0, 2012-02-16 */ public abstract InputStream getInputStream() throws IOException; /*************************************************************************** * @deprecated * * Use {@link #getInputStream()} instead. * * @since API 2.0, 2008-04-03 */ public abstract InputStream getDataStream() throws IOException; } // End Document.java