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