Grid Service Development Tools Guide

Globus Toolkit 3.0 - Last Updated 06/26/2003

Contents

Introduction

Developing a Service

Known Issues

Introduction

This document outlines ant commands that grid service developers may use in order to create, add service data to, and archive grid services. All commands outlined below are provided as targets in build-tools.xml, which is part of the GT3 distributtion.

Basic knowledge of Java and Ant ( http://jakarta.apache.org/ant ) is assumed in this guide. We also assume that you are familiar with the basic OGSA environment described in the User's Guide.

Developing a Service

The following steps are involved in writing a Grid service:

The complete source code for this example is available in the guide directory in your framework distribution.

Step 1. Generate Grid Service Code

There are two main approaches to providing a source for your service that is to be exposed to remote clients.  

Bottom-Up Approach

If you have existing java code that you would like to expose as a Grid service, it must be compiled and archived into a JAR file. This JAR file is run through the createBottomUpGridService tool to automatically generate the stubs, the service locators, the deployment descriptor fragment, and an operation provider that delegates its calls into your existing Java code.

<ant antfile="${build.tools}" target="createBottomUpGridService">
  <property name="verbose" value="true"/>
  <property name="outputDir" value="./bottomUpFiles"/>
  <property name="bottomUp.sourceJar" value="${ogsa.root}/guide/lib/counter.jar"/>
  <property name="bottomUp.classOfPortType" value="org.globus.ogsa.guide.impl..LegacyCounterImpl"/>
</ant>

Other properties that may be used are:
    <property name="help" value="false" /> - can be set to true or false, outputs a usage statement
    <property name="persistent" value="false" /> - can be set to true or false, true would generate a persistent grid service
    <property name="bottomUp.handleResolver" value="false" /> - can be set to true or false, generated service is a handle resolver
    <property name="bottomUp.notificationSource" value="false" /> - can be set to true or false, generated service is a notification source
    <property name="bottomUp.notificationSink" value="false" /> - can be set to true or false, generated service is a notification sink
    <property name="bottomUp.factory" value="false" /> - can be set to true or false, generated service is a factory
    <property name="bottomUp.serviceGroup" value="false" /> - can be set to true or false, generated service is a service group
    <property name="bottomUp.serviceGroupRegistration" value="false" /> - can be set to true or false, generated service is a service group registration
    <property name="bottomUp.all" value="false" /> - can be set to true or false, if true, methods will be exposed in the grid service from classes that classOfPortType inherits from
    <property name="bottomUp.methodList value=""/> - a comma delimited string that indicates what methods to expose in the grid service
    <property name="bottomUp.excludeList value=""/> - comma delimited string that indicates what methds to exclude from the grid service
    <property name="bottomUp.stopClassesList value=""/> - comma delimited string that indicates the class at which to stop the inheritance search if bottomUp.all is set to true

See guide/build-tools-usage.xml for the full example.

Note that the ${build.tools} property has to point to the location of build-tools.xml shipped with the framework. 

This approach should be used with care because some complex java types do not map very well into WSDL and could thus impair the interoperability of your service.

Example:

From the guide directory run ant -f build-tools-usage.xml createBottomUpGridService

This command results in all files necessary for deployment of the Grid service being generated in the guide/bottomUpFiles directory. In particular note the file org/globus/ogsa/impl/LegacyCounterImplProvider.java. This class  hooks the legacy implementation into the Grid service container dispatching framework, and delegates the appropriate operations to the existing implementation using the OperationProvider approach described in the Programmers Guide.

Top-Down Approach

A Grid service may also be created using a GWSDL interface. When providing a GWSDL interface you only need to provide the abstract definition of the service including the types, message, and portType parts of WSDL. The binding and service part, the stubs, the service locators, the deployment descriptor fragment, an operation provider, and an implementation class will be generated for you by our tools. After the Grid service code is generated, you may add the appropriate logic to the generated implementation class. The generated operation provider will delegate its calls into this class.

<ant antfile="${build.tools}" target="createTopDownGridService">
  <property name="verbose" value="true"/>
  <property name="outputDir" value="./topDownFiles"/>
  <property name="topDown.gwsdl-uri" value="${build.dir}/schema/counter_port_type.gwsdl"/>
</ant>

Other properties that may be used are:
    <property name="help" value="false" /> - can be set to true or false, outputs a usage statement
    <property name="persistent" value="false" /> - can be set to true or false, true would generate a persistent grid service
    <property name="topDown.all" value="false"/> - can be set to true or false, true would generate code for all elements, even unreferenced ones
    <property name="namespaceFile" value="" /> - a string indicating the name of a file which contains custom namespace to package mappings 
    <property name="topdown.namespaceOverride" value="" /> - a string containing a namespace to package mapping in namespace=package format 
    <property name="topdown.globalNamespaceOverride" value="" /> - a string containing a package name that overrides all namespace to package mappings

See guide/build-tools-usage.xml for the full example.

Note that the ${build.tools} property has to point to the location of build-tools.xml shipped with the framework.

Example:

From the guide directory run ant -f build-tools-usage.xml createTopDownGridService

This command results in all files necessary for deployment of the Grid service being generated in the guide/topDownFiles directory. In particular note the file org\globus\ogsa\guide\Counter\wsdl\Counter.java. This is the implementation skeleton that you have to complete with a meaningful implementation.

Batch Service Creation Approach

A third approach to creating grid services code is the batch service creation approach. This allows you to create multiple grid services from an XML description. The XML description must adhere to the CreateGridServices.xsd schema that is shipped with the GT3 distribution. The following is an example of such an XML description.

<createGridServices>
 <createGridServices>
  <gridService help="false" 
               outputDirectory="./bottomUpFiles" 
               persistent="false" 
               verbose="true">
    <bottomUp excludeMethods=""
              factory="false" 
              handleResolver="false" 
              includeMethods="" 
              notificationSink="false" 
              notificationSource="false" 
              serviceGroup="false" 
              serviceGroupRegistration="false" 
              sourceClass="org.globus.ogsa.guide.impl.LegacyCounterImpl" 
              stopClasses="" 
              useInheritedClasses="false"/>
  </gridService>
  <gridService help="false" 
               outputDirectory="./topDownFiles" 
               persistent="false" 
               verbose="true">
  <topDown generateAllElements="false" 
           sourceGWSDL="./build/schema/guide/Counter/counter_port_type.gwsdl"/>
  </gridService>
</createGridServices>

See guide/xml/CreateGridServices.xml for the full example.

The ant task used to create multiple grid services is createGridServicesFromFile.  

<ant antfile="${build.tools}" target="createGridServicesFromFile">
  <property name="verbose" value="true"/>
  <property name="file.xml" value="${ogsa.root}/guide/xml/CreateGridServices.xml"/>
</ant>

As a special note, all JAR files that contain the source for bottom-up services that are to be created by the batch processor must be on the classpath prior to running the createGridServicesFromFile target  It is also worth noting here that prior to running the gar target, these JAR files must also be copied to the correct output directory that the tooling creates for those bottom-up services that are created by the batch processor.

See guide/build-tools-usage.xml for the full example.

Note that the ${build.tools} property has to point to the location of build-tools.xml shipped with the framework.

Example:

From the guide directory run ant -f build-tools-usage.xml createGridServiceFromFile

This command will create the exact same files we created in the two examples above.

Step 2. Optionally Add Service Data to the Service

We also provide an addServiceData target, which adds service data doclets to the generated operation provider.  A removeServiceData target is also available to remove any doclets created in error. These doclets are processed upon running the gar target, which depends on other targets that will create service data annotations and the appropriate wsdl to describe the service data.

<ant antfile="${build.tools}" target="addServiceData">
  <property name="verbose" value="true"/>
  <property name="outputDir" value="./bottomUpFiles"/>
  <property name="serviceData.class" value="org.globus.ogsa.guide.impl.LegacyCounterImpl"/>
  <property name="serviceData.name" value="currentValue"/>
  <property name="serviceData.method" value="getValue"/>
</ant>

<ant antfile="${build.tools}" target="removeServiceData">
  <property name="verbose" value="true"/>
  <property name="outputDir" value="./bottomUpFiles"/>
  <property name="serviceData.class" value="org.globus.ogsa.guide.impl.LegacyCounterImpl"/>
  <property name="serviceData.name" value="currentValue"/>
  <property name="serviceData.method" value="getValue"/>
</ant>

See guide/build-tools-usage.xml for the full example.  

Note that the ${build.tools} property has to point to the location of build-tools.xml shipped with the framework.

Example:

Make sure you have completed the topDown approach in step 1 above either using the basic or the batch approach. 
Then from the guide directory run ant -f build-tools-usage.xml addServiceData

This command will add a service data entry to the Counter service called currentValue and tie it to the getValue implementation in our legacy counter implementation example.

Batch Service Data Creation Approach

As with grid service creation, there is also a tool which takes an XML description and adds service data doclets to generated grid service code. This XML description must adhere to the BatchSD.xsd schema that is shipped with the GT3 distribution. The following is an example of such an XML description:

<batchServiceData>
  <serviceData class="org.globus.ogsa.guide.impl.LegacyCounterImpl">
    <verbose/>
    <outputDirectory dir="./bottomUpFiles"/>
    <serviceDataName sdname="currentValue"/>
    <decorateMethod method="getValue"/>
  </serviceData>
</batchServiceData>

The command used to create multiple service data doclets is createServiceDataFromFile.

<ant antfile="${build.tools}" target="createServiceDataFromFile" >
  <property name="verbose" value="true"/>
  <property name="batchSD.xml" value="${ogsa.root}/guide/xml/BatchSD.xml"/>
</ant>

See guide/build-tools-usage.xml for the full example.

Note that the ${build.tools} property has to point to the location of build-tools.xml shipped with the framework.

Example:

Make sure you have completed the topDown approach in step 1 above either using the basic or the batch approach. 
Then from the guide directory run ant -f build-tools-usage.xml createServiceDataFromFile

Step 3. Create a Grid Service Archive (GAR)

A gar target is available to archive all  generated components into an archive file that serves as the unit of deployment.  The gar target depends on several other targets that perform the following steps.

  1. generateServiceDataAnnotation - goes through all subdirectories of the tooling output directory and creates service data annotions for any service data doclet found
  2. compile - compiles all Java parts found in all subdirectories of the tooling output directory
  3. jar - creates a JAR file of all class files and -sdAnnotation files found in all subdirectories of the tooling output directory
  4. generateServiceDataDescriptions - goes through each -sdAnnotation file from the JAR created in the previous step and adds the appropriate service data descriptions to the appropriate wsdl files in the tooling output directory
  5. normalizeSchema - goes through all WSDL in the subdirectories of the tooling output directory and changes any imports that point to other WSDL files in the deployment environment to relative paths in the deployment environment
  6. gar - all generated parts in the output directory are archived into a GAR file
<ant antfile="${build.tools}" target="gar">
  <property name="outputDir" value="./bottomUpFiles"/>
  <property name="jar.name" value="bottomUpCounterService.jar"/>
  <property name="gar.name" value="bottomUpCounterService.gar"/>
</ant>
...
<ant antfile="${build.tools}" target="gar">
  <property name="outputDir" value="./topDownFiles"/>
  <property name="jar.name" value="topDownCounterService.jar"/>
  <property name="gar.name" value="topDownCounterService.gar"/>
</ant>

See guide/build-tools-usage.xml for the full example.

Note that the ${build.tools} property has to point to the location of build-tools.xml shipped with the framework.

Example:

Make sure that you have generated all the files for both the bottomUp and the topDown approaches described above.
Then from the guide directory run ant -f build-tools-usage.xml bottomUpGar topDownGar

Step 4. Deploy the Service

Use the deploy target from build.xml to deploy the generated gar package into a Grid service hosting environment.
In the distribution directory of your ogsa installation make the following command line call:   ant deploy –Dgar.name=<path to gar created in previous step>

Example:

Make sure you have created both the topDown and the bottomUp gar.
Then run ant -f build-tools-usage.xml deploy

You are now ready to try out the generated services in the ServiceBrowser gui described in the User's Guide.
Note that to redo all of the setps describe below in one command you can run:
ant -f build-tools-usage.xml clean all

To undeploy the gars run:
ant -f build-tools-usage.xml undeploy

You can now test your generated services in the ServiceBrowser GUI. Make sure that the CounterPortType is not mapped in the client-gui-config.xml file and that you check the box for the dynamic gui.

Known Issues

If you use polymorphic interfaces on the server side you currently have to manually add typemappings to the deployment descriptor for the values to get deserialized correctly