* 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:
*
* 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
* {@link java.util.zip.ZipFile} class.
*
*
* @version $Revision: 1.4 $ $Date: 2001/07/02 22:46:36 $
* @since 2001-02-27
* @author
* David R. Tribble
* (david@tribble.com).
*
* Copyright
* ©2001 by David R. Tribble, all rights reserved.
*
* @see DocumentI
* @see DocumentFilterI
* @see DocumentStorerI
*/
public interface DocumentSearcherI
{
// Identification
/** Revision information. */
static final String REV =
"@(#)tribble/search/DocumentSearcherI.java $Revision: 1.4 $ $Date: 2001/07/02 22:46:36 $\n";
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
// Public constants
/** Series number. */
public static final int SERIES = 200;
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
// Public methods
/***************************************************************************
* Initialize this searcher.
*
*
* This must be the first method to be called on this searcher object, prior * to calling the {@link #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 searcher. 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-05-01 */ public void initialize(Hashtable parms) throws Exception; /*************************************************************************** * Open a given search path for this searcher. * * @param 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 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-05-05 */ public void open(String path) throws Exception; /*************************************************************************** * Close this searcher. * *
* This must be the last method to be called on this searcher object. * * @throws Exception * Thrown if an error occurs. * * @see #open * * @since 1.1, 2001-02-27 */ public void close() throws 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. * * @param filt * A filter specifying document searching criteria. This can be null, in * which case all possible documents from this searcher are returned. * * @return * An enumeration of {@link DocumentI} objects representing the list of * documents found by this searcher, or null if there are no matching * documents to be found. * * @throws Exception * Thrown if the specified criteria are malformed, or if some other error * occurs. * * @since 1.2, 2001-06-15 */ public Enumeration find(DocumentFilterI filt) throws Exception; /*************************************************************************** * Determine if documents can be written to this searcher. * * @return * True if the {@link DocumentI#getOutputStream} method is supported by * document objects found by this searcher, otherwise false. * * @since 1.1, 2001-05-30 */ public boolean outputSupported(); } // End DocumentSearcherI.java