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