source: other-projects/trunk/gs3-webservices-democlient/docs/HowToFiles/1GettingGS3WebServicesRunning.html@ 15338

Last change on this file since 15338 was 15338, checked in by ak19, 13 years ago

Documentation on how to run the demo-client, how to write and deploy web services and how to write web service clients

  • Property svn:executable set to *
File size: 6.6 KB
Line 
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2
3<html>
4<head>
5<title>Getting web services running on the Greenstone 3 server</title>
6</head>
7<body>
8<a href="index.html">Back to index page</a>
9
10<h1>Getting web services running on the Greenstone 3 server</h1>
11
12You need:
13<ul>
14<li>Greenstone 3 (an up-to-date version, as described in Section A below)</li>
15</ul>
16
17In this document,
18<ul>
19<li>$GSDL3HOME refers to the full path to your Greenstone 3 installation.</li>
20<li>GS3 may be used as a shorthand to refer to Greenstone 3.</li>
21</ul>
22
23<h2>Sections</h2>
24<ul>
25<li><a href="#A">A Preliminary step: need to do this only once</a></li>
26<li><a href="#B">B How to deploy web services on Greenstone 3</a></li>
27<li><a href="#C">C Undeploying web services from Greenstone 3</a></li>
28</ul>
29
30
31<h2><a name="A">A Preliminary step: need to do this only once</a></h2>
32In all likelihood, this step will not be required for versions later than Greenstone 3.03.
33<ul>
34<li>You can either download the latest Greenstone 3 source code from SVN, then compile and install it.</li>
35<li>OR, if you have got a version of Greenstone 3 installed from source already and don't want to get it all over again, then try the following:
36<ol>
37<li>Make a folder to store back up copies of the files
38<ul>
39<li>$GSDLHOME/build.xml</li>
40<li>$GSDLHOME/build.properties</li>
41<li>$GSDLHOME/resources/soap/site.wsdd.template </li>
42<li>$GSDLHOME/resources/soap/undeploy-site.wsdd.template</li>
43</ul>
44</li>
45
46<li>You need to download the following files. Make sure you click on the files and go to the bottom of the pages where there's a download link.
47<ul>
48<li>go to http://trac.greenstone.org/browser/greenstone3/trunk and download build.xml and build.properties</li>
49<li>go to http://trac.greenstone.org/browser/greenstone3/trunk/resources/soap and download site.wsdd.template and undeploy-site.wsdd.template</li>
50<li>go to http://trac.greenstone.org/browser/greenstone3/trunk/resources/java and get QBRSOAPServer.java.in</li>
51<li>go to http://trac.greenstone.org/browser/greenstone3/trunk/web/WEB-INF/classes and download QBRWebServicesHelp.properties</li>
52</ul>
53</li>
54
55<li>Put these downloaded files into similar locations on in your $GSDLHOME installation:
56<ul>
57<li>$GSDLHOME/build.xml</li>
58<li>$GSDLHOME/build.properties</li>
59<li>$GSDLHOME/resources/soap/site.wsdd.template </li>
60<li>$GSDLHOME/resources/soap/undeploy-site.wsdd.template</li>
61<li>$GSDLHOME/resources/java/QBRSOAPServer.java.in</li>
62<li>$GSDLHOME/web/WEB-INF/classes and download QBRWebServicesHelp.properties</li>
63</ul>
64</li>
65</ol>
66</li>
67</ul>
68
69
70<h2><a name="B">B How to deploy web services on Greenstone 3</a></h2>
71We'll look at the example of deploying the "QBRSOAPServer" web service which is used by the GS3-webservices-democlient application.
72<ol>
73<li>Go into your $GSDLHOME folder and start tomcat by typing in an X-term or ms-dos prompt:
74<pre>ant start</pre>
75
76<p>(NOTE: Previously, only the fundamental SOAPServer class offered web services for Greenstone. And those web services could and can still be deployed with
77<pre>ant deploy-localsite</pre>
78This deploys SOAPServer's "process" web service operation on your localhost server. And you can view the effects of deploying it by going to http://localhost:8080/greenstone3/services. Its WSDL can be accessed via that page as well.)</p>
79
80<p>While "ant deploy-localsite" deploys the same default SOAPServer web service, we want to deploy another web service this time.</p>
81
82<p>We'll be deploying the new QBRSOAPServer web services, which will provide basic query, browse and retrieval web service operations. This is what the GS3-webservices-democlient uses:
83<pre>ant soap-deploy-site</pre>
84<ol style="list-style-type:lower-alpha">
85<li>The first time it prompts you, you need to choose the Greenstone3 site you want to deploy the services for. (Localsite on localhost is the default). </li>
86<li>The next time, you need to type the name of the set of web services you wish to deploy. In this case, type
87<pre>QBRSOAPServer</pre>
88Note the use of caps and lowercase letters.</li>
89<li>Finally it will ask you want you want to call this set of web services. You can either accept the default name&mdash;which would be QBRSOAPServerlocalsite if you had chosen to deploy it for localsite&mdash;or you can type some other name for the web services. (For instance, GS3AccessWebServices.)<br />
90At present, just accept the default service name of QBRSOAPServerlocalsite.</li>
91</ol>
92If all went well, it would now have been deployed.
93</li>
94
95<li>Point your browser to the Greenstone site you deployed them for and go to the "services" page. For example, if the services were deployed for localsite and your port was 8080, you'd go to:
96<pre>http://localhost:8080/greenstone3/services</pre>
97And on this page, it will mention QBRSOAPServerlocalsite (or whatever name you chose for the web services) among the list of web services deployed.<br />
98There will be a link named <b>wsdl</b> next to the web service name. (You can click on the wsdl link to view the contents of this XML file. This file describes the web services: the url of the services, the operations it provides, the number and types of the values the operations take and returns.) We won't do anything special with all this other than copy the url for the WSDL file.
99
100<p>For example, depending on the serviceName you chose and the host/port where the services have been deployed on, this might be
101<pre>
102http://localhost:8080/greenstone3/services/QBRSOAPServerlocalsite?wsdl
103</pre></p>
104</li>
105</ol>
106
107<h2><a name="C">C Undeploying web services from Greenstone 3</a></h2>
108When you don't want the web services deployed anymore, you can undeploy them.
109<ol>
110<li>Go into $GSDLHOME folder. Make sure tomcat is running (if not, type "ant start").</li>
111<li>Type in an X-term:
112<pre>ant soap-undeploy-site</pre>
113</li>
114<li>Type the name of the web services you wish to undeploy.<br />
115If you don't remember what the name is anymore, point your browser to the Greenstone site you deployed them for and go to the "services" page again.
116For instance, if my Greenstone3 server is listening at port 8080 on my local computer, I'd go to:
117<pre>http://localhost:8080/greenstone3/services</pre>
118The services page will list the deployed web services. Get the name of the web service you want to undeploy from here. Go back to your x-term and type this in to undeploy the chosen web service.<br />
119For instance, if we had a web service with the name "QBRSOAPServerlocalsite" deployed and wanted it removed, we'd type that name.
120</li>
121</ol>
122
123</body>
124</html>
Note: See TracBrowser for help on using the repository browser.