tribble.search
Interface DocumentStorerI

public interface DocumentStorerI

Generic document storer.

Implementations of this interface provide the capability of storing documents within document storage systems. The term document is used in a very generic sense, referring to any object that contains data that can be read and/or written. The term document storage system (or document storer) is a generic term referring to any kind of system or device that is capable of storing and retrieving documents.

    import tribble.search.*;

    public class MyDocStorer
        implements tribble.search.DocumentStorerI
    {
        ...
    }
 

A document storer allows client classes to create and store documents. Information (a.k.a. attributes) about each new document can be established, as well as it data contents.

Examples of the kinds of entities handled by document storer implementations include:

file system directories

ZIP archive files

LDAP directory services

JNDI naming services

FTP access services

etc.

The store() method of a document storer object writes and commits the document data and its associated attributes to the storage system.

    MyDocStorer         stor;
    Hashtable           props;
    WritableDocumentI   doc;
    OutputStream        docData;

    // Create and initialize a new document storer object
    stor = new MyDocStorer(...);
    props = new Hashtable();
    props.put(..., ...);
    stor.initialize(props);
    stor.open("foo");

    // Create a new document
    doc = stor.create("bar", false);
    docData = doc.getOutputStream();
    docData.write(...);
    docData.close();
    doc.setAttribute(..., ...);

    // Store the new document
    stor.storestore(doc);

    // Finish
    stor.close();
 

The remove() method deletes a named document from the storage system.

Since:

2001-07-02

Version:

$Revision: 1.2 $ $Date: 2001/07/02 21:13:49 $

Author:

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

See Also:

DocumentI, DocumentFilterI, DocumentSearcherI

Field Summary

static java.lang.String	REV Revision information.
static int	SERIES Series number.

Method Summary

void	close() Close this document storer.
WritableDocumentI	create(java.lang.String name, boolean append) Create a new document in the document storage system.
void	createDirectory(java.lang.String name) Create a new directory in the document storage system.
void	initialize(java.util.Hashtable parms) Initialize this document storer.
void	open(java.lang.String path) Open a given storage path for this document storer.
void	remove(java.lang.String name) Remove a document from the document storage system.
void	removeDirectory(java.lang.String name) Remove a directory from the document storage system.
void	store(DocumentI doc) Store a document into the document storage system.

Field Detail

REV

public static final java.lang.String REV

Revision information.

See Also:

Constant Field Values

SERIES

public static final int SERIES

Series number.

See Also:

Constant Field Values

Method Detail

initialize

public void initialize(java.util.Hashtable parms)
                throws java.lang.Exception

Initialize this document storer.

This must be the first method to be called on this document storer object, prior to calling the open() method.

The implementation of this interface may allow this method to be called more than once.

Parameters:

parms - A hash table containing name/value pairs with which to initialize this document storer. This argument may be allowed to be null, depending on the implementation of this interface.

Throws:

java.lang.Exception - Thrown if the specified hash table entries are malformed, or if some other error occurs.

Since:

1.1, 2001-07-02

See Also:

open(java.lang.String)

open

public void open(java.lang.String path)
          throws java.lang.Exception

Open a given storage path for this document storer.

Parameters:

path - The name of a path (which can be anything meaningfully interpreted as a path or device, such as a filename or URL) specifying the location that this document storer is to write new documents to.

Throws:

java.lang.Exception - Thrown if the specified path does not exist or is not accessible, or if it is malformed, or if some other error occurs.

Since:

1.1, 2001-07-02

See Also:

close(), initialize(java.util.Hashtable)

close

public void close()
           throws java.lang.Exception

Close this document storer.

This must be the last method to be called on this document storer object.

Throws:

java.lang.Exception - Thrown if an error occurs.

Since:

1.1, 2001-07-02

See Also:

open(java.lang.String)

create

public WritableDocumentI create(java.lang.String name,
                                boolean append)
                         throws java.lang.Exception,
                                java.lang.UnsupportedOperationException

Create a new document in the document storage system.

It is up to the implementation of this interface how it creates a new document. In particular, space for the new document may or may not actually be allocated in the storage system until the store() method is called.

Parameters:

name - The name of the new document to create. Whether or not this name constitutes a meaningful and valid document name is determined by the implementation of this interface.

append - Specifies whether or not to append written data to the end of the new document if it already exists. The interpretation of this flag is determined by the implementation of this interface.

Returns:

A newly created (empty) document.

Throws:

java.lang.Exception - Thrown if the document name is malformed, or if the document already exists and cannot be overwritten, or if some other error occurs.

java.lang.UnsupportedOperationException - (unchecked) Thrown if the append mode specified is not supported by this document storer.

Since:

1.1, 2001-07-02

See Also:

store(tribble.search.DocumentI), remove(java.lang.String), createDirectory(java.lang.String)

createDirectory

public void createDirectory(java.lang.String name)
                     throws java.lang.Exception,
                            java.lang.UnsupportedOperationException

Create a new directory in the document storage system.

It is up to the implementation of this interface whether or not it supports directories and subdirectories and how it creates them if it does.

Parameters:

name - The name of the new directory to create. Whether or not this name constitutes a meaningful and valid directory name is determined by the implementation of this interface.

Throws:

java.lang.Exception - Thrown if the directory name is malformed, or if the directory already exists, or if the new directory cannot be creaed, or if some other error occurs.

java.lang.UnsupportedOperationException - (unchecked) Thrown if this method is not supported by this document storer.

Since:

1.2, 2001-07-02

See Also:

create(java.lang.String, boolean), removeDirectory(java.lang.String)

store

public void store(DocumentI doc)
           throws java.lang.Exception

Store a document into the document storage system.

It is up to the implementation of this interface how it stores a new document.

Parameters:

doc - The document to store into the document storage system. This should be a document object previously returned by create().

Throws:

java.lang.Exception - Thrown if the document is malformed, or if the document cannot be written into the storage system, or if some other error occurs.

Since:

1.1, 2001-07-02

See Also:

create(java.lang.String, boolean)

remove

public void remove(java.lang.String name)
            throws java.lang.Exception,
                   java.lang.UnsupportedOperationException

Remove a document from the document storage system.

It is up to the implementation of this interface how it removes a document.

Parameters:

name - The name of the new document to remove. Whether or not this name constitutes a meaningful and valid document name is determined by the implementation of this interface.

Returns:

A newly created (empty) document.

Throws:

java.lang.Exception - Thrown if the document name is malformed, or if the document does not exist, or if the document cannot be removed, or if some other error occurs.

java.lang.UnsupportedOperationException - (unchecked) Thrown if this method is not supported by this document storer.

Since:

1.1, 2001-07-02

See Also:

create(java.lang.String, boolean), removeDirectory(java.lang.String)

removeDirectory

public void removeDirectory(java.lang.String name)
                     throws java.lang.Exception,
                            java.lang.UnsupportedOperationException

Remove a directory from the document storage system.

It is up to the implementation of this interface whether or not it supports directories and subdirectories and how it removes them if it does.

Parameters:

name - The name of the existing directory to remove. Whether or not this name constitutes a meaningful and valid directory name is determined by the implementation of this interface.

Throws:

java.lang.Exception - Thrown if the directory name is malformed, or if the directory does not exist, or if the new directory cannot be removed, or if some other error occurs.

java.lang.UnsupportedOperationException - (unchecked) Thrown if this method is not supported by this document storer.

Since:

1.2, 2001-07-02

See Also:

createDirectory(java.lang.String)