source: trunk/gsdl3/RUNNING@ 3548

Note: when running the localhost:8080/gsdl3/library, only the mgppdemo 
collection 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 3 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: site2

sites/site2 can be run as a local site also.

to run site1, and talk to site2 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 current site/transform, current interface/transform, and
 finally default/transform

so you can change the interface by adding new xslt files to these three places.
 Note, if a stylesheet includes another one, eg they all include style.xsl, 
the included one needs to be in the same directory  - ie you need to either 
create a new one, or copy the default one to the new location.

******************************************************
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. fr is the 
only alternative to en 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" info="q/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" info="p/home"/></message>

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

search for frog in mgppdemo: (no docs returned)
<message lang="en"><request type="action" info="q/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" info="q/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.