Back to index page

Writing web services in general - using Java and Apache Axis

In this document,


A The basics of writing and deploying web services in general

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.
  1. Write a Java class that will become the web service.
    For example here's
    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"/>
  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:
    and find the new service there. There will be a link to its WSDL file as well.

B Troubleshooting

Tried to run axis AdminClient on the server-config.wsdd (service descriptor) file and got an AxisFault Exception?
SOLUTION: You have to run tomcat (ant start) before running AdminClient.