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