Writing web services in general - using Java and Apache Axis

In this document,

• $GSDLHOME is the full path to your greenstone 3 directory.

Sections

• A The basics of writing and deploying web services in general
• B Troubleshooting

A The basics of writing and deploying web services in general

1. Write a Java class that will become the web service.
   For example here's UsernameService.java:

   package org.greenstone;
   
   public class UsernameService {
   	public String getUsername() { return "pinky"; }
   }
   

   Compile it. (Say in Eclipse.)
2. Copy the *.class file into the correct package structure inside web/WEB-INF/lib/classes folder of Apache axis.
   Since we are using Greenstone 3, this is $GSDLHOME/web/WEB-INF/classes/. Therefore, in our example, we would copy UsernameService.class into $GSDLHOME/web/WEB-INF/lib/classes/org/greenstone/
3. Once you have deployed localsite (or other site) in Greenstone3 using

   ant deploy-localsite

   the file $GSDLHOME/web/WEB-INF/server-config.wsdd would have been generated. It would contain one or more <service> elements.

   Stop Greenstone's tomcat:

   ant stop

   Copy an existing <service> element in order to create a <service> element for your web service. In our example case, you could have:

    <service name="UsernameService" provider="java:RPC">
     <parameter name="allowedMethods" value="getUsername"/>
     <parameter name="className" value="org.greenstone.UsernameService"/>
    </service>
   

   NOTES:
   • Set the service's provider attribute to "java:RPC"
   • The serviceName is what you want appearing in the wsdl file (it need not be the same as the class name)
   • the className value is your web service Java class with full-package structure.
   • 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:

      <service name="MyWebServices" provider="java:RPC">
       <parameter name="allowedMethods" value="*"/>
       <parameter name="className" value="org.greenstone.WebServices"/>
      </service>
     

4. We now need to deploy the web service. Start tomcat:

   ant start

   And now use Axis' AdminClient tool to deploy the web service by typing the following in the x-term from within the GSDLHOME folder:

   java -cp $AXISCLASSPATH org.apache.axis.client.AdminClient -lhttp://YOURCOMPUTER:YOURPORT/greenstone3/services/AdminService web/WEB-INF/server-config.wsdd

   Change the computer host and port to suit your situation. For example
   

   java -cp $AXISCLASSPATH org.apache.axis.client.AdminClient -lhttp://harakeke:8080/greenstone3/services/AdminService web/WEB-INF/server-config.wsdd

   Check it says DONE PROCESSING or something like it.
5. Stop Tomcat and start it again. In a browser go to the "services" page of Greenstone 3:

   http://localhost:8080/greenstone3/services

   and find the new service there. There will be a link to its WSDL file as well.

B Troubleshooting