* This interface contains the basic methods for implementing a * document repository reader application. Such an application is * responsible for managing a document storage system (or repository) that * allows clients to retrieve documents from 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 Document} class: *
* class MyDocument
* extends {@link Document}
* { ... }
*
* * To retrieve an existing document within a repository system, first a * repository reader object is created. The type of this object is a subclass * which extends the {@link RepositoryReader} class: *
* class MyRepositoryReader
* extends RepositoryReader<MyDocument>
* { ... }
*
* * Finally, the documents that are retrieved from this repository system are * retrieved from a subclass which extends the {@link Folder} class: *
* class MyDocFolder
* extends {@link Folder}<MyDocument>
* { ... }
*
* * A repository reader is created and initialized: *
* MyRepositoryReader repos;
* Hashtable props;
*
* repos = new MyRepositoryReader(...);
* props = ...;
* repos.{@link #initialize initialize}(props);
*
* * Next, a connection to the repository system must be established and attached * to the repository reader: *
* try
* {
* repos.{@link #open open}(...);
* }
* catch (IOException ex)
* { ... }
*
* * The next step in the process of retrieving documents from the repository is to * locate and open the folder containing the documents we are interested in: *
* MyDocFolder folder;
* try
* {
* String folderID;
*
* folderID = ...;
* folder = repos.{@link #getFolder getFolder}(folderID);
* }
* catch (IOException ex)
* { ... }
*
* * From this point, the documents are retrieved from the document folder. * If the document ID is known, it can be used to directly retrieve a specific * document from the repository: *
* try
* {
* String id;
* MyDocument doc;
*
* id = ...;
* doc = folder.{@link Folder#getDocument getDocument}(id);
* ...process the document...
* doc.{@link Document#close close}();
* }
* catch (IOException ex)
* { ... }
*
* * Alternatively, a set of zero or more documents can be retrieved, based on some * kind of query criteria: *
* try
* {
* MyQueryType query;
* DocumentIterator<MyDocument> docs;
*
* query = ...;
* docs = folder.{@link Folder#findDocuments findDocuments}(query);
* }
* catch (IOException ex)
* { ... }
*
* * If the query is successful, the individual documents matching the search * criteria can be retrieved: *
* if (docs != null)
* {
* while (docs.{@link DocumentIterator#hasNext hasNext}())
* {
* MyDocument doc;
*
* doc = docs.{@link DocumentIterator#next next}();
* ...process the document...
* doc.{@link Document#close close}();
* }
* docs.{@link DocumentIterator#close close}();
* }
*
* * The {@link Document#getProperty getProperty()} method can be called * to retrieve the values for specific properties associated with the document. * The {@link Document#getProperties getProperties()} method can be called * to retrieve an array of all the properties associated with the document. * *
* Once the repository reader is no longer needed, it must be closed, breaking * the connection and detaching it from the repository system: *
* folder.{@link Folder#close close}();
* repos.{@link #close close}();
*
* * Exceptions (IOException) are thrown if any errors occur during * processing. * *
* Note: This requires Java 1.5 or later. * * *