tribble.archive
Interface ArchiveWriter<DocType extends WritableDocument>

All Superinterfaces:

Archive<DocType>, java.io.Closeable

public interface ArchiveWriter<DocType extends WritableDocument>
extends Archive<DocType>, java.io.Closeable

Generic document archive storage writer.

This interface contains the basic methods for implementing a document archive writer application. Such an application is responsible for managing a document storage system (or archive) that allows clients to store documents into 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 create and store documents into an archive system, first an archive writer object is created. The type of this object is a subclass which extends the ArchiveWriter class:

    class MyArchiveWriter
        extends ArchiveWriter<MyWritableDocument>
    { ... }

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

    class MyWritableDocument
        extends WritableDocument
    { ...}

An archive writer is created and its initialize() method is called to initialize it:

    MyArchiveWriter     arch;
    Properties          props;

    arch = new MyArchiveWriter(...);
    props = ...;
    arch.initialize(props);

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

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

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

    MyWritableDocument  doc;
    WritableProperty    prop;

    doc = arch.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:

    OutputStream    ds;

    ds = doc.putDataStream();
    ...write content data to the document stream...
    ds.close();

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

    try
    {
        String  id;

        id = arch.storeDocument(doc);
        ...store the document ID somewhere...
        doc.close();
    }
    catch (IOException ex)
    { ... }

This is repeated for each document that needs to be stored in the archive system.

Archive system implementations may optionally allow documents to be removed from the archive. 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 archive:

    try
    {
        String  id;

        id = ...;
        arch.removeDocument(id);
    }
    catch (IOException ex)
    { ... }

Once all documents have been stored or removed, the archive writer 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/ArchiveWriter.java

Documentation:

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

Since:

2008-04-03

Version:

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

Author:

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

See Also:

WritableDocument, WritableProperty, ArchiveReader

Field Summary

static java.lang.String

REV

Method Summary

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

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

setDefaultProperties

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

Establish the default properties for documents created by this archive 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-03

createDocument

DocType createDocument()
                                                throws java.io.IOException

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

Returns:

A newly created document for the archive 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 archive 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-03

storeDocument

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

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

Parameters:

doc - Document to store into the archive.

Returns:

The ID of the stored document.

Throws:

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

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

Since:

API 2.0, 2008-04-03

removeDocument

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

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

Parameters:

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

Throws:

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

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

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

Since:

API 2.0, 2008-04-03