| 1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|---|
| 2 |
|
|---|
| 3 | <html>
|
|---|
| 4 | <head>
|
|---|
| 5 | <title>How to expose custom Greenstone 3 web services on GS3's server</title>
|
|---|
| 6 | </head>
|
|---|
| 7 | <body>
|
|---|
| 8 | <a href="index.html">Back to index page</a>
|
|---|
| 9 |
|
|---|
| 10 | <h1>How to expose custom Greenstone 3 web services on GS3's server</h1>
|
|---|
| 11 |
|
|---|
| 12 | What you need:
|
|---|
| 13 | <ul>
|
|---|
| 14 | <li>Java JDK installed</li>
|
|---|
| 15 | <li>Greenstone 3</li>
|
|---|
| 16 | </ul>
|
|---|
| 17 |
|
|---|
| 18 | In this document,
|
|---|
| 19 | <ul>
|
|---|
| 20 | <li>$GSDL3HOME refers to the full path to your Greenstone 3 installation.</li>
|
|---|
| 21 | <li>GS3 may be used as a shorthand to refer to Greenstone 3.</li>
|
|---|
| 22 | </ul>
|
|---|
| 23 |
|
|---|
| 24 | <h2>Sections</h2>
|
|---|
| 25 | <ul>
|
|---|
| 26 | <li><a href="#A">A Create your web service Java class</a></li>
|
|---|
| 27 | <li><a href="#B">B How to deploy your new web service using GS3'S ant build file</a></li>
|
|---|
| 28 | <li><a href="#C">C How to undeploy your web service from greenstone 3</a></li>
|
|---|
| 29 | </ul>
|
|---|
| 30 |
|
|---|
| 31 |
|
|---|
| 32 | <h2><a name="A">A Create your web service Java class</a></h2>
|
|---|
| 33 | In the steps below, I am assuming that your web service class will be passing either
|
|---|
| 34 | <ul>
|
|---|
| 35 | <li>simple data types: strings, ints, floats, characters, boolean, arrays of simple data types, etc., or </li>
|
|---|
| 36 | <li>Java Collection data types: HashMap, Sets, Lists of simple data types, for which Apache Axis--which comes with Greenstone 3--already provides web service support.</li>
|
|---|
| 37 | </ul>
|
|---|
| 38 | If this is indeed the case, the default behaviour that will apply when the steps below are followed will be appropriate.<br />
|
|---|
| 39 | <b>DETAILS:</b> 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.
|
|---|
| 40 |
|
|---|
| 41 | <p>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.</p>
|
|---|
| 42 |
|
|---|
| 43 | <ol>
|
|---|
| 44 | <li>Write the Java class that will contain the methods you wish to expose as operations on Greenstone's "services" page.<br />
|
|---|
| 45 | Note that I haven't tried working with constructors other than the default constructors (the ones that take no parameters).</li>
|
|---|
| 46 | <li>Copy the contents of the java file into a new java file and name it <someWebService>SOAPServer.java.in. For example, this duplicate file would be called MyServicesSOAPServer.java.in</li>
|
|---|
| 47 | <li>Edit <someWebService>SOAPServer.java.in so that
|
|---|
| 48 | <ul>
|
|---|
| 49 | <li>its class name is <someWebService>SOAPServer@sitename@ </li>
|
|---|
| 50 | <li>its constructor is similarly called <someWebService>SOAPServer@sitename@</li>
|
|---|
| 51 | <li>Any other explicit references in the file to the class name must similarly be renamed to <someWebService>SOAPServer@sitename@. For instance, a Logger object for the class or static references to the class must now refer to <someWebService>SOAPServer@sitename@.</li>
|
|---|
| 52 | </ul>
|
|---|
| 53 | </li>
|
|---|
| 54 | <li>Place the file <someWebService>SOAPServer.java.in into the folder $GSDL3HOME/resources/java, alongside the other <webservice>SOAPServer.java.in already in here.</li>
|
|---|
| 55 | <li>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.</li>
|
|---|
| 56 | </ol>
|
|---|
| 57 |
|
|---|
| 58 | <h2><a name="B">B How to deploy your new web service using GS3'S ant build file</a></h2>
|
|---|
| 59 | <ol>
|
|---|
| 60 | <li>Open an X-term or DOS-prompt and go into the $GSDL3HOME directory.</li>
|
|---|
| 61 | <li>Make sure that Greenstone 3's Tomcat server is running. If it's not running, do:
|
|---|
| 62 | <pre>ant start</pre>
|
|---|
| 63 | </li>
|
|---|
| 64 | <li>Deploy your site by typing:
|
|---|
| 65 | <pre>ant soap-deploy-site</pre>
|
|---|
| 66 | It will ask you 3 things:
|
|---|
| 67 | <ol style="list-style-type:lower-alpha">
|
|---|
| 68 | <li>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
|
|---|
| 69 | <pre>localsite</pre>
|
|---|
| 70 | </li>
|
|---|
| 71 | <li>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:
|
|---|
| 72 | <pre><someWebService>SOAPServer</pre>
|
|---|
| 73 | </li>
|
|---|
| 74 | <li>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 <pre><someWebService>SOAPServer<NameOftheSiteYouDeployedItFor></pre>
|
|---|
| 75 | It's handy to remember the name of the web services you deployed in case you wish to undeploy it (see Section C below).
|
|---|
| 76 | </li>
|
|---|
| 77 | </ol>
|
|---|
| 78 | </li>
|
|---|
| 79 | <li>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 <b>services</b> page for the Site you deployed the web service for. This page will list all the web services deployed.<br />
|
|---|
| 80 | 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
|
|---|
| 81 | </li>
|
|---|
| 82 | </ol>
|
|---|
| 83 |
|
|---|
| 84 | <h2><a name="C">C How to undeploy your web service from greenstone 3</a></h2>
|
|---|
| 85 | <ol>
|
|---|
| 86 | <li>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).
|
|---|
| 87 | </li>
|
|---|
| 88 | <li>Open an X-term or DOS prompt and go into the $GSDL3HOME folder.</li>
|
|---|
| 89 | <li>Type:
|
|---|
| 90 | <pre>soap-undeploy-site</pre>
|
|---|
| 91 | It will ask you for the name of the web service you wish to undeploy. Type the name.</li>
|
|---|
| 92 | <li>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.
|
|---|
| 93 | </li>
|
|---|
| 94 | </ol>
|
|---|
| 95 |
|
|---|
| 96 | </body>
|
|---|
| 97 | </html> |
|---|
