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>
|
---|
24 | Here, 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 />
|
---|
28 | For example here's UsernameService.java:
|
---|
29 | <pre>
|
---|
30 | package org.greenstone;
|
---|
31 |
|
---|
32 | public class UsernameService {
|
---|
33 | public String getUsername() { return "pinky"; }
|
---|
34 | }
|
---|
35 | </pre>
|
---|
36 | Compile 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 />
|
---|
39 | Since 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>
|
---|
44 | the file $GSDLHOME/web/WEB-INF/server-config.wsdd would have been generated.
|
---|
45 | It would contain one or more <service> elements.
|
---|
46 |
|
---|
47 | <p>Stop Greenstone's tomcat:
|
---|
48 | <pre>ant stop</pre></p>
|
---|
49 |
|
---|
50 | Copy an existing <service> element in order to create a <service> element for your web service.
|
---|
51 | In our example case, you could have:
|
---|
52 | <pre>
|
---|
53 | <service name="UsernameService" provider="java:RPC">
|
---|
54 | <parameter name="allowedMethods" value="getUsername"/>
|
---|
55 | <parameter name="className" value="org.greenstone.UsernameService"/>
|
---|
56 | </service>
|
---|
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 | <service name="MyWebServices" provider="java:RPC">
|
---|
66 | <parameter name="allowedMethods" value="*"/>
|
---|
67 | <parameter name="className" value="org.greenstone.WebServices"/>
|
---|
68 | </service>
|
---|
69 | </pre>
|
---|
70 | </li>
|
---|
71 | </ul>
|
---|
72 | </li>
|
---|
73 |
|
---|
74 | <li>We now need to deploy the web service.
|
---|
75 | Start tomcat:
|
---|
76 | <pre>ant start</pre>
|
---|
77 | And 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>
|
---|
79 | Change the computer host and port to suit your situation. For example<br />
|
---|
80 | <blockquote>
|
---|
81 | java -cp $AXISCLASSPATH org.apache.axis.client.AdminClient -lhttp://harakeke:8080/greenstone3/services/AdminService web/WEB-INF/server-config.wsdd
|
---|
82 | </blockquote>
|
---|
83 | Check it says DONE PROCESSING or something like it.
|
---|
84 | </li>
|
---|
85 |
|
---|
86 | <li>Stop Tomcat and restart it again.
|
---|
87 | In a browser go to the "services" page of Greenstone 3:
|
---|
88 | <pre>http://localhost:8080/greenstone3/services</pre>
|
---|
89 | and 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>
|
---|
94 | Tried to run axis AdminClient on the server-config.wsdd (service descriptor) file and got an AxisFault Exception?<br />
|
---|
95 | SOLUTION: You have to run tomcat (ant start) before running AdminClient.
|
---|
96 |
|
---|
97 | </body>
|
---|
98 | </html> |
---|