//============================================================================== // DocumentStorerI.java //============================================================================== package tribble.search; // System imports import java.lang.Exception; import java.lang.String; import java.lang.UnsupportedOperationException; import java.util.Hashtable; // Local imports // (None) /******************************************************************************* * 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:
*
* The {@link #store 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 {@link #remove remove()} method deletes a named document from the storage
* system.
*
*
* @version $Revision: 1.2 $ $Date: 2001/07/02 21:13:49 $
* @since 2001-07-02
* @author
* David R. Tribble
* (david@tribble.com).
*
* Copyright
* ©2001 by David R. Tribble, all rights reserved.
*
* @see DocumentI
* @see DocumentFilterI
* @see DocumentSearcherI
*/
public interface DocumentStorerI
{
// Identification
/** Revision information. */
static final String REV =
"@(#)tribble/search/DocumentStorerI.java $Revision: 1.2 $ $Date: 2001/07/02 21:13:49 $\n";
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
// Public constants
/** Series number. */
public static final int SERIES = 100;
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
// Public methods
/***************************************************************************
* Initialize this document storer.
*
*
* This must be the first method to be called on this document storer object, * prior to calling the {@link #open open()} method. * *
* The implementation of this interface may allow this method to be called * more than once. * * @param 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 Exception * Thrown if the specified hash table entries are malformed, or if some other * error occurs. * * @see #open * * @since 1.1, 2001-07-02 */ public void initialize(Hashtable parms) throws Exception; /*************************************************************************** * Open a given storage path for this document storer. * * @param 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 Exception * Thrown if the specified path does not exist or is not accessible, or if it * is malformed, or if some other error occurs. * * @see #close * @see #initialize * * @since 1.1, 2001-07-02 */ public void open(String path) throws Exception; /*************************************************************************** * Close this document storer. * *
* This must be the last method to be called on this document storer object. * * @throws Exception * Thrown if an error occurs. * * @see #open * * @since 1.1, 2001-07-02 */ public void close() throws Exception; /*************************************************************************** * 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 * {@link #store store()} method is called. * * @param 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. * * @param 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. * * @return * A newly created (empty) document. * * @throws Exception * Thrown if the document name is malformed, or if the document already * exists and cannot be overwritten, or if some other error occurs. * * @throws UnsupportedOperationException (unchecked) * Thrown if the append mode specified is not supported by this document * storer. * * @see #store * @see #remove * @see #createDirectory * * @since 1.1, 2001-07-02 */ public WritableDocumentI create(String name, boolean append) throws Exception, 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. * * @param 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 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. * * @throws UnsupportedOperationException (unchecked) * Thrown if this method is not supported by this document storer. * * @see #create * @see #removeDirectory * * @since 1.2, 2001-07-02 */ public void createDirectory(String name) throws Exception, UnsupportedOperationException; /*************************************************************************** * Store a document into the document storage system. * *
* It is up to the implementation of this interface how it stores a new * document. * * @param doc * The document to store into the document storage system. This should be a * document object previously returned by {@link #create create()}. * * @throws Exception * Thrown if the document is malformed, or if the document cannot be written * into the storage system, or if some other error occurs. * * @see #create * * @since 1.1, 2001-07-02 */ public void store(DocumentI doc) throws Exception; /*************************************************************************** * Remove a document from the document storage system. * *
* It is up to the implementation of this interface how it removes a * document. * * @param 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. * * @return * A newly created (empty) document. * * @throws 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. * * @throws UnsupportedOperationException (unchecked) * Thrown if this method is not supported by this document storer. * * @see #create * @see #removeDirectory * * @since 1.1, 2001-07-02 */ public void remove(String name) throws Exception, 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. * * @param 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 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. * * @throws UnsupportedOperationException (unchecked) * Thrown if this method is not supported by this document storer. * * @see #createDirectory * * @since 1.2, 2001-07-02 */ public void removeDirectory(String name) throws Exception, UnsupportedOperationException; } // End DocumentStorerI.java