tribble.repository
Interface RepositoryWriter<DocType extends StorableDocument>

All Superinterfaces:

java.io.Closeable, Repository<DocType>

public interface RepositoryWriter<DocType extends StorableDocument>
extends Repository<DocType>, java.io.Closeable

Generic document repository storage writer.

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.

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

    class MyRepositoryWriter
        extends RepositoryWriter<MyStorableDocument>
    { ... }

Likewise, the documents that are stored into this repository system are of a subclass which extends the StorableDocument class:

    class MyStorableDocument
        extends StorableDocument
    { ... }

A repository writer is created and initialized:

    MyRepositoryWriter  repos;
    Properties          props;

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

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

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

Next, a new document is created and its properties are established:

    MyStorableDocument  doc;
    WritableProperty    prop;

    doc = repos.createDocument();

    prop = new WritableProperty(...);
    prop.setType(...);
    prop.setLength(...);
    ...other attributes of the property can be set...

    doc.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.setDataStream(ds);

At this point, the document is fully initialized and ready to be stored into the repository system:

    try
    {
        String  id;

        id = repos.storeDocument(doc);
        ...store the document ID somewhere...
        ...note that doc.getDataStream().close() is called...
        ...note that doc.doneReading() is called...
        doc.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 = ...;
        repos.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:

    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/RepositoryWriter.java

Documentation:

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

Since:

2008-04-04

Version:

API 2.0, $Revision: 1.2 $ $Date: 2008/04/04 16:32:25 $

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:

StorableDocument, WritableProperty, RepositoryReader

Field Summary

static java.lang.String

REV

Method Summary

DocType	createDocument(java.lang.String name) Create a new empty document for the repository attached to this repository writer.
void	removeDocument(java.lang.String id) Remove a document from the repository attached to this repository writer.
void	setDefaultProperties(DocumentProperty[] defs) Establish the default properties for documents created by this repository writer.
java.lang.String	storeDocument(DocType doc) Store a document into the repository attached to this repository writer.

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

setDefaultProperties

void setDefaultProperties(DocumentProperty[] defs)
                          throws java.io.IOException

Establish the default properties for documents created by this repository writer.

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:

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

java.lang.UnsupportedOperationException - (unchecked) This operation is not supported, i.e., the implementation does not support default document properties.

java.io.IOException

Since:

API 2.0, 2008-04-04

createDocument

DocType createDocument(java.lang.String name)
                                                throws java.io.IOException

Create a new empty document for the repository attached to this repository writer.

Parameters:

name - Name of the new document. The format and meaning of this name is determined by the implementation. Some implementations amy allow this to be empty ("") or null.

Returns:

A newly created document for the repository system. The document contains no content data, and has only the default document properties as established by a previous call to setDefaultProperties(). After the contents and properties are established for the document, it can be stored in the repository by calling storeDocument().

Throws:

java.io.IOException - Thrown if an error occurs while creating the document.

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

Since:

API 2.0, 2008-04-04

storeDocument

java.lang.String storeDocument(DocType doc)
                               throws java.io.IOException

Store a document into the repository attached to this repository writer.

Parameters:

doc - Document to store into the repository.

Returns:

The ID of the stored document.

Throws:

java.io.IOException - Thrown if an error occurs while storing the document in the repository system.

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

Since:

API 2.0, 2008-04-04

removeDocument

void removeDocument(java.lang.String id)
                    throws java.io.IOException,
                           java.lang.UnsupportedOperationException

Remove a document from the repository attached to this repository writer.

Parameters:

id - ID of a previously stored document to remove from the repository.

Throws:

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

java.lang.UnsupportedOperationException - (unchecked) Thrown if this operation is not allowed by the implementation, i.e., if documents cannot be deleted from the repository.

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

Since:

API 2.0, 2008-04-04