AstroGrid echo service

[The package containing this README] is the source code for [version 1 of] AstroGrid's "echo" grid-service, which is the pilot service in our trial grid. The service provides a single operation, called "echo", that returns its argument to the caller with "Echo:" prepended.

The service built from this package is a web service; it communicates using SOAP over HTTP. It is also a grid service according to the GGF definition. This means (a) that the GridService port is present in the service and (b) that instances of the service are created dynamically by calls to a factory service. The code for the factory is part of this package.

Supporting software

This package is designed to work with library code, in Java and WSDL, from the third release of the OGSA Technology Preview (OGSA-TP-3). The package is not compatible with previous releases of OGSA-TP. You need only the binary release of OGSA-TP-3 to run the echo service.

You do not need Ant. In the current version, the echo service has an old-fashioned makefile.

The echo service uses Apache Axis, but axis is included in OGSA-TP-3. You do not need to install Axis separately.

You do not need to install Jakarta-Tomcat at all. The HTTP server that will put the echo service on-line is included in the OGSA-TP-3 release.

Installation

This is a source-code release. You need to build the source to make a jar file and then install both the jar and some WSDL files into the OGSA-TP-3 directory tree. Detailed instructions follow.

First, install OGSA-TP-3; you can download it from http://www.globus.org/ogsa. See the documents in the OGSA-TP release for details of installation. Note that you don't need to build OGSA-TP from source and all the inbstructions concerned with putting OGSA in Tomcat are irrelevant.

Having installed OGSA-TP-3, define the environment variable OGSA_HOME to point to the top directory in the OGSA tree (the one with bin and lib as sub-directories). If you miss out this step, then the installation step of the build (below) will fail.

Put all the jar files in ${OGSA_HOME}/lib on your CLASSPATH. You need this CLASSPATH both to build the package and to run the server.

Change directory to the diretcory where you unpacked the echo package.

Build and install the echo package. The simple way to do this is

   make all

which will build the code and install it in OGSA-TP-3. You can also do the intermediate steps of the build explicitly, to see what is going on.

   make gensource

generates the web-service interface code from the WDSL files in the package. These WSDL files import other WSDL files that are standard for OGSA: the imported files are taken from a web server at Cambridge. The generated code appears in the directory org/astrogrid/ogsa/echo. Code is also generated in org/gridforum and its subdirectories, but this code is already in the jar files of the OGSA-TP-3 installation; the regenerated code is not used in the build.

   make compile

compiles both the auto-generated code and the hand-written code in the build directory. The class files for all the code go into org/astrogrid/ogsa/echo.

   make jar

collects the class files from org/astrogrid/ogsa/echo into a jar file in the build directory.

   make install

copies the jar file and the WSDL files into the OGSA-TP-3 installation (look at makefile for details of locations).

   make distclean 

removes all built files from the build directory. This includes all the files needed for the installation and the entire directory tree starting at org. Nothing in or below the build directory is needed to run the service once the built files are installed in OGSA-TP.

Finally, you need to edit a configuration file in OGSA-TP-3 to tell OGSA that it has a new service. Edit ${OGSA_HOME}/server-config.wsdd

and add these lines after the last element.

 <service name="astrogrid/echo/basic/EchoFactoryService" provider="Handler" style="wrapped">
  <parameter name="allowedMethods" value="*"/>
  <parameter name="className" value="org.astrogrid.ogsa.echo.EchoFactoryImpl"/>
  <parameter name="persistent" value="true"/>
  <parameter name="schemaPath" value="schema/core/factory/factory_service.wsdl"/>
  <parameter name="instanceSchemaPath" value="schema/astrogrid/echo/echo_service.wsdl"/>
  <parameter name="handlerClass" value="org.globus.ogsa.handlers.RPCURIProvider"/>
 </service>

Installation checklist

1. Install OGSA-TP-3. 2. Define OGSA_HOME. 3. Put all jar files in ${OGSA_HOME}/lib on your CLASSPATH. 4. cd 5. make all OR 5a. make gensource 5b. make compile 5c. make jar 5d. make install 5e. make distclean 6. Edit server-config.wsdd

Running the server

First, make sure that all the jar files in ${OGSA_HOME}/lib are in your CLASSPATH. Now change directory to $OGSA_HOME. (You will get class-not-found errors if you try to run the server from any other directory.)

To run the server containing the echo service, enter

  java org.globus.ogsa.server.ServiceContainer 8090 &

(i.e. run the ServiceContainer^? class from OGSA through the Java interpreter). The number 8090 is the IP port-number on which the server listens. You can pick any port-number you like if 8090 isn't suitable. If this operation works, you will gets some progress messages, then a pause of around 30 seconds, then several screens of XML. The XML is actually Web Services Inspection Language (WSIL) and it's a listing of the grid services that the new server is running. If the server doesn't work, you'll get an unhandled exception with a stack dump.

If you have failures when running the code, the most likely problem is with your CLASSPATH. You should also check that you are in $OGSA_HOME when starting the server.

Running the clients

Clients talk to your echo service in two stages. First, a client has to invoke EchoFactory^? to create an instance of the echo service. Second, the client invokes the echo operation on the instance of the echo service.

Invoke the factory like this:

  java org.globus.ogsa.impl.core.factory.client.CreateService \
  http://my.host:8090/ogsa/services/astrogrid/echo/basic/EchoFactoryService \
  echo1

but replace "my.host:8090" with the name and port-number of your server. Note that this runs a client that is part of the OGSA-TP-3 release; it's not running any code specific to the echo service. In the URL, /ogsa.services is common to all services in the server. The part from /astrogrid/echo distinguishes the particular service. The name of the echo-service instance is the "echo1" parameter; you can call your instance whatever you like. If this operation succeeds, it will print several pages of XML. This XML is WSDL: it's the formal description of the created service-instance.

Invoke the instance like this:

 java org.astrogrid.ogsa.echo.TestEcho  \
 ping \
 http://my.host:8090/ogsa/services/astrogrid/echo/basic/EchoFactoryService/echo1

replacing my.host:8090 with the name and port-number of your server. The class for the client programme is specific to the echo service and is included in ag-ogsa-echo.jar which should be in ${OGSA_HOME}/lib by now.

Note that the URL of the service-instance is the URL of its factory followed by the name of the instance. If this works, you will get

  - Logging is working
  Echo: ping

where the first line is a wart that may be removed in later versions; the second line is the intended result.

If you have failures when running the code, the most likely problem is with your CLASSPATH.

Test-run checklist

1. Define OGSA_HOME. 2. Put all jar files in ${OGSA_HOME}/lib on your CLASSPATH. 3. cd $OGSA_HOME. 4. Start the server. 5. Create an instance of echo. 6. Invoke echo on the instance.

-- GuyRixon - 25 Sep 2002