Readme for the LuceneServer
===========================

The luceneserver is a socket based XML client for the lucene search engine.

It accepts requests in an XML format and will return XML responses.  The aim
is to leverage the lucene search engine in a language independant way.

Requirements:
  - Java 1.3.1 or higher.
Everything else is contained in the distribution (including lucene itself).
To compile the luceneserver there are additional requirements please see the 
readme.developer.txt file for more information.


Getting Started
---------------

Unpack the distribution archive into a directory somewhere 
(eg c:\luceneserver or ~/luceneserver).  Ensure Java is installed. Running
java -version should give you the java version information.  If it returns 
an error then Java needs to be installed properly before the luceneserver
will function.

To start the luceneserver:

Method A: Use ANT, see developer readme for more information.
Method B: Use the runserver script.
Windows: Open a command prompt,
         Go to the directory where you unpacked the luceneserver
         Type: bin\runserver

You should see some debug information similar to the following:
(please note that I have removed the date and time to save space)
 Log4jConfigPath:null
 Loading config from Server.config
 Log4jConfigPath:etc/log4j.xml
 log4j:WARN No such property [encoding] in org.apache.log4j.PatternLayout.
 Logging now passed to Log4J.
 WARN  [main] LuceneServer now initialised and Log4J logging started.
 DEBUG [main] Getting start list: nz.net.catalyst.lucene.server.Server.st...
 INFO  [main] Reading Application properties from: etc\application\sos.pr...
 ...
 ...
 DEBUG [main] About to invoke nz.net.catalyst.lucene.server.Server.Start
 INFO  [main]    Starting LuceneServer version 0.3dev [XML enabled]
 DEBUG [main] Returned from nz.net.catalyst.lucene.server.Server.Start


Running the Demo Programs
-------------------------

The demo programs are intended to be run from the command line in another
window from the luceneserver itself (they can with some modification be run
from another machine, which is the intented use).

 Open a command window.
 Change direcotry to the luceneserver directory.
 
 To index a single document run:  bin\index
 To query the above document run: bin\query
 
NOTE: The index needs to be created before querying can take place.  This 
is done automatically when first indexing a document.


Finding out More
----------------

There are more documents in the doc directory.  These include:
 protocol_xml.txt  - documentatin on the xml protocol used.
 protocol.txt      - legacy protocol documentation
 notes.txt         - notes that didn't fit anywhere else
 benchmark.txt     - some benchmarking information.
 Index_Maration.txt- more figures about the benchmark
 LuceneRequest.dtd - XML Request DTD.
 LuceneResponse.dtd- XML Response DTD.
 Lucene_FileFormats.doc - information saved from the lucene-user mailing
                          list about internal lucene file formats.

Again, the readme.developer.txt contains some more technical information about
the luceneserver.

Troubleshooting
---------------

This section will be expanded with common problems and hopefully some
solutions to them.

Problem: NoClassDefFoundError when running scripts.
Error message: "Exception in thread "main" java.lang.NoClassDefFoundError:
               nz/net/catalyst/lucene/server/Server"
Solution: Java cannot find the luceneserver files.  This can be caused by 
    running the scripts from the wrong directory.  Make sure you are in the
    luceneserver root directory. e.g. c:\luceneserver and not in the 
    c:\luceneserver\bin directory where the scripts actually are.  
    This is because the scripts and default configuration rely on paths 
    relative to the luceneserver root.



This product includes software developed by the
Apache Software Foundation (http://www.apache.org/).