tribble.search
Interface DocumentSearcherI

All Known Implementing Classes:
FDirectory, FtpSearcher, ZArchive

public interface DocumentSearcherI

Generic document searcher.

Implementations of this interface provide the capability of searching for documents. The term document is used in a very generic sense, referring to any object that contains data that can be read and/or written.

    import tribble.search.*;

    public class MyDocSearcher
        implements tribble.search.DocumentSearcherI
    {
        ...
    }
 

A document searcher allows client classes to apply a set of search criteria in order to locate documents. Information about each found document can then be retrieved, as well as it data contents. This model assumes a very simple hierarchical arrangement of searchers being able to locate one or more documents, each of which contains data of some sort.

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

  • file system directories
  • ZIP archive files
  • LDAP directory services
  • JNDI naming services
  • FTP access services
  • etc.

    The find() method of a document searcher object returns an enumeration which is used to interate through the complete list of matching document entries found by the searcher.

        MyDocSearcher   src;
        Hashtable       props;
        MyNameFilter    filt;
        Enumeration     iter;
    
        // Create and initialize a new searcher object
        src = new MyDocSearcher(...);
        props = new Hashtable();
        props.put(..., ...);
        src.initialize(props);
        src.open(...);
    
        // Find zero or more documents
        filt = new MyNameFilter(...);
        iter = src.find(filt);
    
        // Iterate through the list of matching documents
        while (iter.hasMoreElements())
        {
            MyDoc   doc;
    
            // Get the next matching document
            doc = (MyDoc) iter.nextElement();
            ... process document 'doc' ...
        }
     

    Some of the methods of this interface were modelled after the ZipFile class.

    Since:
    2001-02-27
    Version:
    $Revision: 1.4 $ $Date: 2001/07/02 22:46:36 $
    Author:
    David R. Tribble (david@tribble.com).
    Copyright 2001 by David R. Tribble, all rights reserved.
    See Also:
    DocumentI, DocumentFilterI, DocumentStorerI

    Field Summary
    static java.lang.String REV
              Revision information.
    static int SERIES
              Series number.
     
    Method Summary
     void close()
              Close this searcher.
     java.util.Enumeration find(DocumentFilterI filt)
              Locate and retrieve documents from this searcher matching given filtering criteria.
     void initialize(java.util.Hashtable parms)
              Initialize this searcher.
     void open(java.lang.String path)
              Open a given search path for this searcher.
     boolean outputSupported()
              Determine if documents can be written to this searcher.
     

    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 searcher.

    This must be the first method to be called on this searcher object, prior to calling the open(java.lang.String) 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 searcher. 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-05-01
    See Also:
    open(java.lang.String)

    open

    public void open(java.lang.String path)
              throws java.lang.Exception
    Open a given search path for this searcher.

    Parameters:
    path - The name of a path (which can be anything meaningfully interpreted as a path, such as a filename or URL) specifying the location of the searcher to open and search.
    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-05-05
    See Also:
    close(), initialize(java.util.Hashtable)

    close

    public void close()
               throws java.lang.Exception
    Close this searcher.

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

    Throws:
    java.lang.Exception - Thrown if an error occurs.
    Since:
    1.1, 2001-02-27
    See Also:
    open(java.lang.String)

    find

    public java.util.Enumeration find(DocumentFilterI filt)
                               throws java.lang.Exception
    Locate and retrieve documents from this searcher matching given filtering criteria.

    It is up to the implementation of this interface whether this method retrieves all of the matching documents at once or whether it retrieves them one at a time through the enumeration that is returned.

    Parameters:
    filt - A filter specifying document searching criteria. This can be null, in which case all possible documents from this searcher are returned.
    Returns:
    An enumeration of DocumentI objects representing the list of documents found by this searcher, or null if there are no matching documents to be found.
    Throws:
    java.lang.Exception - Thrown if the specified criteria are malformed, or if some other error occurs.
    Since:
    1.2, 2001-06-15

    outputSupported

    public boolean outputSupported()
    Determine if documents can be written to this searcher.

    Returns:
    True if the DocumentI#getOutputStream method is supported by document objects found by this searcher, otherwise false.
    Since:
    1.1, 2001-05-30