source: trunk/gsdl3/RUNNING@ 3591

Note: when running the localhost:8080/gsdl3/library, only the mgppdemo and
chinese demo collections can do anything useful.

*******************************************************
There are 3 main parts to the system: sites, interfaces, library executables.

Sites contain collections. Interfaces contain images and xslts.

There are 2 sites in this prototype example.

sites/localsite is a standalone site, like used by a local library. It has
no connections to any other sites.

sites/site1 is a site that specifies a SOAP connection to another site: localsite

to run site1, and talk to localsite via SOAP, you need to have apache tomcat installed, running, and serving site2. (see INSTALL)

You can add other sites by putting a directory in the sites directory, and 
configuring it appropriately. TODO MakeSite program


There is one interface - default. you can add other interfaces if you like, in 
the interfaces directory. 

The interface and site to use for a particular servlet is determined by the 
init-params in the web.xml file 

XSL Files: when an xslt file is to be used, eg home.xsl, it is looked for in 
several places: in sites/current site/transform, interfaces/current interface/transform, and finally interfaces/default/transform

so you can change the interface by adding new xslt files to these three places.

******************************************************
Servlet:

need to run setup.bash to set CLASSPATH etc

Can run the web interface by starting tomcat (see INSTALL) and going to
localhost:8080/gsdl3/library

only mgpp collections can be searched - use mgppdemo, not demo.
Currently, only Text search works.

to change the interface language, you can add &l=fr to the url. However, there are no alternative langs at the moment.

*******************************************************
Command line libraries

need to run setup.bash to set CLASSPATH etc

there is a sample executable class: Library1

it can be run by "java org.greenstone.gsdl3.Library1  <sitehome>"

sitehome is the base dir for the site you are running:
 for the local library example site, its .../gsdl3/sites/localsite
 for the distributed soap example site, its .../gsdl3/sites/site1

Library1 - just takes straight XML queries and returns the results. It talks 
directly to the message router

basically messages are like:

<message><request type="describe|query" to="demo/TextQuery" info=""/></message>
with type="describe", to="", can use serviceList, collectionList and siteList 
for the info field.

this program is not very useful - except for debugging - when using the servlet
or Library2, can print out the messages - then cut and paste these for teh 
input to Library1

sample messages: (to cut and paste)

describe request to message router:
<message><request type="describe" to=""/></message>

describe request to collection:
<message><request type="describe" to="mgppdemo"/></message>

query:
<message><request type="query" to="mgppdemo/TextQuery"><paramList/><content>the</content></request></message>

get Titles for a list of docs:
<message><request type="query" to="mgppdemo/MetadataRetrieve"><paramList/><content><resourceList><resource name="HASH30aa188f4d8ddaef558fc9" /><resource name="HASH0102361bccb095d60673448c.3" /><resource name="HASH4632a8a51d33c47a75c559.4.1.5" /></resourceList><metadataList><element name="Title"/></metadataList></content></request></message>

get a document:
<message><request type="query" to="mgppdemo/ResourceRetrieve"><paramList/><content><resourceList><resource name="HASH30aa188f4d8ddaef558fc9" /></resourceList></content></request></message>


Library2: 

java org.greenstone.gsdl3.Library2 <sites home> <site name> <interfaces home> <interface name>  

takes xml request of 'cgi' params, and returns html (input must be all on one line)

<message lang="en">
<request type="action" action="q" subaction="text">
<paramList>
<param name="q" value="the"/>
</paramList>
</request>
</message>

the info field is action/subaction, eg a=p&sa=home, or a=q&sa=text

Some sample queries: (to cut and paste)

home page:
<message lang="en"><request type="action" action="p" subaction="home" /></message>

about page for mgppdemo:
<message lang="en"><request type="action" action="p" subaction="about""><paramList><param name="c" value="mgppdemo"/></paramList></request></message>

search for frog in mgppdemo: (no docs returned)
<message lang="en"><request type="action" action="q" subaction="text"><paramList><param name="c" value="mgppdemo"/><param name="q" value="frog"/><param name="md" value="10"/></paramList></request></message>

search for frog in mgppdemo, with stemming on: (some docs returned)
<message lang="en"><request type="action" action="q" subaction="text""><paramList><param name="c" value="mgppdemo"/><param name="q" value="frog"/><param name="md" value="10"/><param name="s" value="1"/></paramList></request></message>


Collections:

Can use the new java Queryer to test mgpp collections:

java org.greenstone.mgpp.Queryer <basedir> <indexdir> <textdir>

eg 
java org.greenstone.mgpp.Queryer sites/localsite/collect/mgppdemo/index  tt/mgppdemo text/mgppdemo

you can use any mgpp collection built with gsdl2 - you need to add a 
buildcfg.xml file to the index directory - look at the one for mgppdemo to see
what it should look like.