source: trunk/gsdl3/README@ 3286

initial prototype of gsdl3

2002/07/30 *********************************

think we will use java servlets rather than cgi. can use tomcat to serve our 
servlets as well as for the soap stuff (in fact, rpcrouter is a servlet that 
does soap stuff)

I have added a test html page, and a test servlet.

tomcat should already be installed (if not, see below).

you need to edit the tomcat conf/server.xml to add a context for gsdl servlets
add this line near the soap one:

    <!-- GSDL3 Service -->
    <Context path="/gsdl3" docBase="<GSDLHOME>/web" debug="1" reloadable="true"/>

when you edit server.xml, (or change web.xml in gsdl3/web/WEB-INF/web.xml) or
change the classes, you need to shutdown and restart the server. also you may 
need to clear the cache of your browser

once you have made the test servlet class,
(in web/WEB-INF/classes, javac TestServlet.java)
you can run it.

localhost:8080/gsdl3 should get you the index page - can click on the link to 
run the test. or can specify it directly:
localhost:8080/gsdl3/testing

the path 'testing' is determined by servlet-mapping entry in 
web/WEB-INF/web.xml 

Note: also changed setup.bash to only have CLASSPATH, not CP - need to change
the CP entry in catalina.sh to use CLASSPATH instead - see below in Tomcat 
installation
2002/07/16 *********************************

MGPP java wrapper

a java interface has been added for mgpp.

the java code is in src/java/org/greenstone/mgpp
the cpp code in src/cpp/jni/mgpp

you need to run make in the java part before the cpp part, as the java stuff
creates the jni header file for the cpp side

in src/java/org/greenstone/mgpp do:
make
make install

in src/cpp/jni/mgpp do:
make 
make install

run the Queryer:
java org.greenstone.mgpp.Queryer <basedir> <indexdir> <textdir>

eg if have a mgpp collection in gsdl/collect/mgppdemo
java org...Queryer gsdl/collect/mgppdemo/index tt/mgppdemo text/mgppdemo

for this to work (termporarily) you need to get the mgpp source from gsdl as
it hasn't been added to gsdl3 cvs yet

if you already have gsdl installed, then build a collection using mgpp (see
greenstone doc and source collection at nzdl2.cs.waikato.ac.nz for more info - search for mgpp)

you need to edit the src/cpp/jni/mgpp Makefile to set the correct include 
directories.
also copy gsdl/src/mgpp/lib/libmg.a and gsdl/src/mgpp/text/libtextin.a to 
gsdl3/lib/cpp

(and if you want 'make test' to work in src/java/org/greenstone/mgpp you need to change the command to run)

the make steps above should now work.

if you dont have gsdl yet, do:
cvs co gsdl
cd gsdl
./configure
make 
make install

then build collections etc (good luck)

2002/07/05 *******************************

only for linux

need to run setup.bash to set CLASSPATH etc

java src code in src/java/org/greenstone/gsdl3 - you need to do a  make, and 
then a make install in this top directory. - makes all the classes in the 
subdirectories too.

classes get compiled to src/java/org/greenstone/gsdl/classes, then a jar file
is made of them all. make install copies this to lib/java

There are two executable classes: Library1 and Library2

both are run by "java org.greenstone.gsdl3.Libraryx <gsdlhome> <sitehome>"

gsdlhome is the base dir for your installation: .../gsdl3
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

(imaginative names eh)

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 below)

Library1 - just takes straight XML queries and returns the results. see docs/xml/* for examples - not there yet. can use the other library to see how requests are formatted
basically its 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.

Library2 - still command line based, but has a slightly nicer interface.
it will prompt you for commands eg
type of request - describe/query
collection name
service name
info name (at the moment collectionList, serviceList, siteList)
these can all be left blank except for the first one
A sample usage thingy:

describe,_,_,_ - returns info from MessageRouter - list of colls, sites, services etc

describe,_,_,collectionList - returns info from MessageRouter - only a list of colls

describe,demo,_,_ - returns info from demo coll - list of services

describe,demo,TextQuery,_ - returns info about the service

Library2 also attempts to use some XSLT transforms to format the resulting xml

********************************************************************

SOAP stuff.

am using jakarta tomcat at this stage to serve the SOAP classes
-----------------------------------------------------
set up SOAP Server:

the class SOAPServer is a wrapper around a messagerouter - so can serve 
the collections

it has a path hard coded in  - need to set this to your appropriate site - 
for the example sites that I've set up, it should be <GSDL3HOME>/sites/site2
--------------------------------------------------------------------
TOMCAT installation:

need to install tomcat and soap:


 a tar file is in comms/tomcat directory - not sure where to put this, so made a new directory for it

you need to unzip the tar file.

edit jakarta-tomcat-4.0.1/bin/catalina.sh:

on line 89 add $CLASSPATH to the CP="...." line ie. CP="$CLASSPATH:..." - this 
sets up the class path properly (note this has changed since last time 
2002/07/30)

edit jakarta-tomcat-4.0.1/conf/server.xml

add the following (put proper path for <GSDL3HOME>)

<!-- SOAP Service -->
<Context path="/soap" docBase="<GSDL3HOME>/comms/soap/soap-2_2/webapps/soap" debug="1" reloadable="true"/>

(there are other Context elements to look at)

---------------------------------------------------------------------
install soap:

just untar soap-bin-2.2.tar.gz in the comms/soap directory
--------------------------------------------------------------
to run tomcat, need to source setup.bash in GSDL3HOME to set up $CP

then cd to comms/tomcat/jakarta-tomcat-4.0.1/bin

run startup.sh

to shut down tomcat, run shutdown.sh

you can access the soap service though the web, at http://localhost:8080/soap

(conf/server.xml is the place to change the port number if needed)


Run the admin client

can list, deploy, undeploy soap services

-----------------------------------------------------------------
to deploy the SOAPServer for site2:

edit the following fields in the deploy form:

ID:  org.greenstone.site2
Scope: any will do: Request - new instantiation for each request
            Session - same instantiation across a session
            Application - only uses one instantiation

Methods: process

Java Provider / Provider Class: org.greenstone.gsdl3.SOAPServer

then click deploy.
hopefully all will be well.

---------------------------------------------------------

shoudl be able to run (from GSDL3HOME directory)
java org.greenstone.gsdl3.Library2 . ./sites/site1

and have it talk via soap. (assuming you have tomcat running and have deployed
org.greenstone.site2)

--------------------------------------------------------

debugging soap:

tomcat output goes to jakarta-tomcat-4.0.1/logs/catalina.out

if you recompile the classes, you need to shutdown and restart tomcat to get the new classes.

deployment info is retained between shutdown and start up - dont need to redeploy it each time.

TcpTUnnelGui:

this program allows you to view the actual soap messages

run like:

java org.apache.soap.util.net.TcpTunnelGui 8070 localhost 8080

tomcat uses 8080, and you need to modify the greenstone stuff to talk to port 8070 instead of 8080:

sites/site1 is the site that talks to the SOAPServer for site2

in site1/sitecfg.xml, in the address field, replace 8080 with 8070 when you want to use TcpTunnelGui.

note that 
http://localhost:8080/soap/servlet/rpcrouter

is the address for talking to the tomcat soap thingy.


-------------------------------------------------------------------