source: main/tags/3.00/gsdl3/README@ 25390

initial prototype of gsdl3

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 $CP to the CP="...." line ie. CP="$CP:..." - this sets up the 
class path properly

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.