tribble.archive
Interface Archive<DocType extends ArchiveDocument>

All Superinterfaces:

java.io.Closeable

All Known Subinterfaces:

ArchiveReader<DocType>, ArchiveWriter<DocType>

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

Generic document archive (base class).

This interface contains the basic methods for implementing a document archive application. Such an application is responsible for managing a document storage system (or archive) that allows clients to store or 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.

Implementations of an archive system must subclass either the ArchiveReader or ArchiveWriter class, or both. Archive reader implementations must also subclass the ArchiveDocument class, while archive writer implementations must subclass the WritableDocument class.

Configuration properties specific to the archive implementation are passed to the initialize() method in order to initialize the archive reader or writer appropriately. Once the archive reader or writer has been properly initialized, calling its open() method establishes a connection to the archive system. Documents can then be retrieved from or stored into the archive. After all archive operations have been completed, the close() method must be called, which closes the connection to the archive system and deallocates any resources used by the reader/writer object.

Most of the methods in these classes throw an IOException if an error occurs.

Note: This requires Java 1.5 or later.

Source code:

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

Documentation:

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

Since:

2008-04-03

Version:

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

Author:

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

See Also:

ArchiveDocument, ArchiveReader, ArchiveWriter

Field Summary

static java.lang.String

REV

Method Summary

void	close() Close the connection and detach the archive system from this archive handler.
DocumentProperty[]	getDefaultProperties() Retrieve the default properties for documents managed by this archive handler.
void	initialize(java.util.Properties props) Load the application configuration properties for this archive handler.
void	open() Establish a connection and attach an archive system to this archive handler.

Field Detail

REV

static final java.lang.String REV

See Also:

Constant Field Values

Method Detail

initialize

void initialize(java.util.Properties props)
                throws java.io.IOException

Load the application configuration properties for this archive handler. This must be the first method to be called, prior to calling open() or any other method.

The name and format of the properties is determined by the actual implementation of the archive system. Typically, properties specify the details required to establish a connection to the archive system, e.g., host or path names, user-ID and password credentials, database names, and other similar information. The properties passed to this method thus establish a specific context in which access to the archive system takes place. This context exists for all of the operations occurring between the calls to open() and close().

Certain implementations might not require any context information at all prior to calling open(), in which case this method may accept an empty Properties object or even null.

Implementations may allow this method to be called more than once. This could be useful in cases where configuration information is taken from multiple sources.

Throws:

java.io.IOException - Thrown if a required property is missing or malformed.

Since:

API 2.0, 2008-04-03

open

void open()
          throws java.io.IOException

Establish a connection and attach an archive system to this archive handler.

Throws:

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

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

Since:

API 2.0, 2008-04-03

close

void close()

Close the connection and detach the archive system from this archive handler. Resources used by this archive handler are deallocated.

Any subsequent attempts to use this archive handler without calling open() again will result in exceptions.

Note that this method does not throw any exceptions.

Specified by:

close in interface java.io.Closeable

Since:

API 2.0, 2008-04-03

getDefaultProperties

DocumentProperty[] getDefaultProperties()
                                        throws java.io.IOException

Retrieve the default properties for documents managed by this archive handler.

Note that implementations are not required to support default document properties, in which case this method can throw an UnsupportedOperationException or simply return null.

Returns:

The default document properties for this archive handler.

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