* This interface contains the basic methods for implementing a * document archive application. Such an application is * responsible for managing a document storage system (or archive) that * allows clients to store or retrieve documents from it. How the archive system * is implemented and what exactly constitutes a document is determined by each * particular subclass that implements this interface. * *
* A document consists of content data (such as an image, text, or other * kind of user data) and one or more properties. Typically, the * properties comprise the indices used to store the document in the archive * system. * *
* Implementations of an archive system must subclass either the * {@link ArchiveReader} or {@link ArchiveWriter} class, or both. * Archive reader implementations must also subclass the {@link ArchiveDocument} * class, while archive writer implementations must subclass the * {@link WritableDocument} class. * *
* Configuration properties specific to the archive implementation are passed to * the {@link #initialize initialize()} method in order to initialize the archive * reader or writer appropriately. Once the archive reader or writer has been * properly initialized, calling its {@link #open open()} method establishes a * connection to the archive system. Documents can then be retrieved from or * stored into the archive. After all archive operations have been completed, * the {@link #close close()} method must be called, which closes the connection * to the archive system and deallocates any resources used by the reader/writer * object. * *
* Most of the methods in these classes throw an IOException if an * error occurs. * *
* Note: This requires Java 1.5 or later. * * *
* The name and format of the properties is determined by the actual * implementation of the archive system. Typically, properties specify the * details required to establish a connection to the archive system, e.g., * host or path names, user-ID and password credentials, database names, and * other similar information. The properties passed to this method thus * establish a specific context in which access to the archive system takes * place. This context exists for all of the operations occurring between * the calls to {@link #open open()} and {@link #close close()}. * *
* Certain implementations might not require any context information at all * prior to calling {@link #open open()}, in which case this method may * accept an empty Properties object or even null. * *
* Implementations may allow this method to be called more than once. * This could be useful in cases where configuration information is taken * from multiple sources. * * @throws IOException * Thrown if a required property is missing or malformed. * * @since API 2.0, 2008-04-03 */ public abstract void initialize(Properties props) throws IOException; /*************************************************************************** * Establish a connection and attach an archive system to this archive * handler. * * @throws IOException * Thrown if an error occurs while opening the archive system. * * @throws IllegalStateException (unchecked) * Thrown if {@link #initialize initialize()} has not been called yet. * * @since API 2.0, 2008-04-03 */ public abstract void open() throws IOException; /*************************************************************************** * Close the connection and detach the archive system from this archive * handler. * Resources used by this archive handler are deallocated. * *
* Any subsequent attempts to use this archive handler without calling * {@link #open open()} again will result in exceptions. * *
* Note that this method does not throw any exceptions. * * @since API 2.0, 2008-04-03 */ //@Override public abstract void close(); /*************************************************************************** * Retrieve the default properties for documents managed by this archive * handler. * *
* Note that implementations are not required to support default document * properties, in which case this method can throw an * UnsupportedOperationException or simply return null. * * @return * The default document properties for this archive handler. * * @throws IllegalStateException (unchecked) * Thrown if {@link #initialize initialize()} has not been called yet. * * @throws UnsupportedOperationException (unchecked) * This operation is not supported, i.e., the implementation does not support * default document properties. * * @since API 2.0, 2008-04-03 */ public abstract DocumentProperty[] getDefaultProperties() throws IOException; } // End Archive.java