tribble.archive
Interface ArchiveDocument

All Superinterfaces:

java.io.Closeable

All Known Subinterfaces:

WritableDocument

All Known Implementing Classes:

AbstractDocument, AbstractWritableDocument

public interface ArchiveDocument
extends java.io.Closeable

Generic read-only archive document.

An archive document is composed of content data (such as an image, text, or other kind of data) and one or more properties.

An archive document has an identifying document ID which provides a means for locating it within the archive system. This is generally some kind of identifier string that uniquely designates a single document within the archive with respect to the context that the archive is being accessed (i.e., with respect to the configuration properties that were use to initialize and open the archive handler).

An archive document may also possess a size, which specifies the length of the document in units defined by the implementation (not necessarily bytes).

In addition, each archive document has a set of zero or more document properties associated with it. These properties (DocumentProperty objects) specify attributes of the document beyond its content data, the meaning of which are defined by the implementation. For example, a given implementation might provide properties specifying things like a document's modification date, number of pages it contains, the names of its authors, its access permissions, its expiration date, an identification number shared by other related documents within the same batch, and so forth. In addition to the document ID, one or more of these properties might be used as the indices to store the document in the archive system.

Note: This requires Java 1.5 or later.

Source code:

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

Documentation:

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

Since:

2008-04-03

Version:

API 2.0, $Revision: 1.1 $ $Date: 2008/04/03 23:02:00 $

Author:

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

See Also:

WritableDocument, DocumentProperty, ArchiveReader, AbstractDocument

Field Summary

static java.lang.String

REV

Method Summary

void	close() Close this archive document.
java.io.InputStream	getDataStream() Open a readable data stream to the contents of this archive document.
java.lang.String	getID() Retrieve the ID of this archive document.
DocumentProperty[]	getProperties() Retrieve the properties associated with this archive document.
java.lang.Object	getProperty(java.lang.String prop) Retrieve the value of a property in this archive document.
long	getSize() Retrieve the size of the data for this archive document.

Field Detail

REV

static final java.lang.String REV

See Also:

Constant Field Values

Method Detail

close

void close()

Close this archive document. Deallocates all resources associated with the document. Any further use of the document will result in exceptions.

Note that this method does not throw any exceptions.

Implementations may allow this method to be called more than once.

Specified by:

close in interface java.io.Closeable

Since:

API 2.0, 2008-04-03

getID

java.lang.String getID()
                       throws java.io.IOException

Retrieve the ID of this archive document.

Returns:

A name that identifies the document within the archive.

Throws:

java.io.IOException - Thrown if an error occurred while accessing the document.

Since:

API 2.0, 2008-04-03

getSize

long getSize()
             throws java.io.IOException

Retrieve the size of the data for this archive document.

Returns:

The size (typically in bytes) of the document data, or -1 if the size is not known.

Throws:

java.io.IOException - Thrown if an error occurred while accessing the document.

Since:

API 2.0, 2008-04-03

getProperty

java.lang.Object getProperty(java.lang.String prop)
                             throws java.io.IOException

Retrieve the value of a property in this archive document.

Parameters:

prop - The name of the document property value to retrieve.

Returns:

The property value (which may be null).

Throws:

java.io.IOException - Thrown if an error occurred while accessing the document, or if the document does not have the specified property.

Since:

API 2.0, 2008-04-03

getProperties

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

Retrieve the properties associated with this archive document.

Returns:

The properties defined for this document.

Throws:

java.io.IOException - Thrown if an error occurred while accessing the document.

Since:

API 2.0, 2008-04-03

getDataStream

java.io.InputStream getDataStream()
                                  throws java.io.IOException

Open a readable data stream to the contents of this archive document.

Returns:

A readable binary data stream containing the contents of the document. Note that the stream must be closed (by calling its close() method) after the data is read.

Throws:

java.io.IOException - Thrown if an error occurred while accessing the document.

Since:

API 2.0, 2008-04-03