source: other-projects/trunk/gs3-webservices-democlient/docs/HowToFiles/7BasicsOfWritingWebServices.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

File size: 4.0 KB
Line 
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2
3<html>
4<head>
5<title>Writing web services in general - using Java and Apache Axis</title>
6</head>
7<body>
8<a href="index.html">Back to index page</a>
9
10<h1>Writing web services in general - using Java and Apache Axis</h1>
11<p>In this document,
12<ul>
13<li>$GSDLHOME is the full path to your greenstone 3 directory.</li>
14</ul>
15</p>
16
17<h2>Sections</h2>
18<ul>
19<li><a href="#A">A The basics of writing and deploying web services in general</a></li>
20<li><a href="#B">B Troubleshooting</a></li>
21</ul>
22
23<h2><a name="A">A The basics of writing and deploying web services in general</a></h2>
24Here, we will write a web service in Java and use Apache Axis (which is installed with Greenstone 3) to deploy the web services. Otherwise we won't really be using Greenstone 3.
25
26<ol>
27<li>Write a Java class that will become the web service.<br />
28For example here's UsernameService.java:
29<pre>
30package org.greenstone;
31
32public class UsernameService {
33 public String getUsername() { return "pinky"; }
34}
35</pre>
36Compile it. (Say in Eclipse.)
37</li>
38<li>Copy the *.class file into the correct package structure inside web/WEB-INF/lib/classes folder of Apache axis.<br />
39Since we are using Greenstone 3, this is $GSDLHOME/web/WEB-INF/classes/<correct package structure>. Therefore, in our example, we would copy UsernameService.class into $GSDLHOME/web/WEB-INF/lib/classes/org.greenstone/
40</li>
41
42<li>Once you have deployed localsite (or other site) in Greenstone3 using
43<pre>ant deploy-localsite</pre>
44the file $GSDLHOME/web/WEB-INF/server-config.wsdd would have been generated.
45It would contain one or more &lt;service&gt; elements.
46
47Stop greenstone's tomcat:
48<pre>ant stop</pre>
49
50Copy an existing &lt;service&gt; element in order to create a &lt;service&gt; element for your web service.
51In our example case, you could have:
52<pre>
53 &lt;service name="UsernameService" provider="java:RPC"&gt;
54 &lt;parameter name="allowedMethods" value="getUsername"/&gt;
55 &lt;parameter name="className" value="org.greenstone.UsernameService"/&gt;
56 &lt;/service&gt;
57</pre>
58<b>NOTES:</b>
59<ul>
60<li>Set the service's provider attribute to "java:RPC"</li>
61<li>The serviceName is what you want appearing in the wsdl file (it need not be the same as the class name)</li>
62<li>the className value is your web service Java class with full-package structure.</li>
63<li>set the parameter allowedMethods to either the single method to be exposed, or if there is a list of them, then set the value to a comma-separated list of method names, or if you want ALL the class' public methods exposed, put a * for the value. See example below:
64<pre>
65 &lt;service name="MyWebServices" provider="java:RPC"&gt;
66 &lt;parameter name="allowedMethods" value="*"/&gt;
67 &lt;parameter name="className" value="org.greenstone.WebServices"/&gt;
68 &lt;/service&gt;
69</pre>
70</li>
71</ul>
72</li>
73
74<li>We now need to deploy the web service.
75Start tomcat:
76<pre>ant start</pre>
77And now use Axis' AdminClient tool to deploy the web service by typing the following in the x-term from within the GSDLHOME folder:
78<pre>java -cp $AXISCLASSPATH org.apache.axis.client.AdminClient -lhttp://YOURCOMPUTER:YOURPORT/greenstone3/services/AdminService web/WEB-INF/server-config.wsdd</pre>
79Change the computer host and port to suite your situation. For example<br />
80<blockquote>
81java -cp $AXISCLASSPATH org.apache.axis.client.AdminClient -lhttp://harakeke:8080/greenstone3/services/AdminService web/WEB-INF/server-config.wsdd
82</blockquote>
83Check it says DONE PROCESSING or something like it.
84</li>
85
86<li>Stop Tomcat and restart it again.
87In a browser go to the "services" page of the Greenstone 3:
88http://localhost:8080/greenstone3/services
89and find the new service there. There will be a link to its WSDL file as well.
90</li>
91</ol>
92
93<h2><a name="B">B Troubleshooting</a></h2>
94Tried to run axis AdminClient on the server-config.wsdd (service descriptor) file and got an AxisFault Exception?<br />
95SOLUTION: You have to run tomcat (ant start) before running AdminClient.
96
97</body>
98</html>
Note: See TracBrowser for help on using the repository browser.