Globus Toolkit 3.0 - Last Updated 06/26/2003
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.
The following steps are involved in writing a Grid service:
Step 1. Generate Grid service code
Step 2. Optionally add service data to the service
Step 3. Create a Grid service archive (GAR)
Step 4. Deploy the Service
The complete source code for this example is available in the guide directory in your framework distribution.
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.
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
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.
<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
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.