home *** CD-ROM | disk | FTP | other *** search
/ PC World Komputer 1995 November / PCWK1195.iso / inne / win95 / sieciowe / hotja32.lzh / hotjava / classsrc / browser / tools / javasearch / readme < prev    next >
Text File  |  1995-08-11  |  9KB  |  215 lines
  1.     The JavaSearch toolkit   @(#)README    1.7 95/03/20     -*- Text -*-
  2.  
  3.                   David Brown, Sun Microsystems Inc., November 1994
  4.  
  5.  
  6. JavaSearch is a collection of classes used to CREATE and SEARCH
  7. inverted-index text databases.  JavaSearch is used in a two-step
  8. process:
  9.  
  10. (1) Use the "javaindex" program to build an JavaSearch database for a
  11.     collection of documents.
  12.  
  13. (2) Use the Database, Searcher, DocList and Doc classes in YOUR
  14.     application to search an JavaSearch database.
  15.  
  16. Here's the details on the two steps:
  17.  
  18. ----- (1) Creating an JavaSearch database -----
  19.  
  20. Use the javaindex program.  Usage is:
  21.  
  22.    java javaindex -db database_name [-trimprefix path_to_trim]
  23.         [-fileprefix path_prefix] [-urlprefix url_prefix]
  24.         [-description "Description of this database"]
  25.         filename filename ...
  26.  
  27. Where:
  28.  
  29.   database_name is used to construct the 5 filenames which will
  30.       be created by javaindex, and is the name you need to know when
  31.       you later want to *search* the database.  See Database.java
  32.       for info on the 5 filenames.
  33.       
  34.       database_name can either be relative to the current directory,
  35.       or an absolute path.  For example, using the database name
  36.  
  37.           /foo/bar/databases/JAVASPEC
  38.  
  39.       will cause the files JAVASPEC.dbinfo, JAVASPEC.index,
  40.       JAVASPEC.qindex, JAVASPEC.docs, and JAVASPEC.docindex to all be
  41.       created in the directory "/foo/bar/databases".
  42.  
  43.   path_to_trim is a string that should be trimmed off the BEGINNING of
  44.       every filename we index, before saving a Doc object for that
  45.       filename in the Database we're creating.  This is important
  46.       because URLs are constructed by concatenating the DATABASE's URL
  47.       prefix with the DOCUMENT's filename!
  48.  
  49.       So if you're indexing the files /foo/bar/baz/*.html, and these
  50.       files happen to be accessible by URLs like
  51.       "http://tachyon.eng/baz/*.html", you would TRIM /foo/bar/baz/
  52.       and use a urlprefix of http://tachyon.eng/baz/.
  53.  
  54.       Here's a real-world example, for the Java spec:
  55.  
  56.         java javaindex -db JAVA_SPEC                                 \
  57.           -trimprefix /net/tachyon/export/disk1/Mosaic/docs/spec/  \
  58.           -urlprefix http://tachyon.eng/spec/                      \
  59.           /net/tachyon/export/disk1/Mosaic/docs/spec/*.html
  60.  
  61.  
  62.   path_prefix is the string that should be prepended to the "filename"
  63.       of each individual Doc in this database, to construct a valid
  64.       fully-qualified pathname.  For example, you might index all the
  65.       files in the current directory like this:
  66.  
  67.        java javaindex -db FOO -fileprefix /full/path/to/this/dir/ *
  68.  
  69.  
  70.   url_prefix is the string that should be prepended to the "filename"
  71.       of each individual Doc in this database, to construct a valid
  72.       URL pointing to that document.  See above for an example.
  73.  
  74.       url_prefix and path_prefix may be used together, although in
  75.       general a Database will either be full of HTML files (in which
  76.       case they are always going to be accessed as URLs) or full of
  77.       plain text files (in which case path_prefix should be used,
  78.       since the documents will be read as regular files).
  79.  
  80.   description is a human-readable description of this database.
  81.  
  82.   filename ...   This is the list of documents to index.  These
  83.       filenames must be either absolute pathnames, or relative to the
  84.       current directory, although remember the "path_to_trim" string
  85.       is stripped off all filenames before they're stored in the
  86.       Database. 
  87.  
  88. Sorry if the path_to_trim/path_prefix/url_prefix stuff is confusing;
  89. note that WAIS does it the same way, though.  Look for my notes on
  90. "WAIS's URL type" in /net/barchetta/opt/wais/README.
  91.  
  92. Javaindex prints out a bunch of useful statistics when it finished
  93. creating a database.
  94.  
  95. ----- (2) Searching an JavaSearch database from your program -----
  96.  
  97. First of all, look at the program "javasearch.java": this is a very
  98.   simple command-line interface to perform searches on an JavaSearch
  99.   database.  It demonstrates how to open a database, do a search, and
  100.   look at the results.
  101.  
  102. In a nutshell, you do the following to perform a search:
  103.  
  104.         Database db = Database.OpenDatabase(database_name);
  105.         Searcher searcher = new Searcher(db);
  106.         DocList resultList = searcher.doSearch(query_string);
  107.  
  108. Now, use the DocList.getDocAt() method to look at the individual Doc
  109.   objects in the result list.  For any Doc, you can get the headline
  110.   (doc.headline), or a URL for the Doc (db.docURLPrefix+doc.filename),
  111.   or a full pathname for the Doc (db.docPathPrefix + doc.filename).
  112.  
  113. A Query string is a simple boolean expression, like (for example)
  114.   "method and matching".  Boolean operators "and", "or" and "not" are
  115.   allowed.  Precedence is a trivial left-to-right evaluation;
  116.   parentheses are not supported.  See the big doc comment for the
  117.   doSearch() method in Searcher.java for all the details.
  118.  
  119. That's all there is.  A typical "Searching app" or applet might give
  120.   the user text entry fields to select a database name and a query
  121.   string, then show the result headlines in a scrolling list, and then
  122.   have HotJava open the URL of any Doc which the user clicks on.
  123.  
  124. -----
  125.  
  126. See the detailed comment at the end of Database.java for a description
  127. of the Files used by JavaSearch, and an overview of most of the
  128. classes.
  129.  
  130. -----
  131.  
  132. EXAMPLES:
  133.  
  134. (1) Creating and searching a database of the Java language spec:
  135.  
  136.     cd livejava/src/share/contrib/JavaSearch  (eventually the JavaSearch
  137.                                             stuff should be in a package!)
  138.  
  139.     java -cs javaindex -db /tmp/JAVA_SPEC -trimprefix /net/tachyon/export/disk1/Mosaic/docs/spec/ -urlprefix http://tachyon.eng/spec/ /net/tachyon/export/disk1/Mosaic/docs/spec/*.html
  140.  
  141.     [This builds the database, in /tmp.]
  142.  
  143.     [Now search for "method and matching":]
  144.  
  145.     java -cs javasearch /tmp/JAVA_SPEC method and matching
  146.  
  147.     [Look at the results.  Selecting a document to view isn't too
  148.      useful here, since these documents have no valid filenames!
  149.      They're designed to be accessed by their URLs.]
  150.  
  151. (2) Creating a database of random text files, for example RFCs:
  152.  
  153.     java -cs javaindex -db /tmp/Patent-stuff -trimprefix /usr/green/doc/Patents-Original/ -fileprefix /usr/green/doc/Patents-Original/ /usr/green/doc/Patents-Original/*.txt
  154.  
  155.     [This takes a few minutes.  (The indexer really needs the 'btree
  156.      optimization' (see below)!)]
  157.  
  158.     [Now search:]
  159.  
  160.     java -cs javasearch /tmp/Patent-stuff geographic and navigation
  161.  
  162.     java -cs javasearch /tmp/Patent-stuff touch and interface not speech
  163.  
  164.     [Once you see the results, type a document number to
  165.     javasearch's prompt, and javasearch will display that file.]
  166.  
  167. -----
  168.  
  169. RESTRICTIONS:  
  170.  
  171. Here's a list of things that many other text search/retrieval systems
  172. can do that JavaSearch can't.  Some of these might be important to add
  173. at some point.
  174.  
  175. - When indexing, each input file is treated as a document.  Some other
  176.   systems let you have multiple documents per file.
  177.  
  178. - The searcher is missing numerous features found in other info
  179.   retrieval systems, such as:  relevance ranked (or "weighted")
  180.   results; stopwords; synonyms, word stemming and searches like "foo*"
  181.   for all words beginning with "foo"; literal searches (like "method
  182.   overloading"; full parsing of a hierarchical boolean query (with
  183.   parentheses for precedence grouping); word proximity searching
  184.   ("method near matching"); and many others.
  185.  
  186.   Some of these features would require significant changes to
  187.   JavaSearch's architecture, some would require slight changes in the
  188.   index format, and others could be implemented by changing only the
  189.   Searcher class.
  190.  
  191. - The indexer only currently knows about plain text or HTML files.
  192.   The code does have an *outline* for recognizing News articles --
  193.   just grep for "NEWS" to find all the places you need to change to
  194.   add a new doc type.
  195.  
  196. - The indexer is wildly suboptimal in how it keeps the Word objects in
  197.   memory while building an index -- it *should* use a btree, but
  198.   instead keeps Words in an unsorted Vector!  Sorry, I didn't get
  199.   around to writing a btree utility class.  But this only makes
  200.   indexing slow; it has no effect on Searching performance.  And
  201.   still, the indexer only takes a couple of minutes for small
  202.   databases like the Java documentation...
  203.  
  204. - Javaindex should have a "recursively index directories" feature.
  205.   This would work by having a command-line arg ("-R"?) that told
  206.   javaindex that each "filename" argument was really a directory,
  207.   and that it should index ALL files in that directory's hierarchy.
  208.   This is the only reasonable way to index very large databases, like
  209.   for example a news spool filesystem (like the fp.* groups).
  210.  
  211. - There's a whole bunch of other features which would be nice to have,
  212.   but I haven't had time to implement.  Look for "REMIND" comments in
  213.   the JavaSearch code to find lots of notes like this.
  214.  
  215.