tribble.archive
Interface ArchiveReader<DocType extends ArchiveDocument>

All Superinterfaces:

Archive<DocType>, java.io.Closeable

public interface ArchiveReader<DocType extends ArchiveDocument>
extends Archive<DocType>, java.io.Closeable

Generic document archive storage reader.

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 ArchiveReader class:

    class MyArchiveReader
        extends ArchiveReader<MyDocument>
    { ... }

Likewise, the documents that are retrieved from this archive system are of a subclass which extends the ArchiveDocument class:

    class MyDocument
        extends ArchiveDocument
    { ...}

An archive reader is created and its 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.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.getDocument(id);
        ...process the document...
        doc.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;
        Set<MyDocument> docs;

        query = ...;
        docs = arch.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.close();
    }

The getProperty() method can be called to retrieve the values for specific properties associated with the document. The 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.close();

Exceptions (IOException) are thrown if any errors occur during processing.

Note: This requires Java 1.5 or later.

Source code:

http://david.tribble.com/src/java/tribble/archive/ArchiveReader.java

Documentation:

http://david.tribble.com/docs/tribble/archive/ArchiveReader.html

Since:

2008-04-03

Version:

API 2.0, $Revision: 1.1 $ $Date: 2008/04/03 22:16:22 $

Author:

David R. Tribble (david@tribble.com) Copyright ©2004 by David R. Tribble, all rights reserved.

See Also:

ArchiveDocument, DocumentProperty, ArchiveWriter

Field Summary

static java.lang.String

REV

Method Summary

java.util.Set<DocType>	findDocuments(java.lang.Object query) Find matching documents within the archive attached to this archive reader.
DocType	getDocument(java.lang.String id) Retrieve a specific document from the archive attached to this archive reader.

Methods inherited from interface tribble.archive.Archive

close, getDefaultProperties, initialize, open

Field Detail

REV

static final java.lang.String REV

See Also:

Constant Field Values

Method Detail

getDocument

DocType getDocument(java.lang.String id)
                                            throws java.io.IOException

Retrieve a specific document from the archive attached to this archive reader.

Parameters:

id - ID of the document to retrieve from the archive.

Throws:

java.io.IOException - Thrown if an error occurs while retrieving the document from the archive system.

java.lang.IllegalStateException - (unchecked) Thrown if initialize() has not been called yet.

Since:

API 2.0, 2008-04-03

findDocuments

java.util.Set<DocType> findDocuments(java.lang.Object query)
                                                             throws java.io.IOException

Find matching documents within the archive attached to this archive reader.

Parameters:

query - A query for searching for multiple matching documents within the archive. The actual form of this object (string, expression tree, etc.) is dependent upon the implementation of the archive system.

Returns:

A set of zero or more matching documents.

Throws:

java.io.IOException - Thrown if an error occurs while querying the archive system.

java.lang.IllegalStateException - (unchecked) Thrown if initialize() has not been called yet.

Since:

API 2.0, 2008-04-03