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)