* This interface contains the basic methods for implementing a * document repository writer application. Such an application is * responsible for managing a document storage system (or repository) that * allows clients to store documents into it. How the repository 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 zero or more properties. Typically, the * properties comprise the keys used to store the document in the repository * system. * *
* First, note that the documents that are retrieved from this repository system * are of a subclass which extends the {@link StorableDocument} class: *
* class MyStorableDocument
* extends {@link StorableDocument}
* { ... }
*
* * To create and store documents into a repository system, first a repository * writer object is created. The type of this object is a subclass which extends * the {@link RepositoryWriter} class: *
* class MyRepositoryWriter
* extends {@link RepositoryWriter}<MyStorableDocument>
* { ... }
*
* * Finally, the documents that are stored into this repository system are * done so from a subclass which extends the {@link StorableFolder} class: *
* class MyStorableFolder
* extends {@link StorableFolder}<MyStorableDocument>
* { ... }
*
* * A repository writer is created and initialized: *
* MyRepositoryWriter repos;
* Properties props;
*
* repos = new MyRepositoryWriter(...);
* props = ...;
* repos.{@link #initialize initialize}(props);
*
* * Next, a connection to the repository system must be established and attached * to the repository writer: *
* try
* {
* repos.{@link #open open}();
* }
* catch (IOException ex)
* { ... }
*
* * The next step in the process of storing documents into the repository is to * locate and open the folder containing the documents we are interested in: *
* MyStorableFolder folder;
* try
* {
* String folderID;
*
* folderID = ...;
* folder = repos.{@link #getFolder getFolder}(folderID);
* }
* catch (IOException ex)
* { ... }
*
* * Alternatively, if the folder does not yet exist within the repository, we * must create it: *
* MyStorableFolder folder;
* try
* {
* String folderID;
*
* folderID = ...;
* folder = repos.{@link #createFolder createFolder}(folderID);
* }
* catch (IOException ex)
* { ... }
*
* * Either way, we now have a writable folder in which to store new documents. * *
* Next, a new document is created and its properties are established: *
* MyStorableDocument doc;
* {@link WritableProperty} prop;
*
* doc = repos.{@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 StorableDocument#addProperty addProperty}(prop);
*
* ...repeat for each document property...
*
* * Next, the contents of the document are established, by setting the input * stream from which the contents are to be read: *
* InputStream ds;
*
* ds = new InputStream(...);
* doc.{@link StorableDocument#setDataStream setDataStream}(ds);
*
* * At this point, the document is fully initialized and ready to be stored into * the repository system: *
* try
* {
* String id;
*
* id = folder.{@link WritableFolder#storeDocument storeDocument}(doc);
* ...store the document ID somewhere...
* ...note that doc.{@link StorableDocument#getDataStream getDataStream}().close() is called...
* ...note that doc.{@link StorableDocument#doneReading doneReading}() is called...
* doc.{@link StorableDocument#close close}();
* }
* catch (IOException ex)
* { ... }
*
* * This is repeated for each document to be stored in the repository system. * *
* Repository system implementations may optionally allow documents to be removed * from the repository. 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 repository: *
* try
* {
* String id;
*
* id = ...;
* folder.{@link WritableFolder#removeDocument removeDocument}(id);
* }
* catch (IOException ex)
* { ... }
*
* * Once all documents have been stored or removed, the repository writer must be * closed, breaking the connection and detaching it from the repository system: *
* folder.{@link WritableFolder#close close}();
* repos.{@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-04 */ public abstract void setDefaultProperties(DocumentProperty[] defs) throws IOException; /*************************************************************************** * Create a new empty document folder in the repository attached to this * repository writer. * * @param id * Name of the new document folder. * The format and meaning of this name is determined by the implementation. * Some implementations amy allow this to be empty ("") or null. * * @return * A newly created folder for the repository system. * The folder contains no documents, 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 a new document, * it can be stored in the folder by calling * {@link WritableFolder#storeDocument WritableFolder.storeDocument()}. * * @throws IOException * Thrown if an error occurs while creating the folder. * * @throws IllegalStateException (unchecked) * Thrown if {@link #initialize initialize()} has not been called yet. * * @since API 3.0, 2012-03-05 */ public abstract WritableFolder createFolder(String id) throws IOException; } // End RepositoryWriter.java