tribble.repository
Interface RepositoryReader<DocType extends Document>

All Superinterfaces:

java.io.Closeable, Repository<DocType>

public interface RepositoryReader<DocType extends Document>
extends Repository<DocType>, java.io.Closeable

Generic document repository storage reader.

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.

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

    class MyRepositoryReader
        extends RepositoryReader<MyDocument>
    { ... }

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

    class MyDocument
        extends Document
    { ... }

A repository reader is created and initialized:

    MyRepositoryReader  repos;
    Hashtable           props;

    repos = new MyRepositoryReader(...);
    props = ...;
    repos.initialize(props);

Next, a connection to the repository system must be established and attached to the repository reader:

    try
    {
        repos.open(...);
    }
    catch (IOException ex)
    { ... }

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 = repos.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;
        DocumentIterator<MyDocument>    docs;

        query = ...;
        docs = repos.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.hasNext())
        {
            MyDocument  doc;

            doc = docs.next();
            ...process the document...
            doc.close();
        }
        docs.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 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:

    repos.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/repository/RepositoryReader.java

Documentation:

http://david.tribble.com/docs/tribble/repository/RepositoryReader.html

Since:

2008-04-04

Version:

API 2.0, $Revision: 1.2 $ $Date: 2008/04/09 16:48:11 $

Author:

David R. Tribble (david@tribble.com)
Copyright ©2008 by David R. Tribble, all rights reserved.
Permission is granted to any person or entity except those designated by the United States Department of State as a terrorist or terrorist government or agency, to use and distribute this source code provided that the original copyright notice remains present and unaltered.

See Also:

Document, DocumentProperty, RepositoryWriter

Field Summary

static java.lang.String

REV

Method Summary

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

Methods inherited from interface tribble.repository.Repository

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 repository attached to this repository reader.

Parameters:

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

Returns:

The specified document, or null if no such document exists within the repository.

Throws:

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

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

Since:

API 2.0, 2008-04-04

findDocuments

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

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

Parameters:

query - A query for searching for multiple matching documents within the repository. The actual form of this object (string, expression tree, etc.) is dependent upon the implementation of the repository system. This may be a subtype that implements interface DocumentFilter.

Returns:

A set of zero or more matching documents.

Throws:

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

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

Since:

API 2.0, 2008-04-04