Back to index page

How to expose custom Greenstone 3 web services on GS3's server

What you need: In this document,


A Create your web service Java class

In the steps below, I am assuming that your web service class will be passing either If this is indeed the case, the default behaviour that will apply when the steps below are followed will be appropriate.
DETAILS: This default behaviour is that the "provider" property of the web service will be set to Java:RPC in the web service descriptor file (*.wsdd) used by Apache Axis to deploy your web service.

Assuming that your web service class is going to make use of Greenstone 3 functionality, the classpath to all of Greenstone 3's java code is already available in the Ant buildfile that will be used to expose your web services on Greenstone 3's services page.

  1. Write the Java class that will contain the methods you wish to expose as operations on Greenstone's "services" page.
    Note that I haven't tried working with constructors other than the default constructors (the ones that take no parameters).
  2. Copy the contents of the java file into a new java file and name it <someWebService> For example, this duplicate file would be called
  3. Edit <someWebService> so that
  4. Place the file <someWebService> into the folder $GSDL3HOME/resources/java, alongside the other already in here.
  5. OPTIONAL STEP: Open $GSDL3HOME/build.xml and you can add your web service name (<someWebService>SOAPServer) to the list of web services already mentioned in there. This will then be available in the command-line menu when you try to deploy a web service using Apache Ant.

B How to deploy your new web service using GS3'S ant build file

  1. Open an X-term or DOS-prompt and go into the $GSDL3HOME directory.
  2. Make sure that Greenstone 3's Tomcat server is running. If it's not running, do:
    ant start
  3. Deploy your site by typing:
    ant soap-deploy-site
    It will ask you 3 things:
    1. Type the name of the Site you wish to deploy it for. It can be any existing remote Site that you have access to, or if you wish to deploy it locally, you would type
    2. Type the name of the Greenstone 3 web service you wish to deploy. The default Greenstone 3 SOAPServer and QBRSOAPServer (for Query, Browse and Retrieve operations) are already in the list of web services that can be deployed. And because you have now added your web service class in there as well, you can type its name:
    3. Finally, give the web service a name. For instance, you can type "MyGS3WebServices" or something more descriptive of the web services you have created. Alternatively, you can choose the default web service name it will give you, which will be of the form
      It's handy to remember the name of the web services you deployed in case you wish to undeploy it (see Section C below).
  4. If all goes well, it will have deployed your web service. To check that this is indeed the case, point your web browser to the greenstone server's services page for the Site you deployed the web service for. This page will list all the web services deployed.
    For example, the http://HOST:PORT/greenstone3/services page, when deployed for the Site "localsite" if on localhost and port 8080, would be http://localhost:8080/greenstone3/services

C How to undeploy your web service from greenstone 3

  1. You need the name of the web services you deployed. If you don't remember, go to the services page for the Site you deployed it on. (http://HOST:PORT/greenstone3/services for the HOST and PORT values that apply to your deployment situation).
  2. Open an X-term or DOS prompt and go into the $GSDL3HOME folder.
  3. Type:
    It will ask you for the name of the web service you wish to undeploy. Type the name.
  4. If your web service was deployed and you typed the web service name correctly, it will now be undeployed. To check, go to http://HOST:PORT/greenstone3/services and check that your web service is no longer in the list of hosted services.