* This interface contains the basic methods for implementing a * document archive writer application. Such an application is * responsible for managing a document storage system (or archive) that * allows clients to store documents into 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. * *
* To create and store documents into an archive system, first an archive writer * object is created. The type of this object is a subclass which extends the * {@link ArchiveWriter} class: *
* class MyArchiveWriter
* extends {@link ArchiveWriter}<MyWritableDocument>
* { ... }
*
* * Likewise, the documents that are stored into this archive system are of a * subclass which extends the {@link WritableDocument} class: *
* class MyWritableDocument
* extends {@link WritableDocument}
* { ...}
*
* * An archive writer is created and its {@link #initialize initialize()} method * is called to initialize it: *
* MyArchiveWriter arch; * Properties props; * * arch = new MyArchiveWriter(...); * props = ...; * arch.initialize(props);* *
* Next, a connection to the archive system must be established and attached to * the archive writer: *
* try
* {
* arch.{@link #open open}();
* }
* catch (IOException ex)
* { ... }
*
* * Next, a new document is created and its properties are established: *
* MyWritableDocument doc;
* {@link WritableProperty} prop;
*
* doc = arch.{@link #createDocument createDocument}();
*
* prop = new WritableProperty(...);
* prop.{@link WritableProperty#setType setType}(...);
* prop.{@link WritableProperty#setLength setLength}(...);
* ...other attributes of the property can be set...
*
* doc.{@link WritableDocument#addProperty addProperty}(prop);
*
* ...repeat for each document property...
*
* * Next, the contents of the document are established: *
* OutputStream ds;
*
* ds = doc.{@link WritableDocument#putDataStream putDataStream}();
* ...write content data to the document stream...
* ds.close();
*
* * At this point, the document is fully populated and ready to be stored into * the archive system: *
* try
* {
* String id;
*
* id = arch.{@link #storeDocument storeDocument}(doc);
* ...store the document ID somewhere...
* doc.{@link WritableDocument#close close}();
* }
* catch (IOException ex)
* { ... }
*
* * This is repeated for each document that needs to be stored in the archive * system. * *
* Archive system implementations may optionally allow documents to be removed * from the archive. This is done by specifying a specific document ID to be * deleted. Implementations that allow this operation must ensure that the * document ID uniquely identifies a single document within the archive: *
* try
* {
* String id;
*
* id = ...;
* arch.{@link #removeDocument removeDocument}(id);
* }
* catch (IOException ex)
* { ... }
*
* * Once all documents have been stored or removed, the archive writer must be * closed, breaking the connection and detaching it from the archive system: *
* arch.{@link #close close}();
*
* * Exceptions (IOException) are thrown if any errors occur during * processing. * *
* Note: This requires Java 1.5 or later. * * *
* Note that implementations are not required to support default document * properties, in which case this method can throw an * UnsupportedOperationException or simply do nothing. * * @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 void setDefaultProperties(DocumentProperty[] defs) throws IOException; /*************************************************************************** * Create a new empty document for the archive attached to this archive * writer. * * @return * A newly created document for the archive system. * The document contains no content data, and has only the default document * properties as established by a previous call to * {@link #setDefaultProperties setDefaultProperties()}. * After the contents and properties are established for the document, it can * be stored in the archive by calling * {@link #storeDocument storeDocument()}. * * @throws IOException * Thrown if an error occurs while creating the document. * * @throws IllegalStateException (unchecked) * Thrown if {@link #initialize initialize()} has not been called yet. * * @since API 2.0, 2008-04-03 */ public abstract DocType createDocument() throws IOException; /*************************************************************************** * Store a document into the archive attached to this archive writer. * * @param doc * Document to store into the archive. * * @return * The ID of the stored document. * * @throws IOException * Thrown if an error occurs while storing the document in 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 String storeDocument(DocType doc) throws IOException; /*************************************************************************** * Remove a document from the archive attached to this archive writer. * * @param id * ID of a previously stored document to remove from the archive. * * @throws IOException * Thrown if an error occurs while removing the document from the archive * system. * * @throws UnsupportedOperationException (unchecked) * Thrown if this operation is not allowed by the implementation, i.e., * if documents cannot be deleted from the archive. * * @throws IllegalStateException (unchecked) * Thrown if {@link #initialize initialize()} has not been called yet. * * @since API 2.0, 2008-04-03 */ public abstract void removeDocument(String id) throws IOException, UnsupportedOperationException; } // End ArchiveWriter.java