* This interface contains the basic methods for implementing a * document archive reader application. Such an application is * responsible for managing a document storage system (or archive) that * allows clients to 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. * *
* To retrieve an existing document within an archive system, first an archive * reader object is created. The type of this object is a subclass which extends * the {@link ArchiveReader} class: *
* class MyArchiveReader
* extends ArchiveReader<MyDocument>
* { ... }
*
* * Likewise, the documents that are retrieved from this archive system are of a * subclass which extends the {@link ArchiveDocument} class: *
* class MyDocument
* extends {@link ArchiveDocument}
* { ...}
*
* * An archive reader is created and its {@link #initialize initialize()} method * is called to initialize it: *
* MyArchiveReader arch; * Properties props; * * arch = new MyArchiveReader(...); * props = ...; * arch.initialize(props);* *
* Next, a connection to the archive system must be established and attached to * the archive reader: *
* try
* {
* arch.{@link #open open}();
* }
* catch (IOException ex)
* { ... }
*
* * If the document ID is known, it can be used to directly retrieve a specific * document from the archive: *
* try
* {
* String id;
* MyDocument doc;
*
* id = ...;
* doc = arch.{@link #getDocument getDocument}(id);
* ...process the document...
* doc.{@link ArchiveDocument#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;
* {@link Set}<MyDocument> docs;
*
* query = ...;
* docs = arch.{@link #findDocuments findDocuments}(query);
* }
* catch (IOException ex)
* { ... }
*
* * If the query is successful, the individual documents matching the search * criteria can be retrieved: *
* Iterator<MyDocument> list;
*
* list = docs.iterator();
* while (list.hasNext())
* {
* MyDocument doc;
*
* doc = list.next();
* ...process the document...
* doc.{@link ArchiveDocument#close close}();
* }
*
* * The {@link ArchiveDocument#getProperty getProperty()} method can be called * to retrieve the values for specific properties associated with the document. * The {@link ArchiveDocument#getProperties getProperties()} method can be called * to retrieve an array containing all of the properties associated with the * document. * *
* Once the archive reader is no longer needed, it 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. * * *