Homework 4: Modifying, Compiling, and Deploying a Simple Grid Service in Globus Toolkit 4

Based on an assignment for GT3.2 written by Jeffrey C. House with modifications by Mark Holliday and Amy Apon

Overview

            The objective of this assignment is for you to learn how to develop a simple Grid Service using the Globus Toolkit 4. This assignment will take you through the steps necessary to compile and deploy a prewritten grid service. Towards the end of the assignment, you will be required to modify the code that is given to you to help broaden your experience with developing grid services.

Introduction to Grid Services

            Grid Services are an extension of web services. Like a web service a key feature of a grid service is that there is a process running the service on some machine and there can be one or more processes running clients on some machines that can request that the service process provide the service. The machines running the client processes and the service process need not be the same machine; in other words, the grid service can be a distributed system. In fact the possible configuration can be more complicated in that there can be more than one process that is an instantiation of the service.

The above description means that a grid service, as does a web service, provides a client-server form of interaction. One way that a grid service and a web service differ is that a grid service can be either stateful or stateless, In contrast, a web service can only be stateless.  That a grid service is stateful means that the grid service can remember previous information from the last client-server interaction. When a grid service is stateless, the grid service does not retain state about an interaction with a client and thus the grid service is not aware of what happened during previous interactions with the same client (or any other client)

            Grid services can also have one-to-one or one-to-many interactions with clients. The one-to-one approach to grid services means that an individual client will have their own instance of a grid service, and more than likely, that grid service will be destroyed after the interaction with the client is complete. The one-to-many approach to grid services means that there is only one instance of the grid service and the information that service has is available to any number of clients.

This particular assignment involves a one-to-many grid service based on the example in Chapter 3 of The Globus Toolkit 4 Programmer's Tutorial by Borja Sotomayor.

In this assignment the diretory structure has been simplified and the contents of the files modified acordingly to make it easier to use.

Assignment Specifics

Step 1: Getting Started

            You should logon to cohn.cs.kent.edu. When you logon you will initially be in your home directory which is /home/yourusername. Throughout this handout you should view the string yourusername as referring to your username on cohn. The text file generated using script shows the results of the command in this step.

Now that you are logged on,  use the wget command to get the tar file above:

[yourusername@cohn ~]$ wget http://www.cs.kent.edu/~farrell/grid06/ass/gridsrv.tar
The Linux command interpreter (shell) executes what is entered on one line at the command prompt. That one line usually (and always in this assignment) has just one command. The problem is that sometimes that one command is longer than the width of the console screen or of the width of a document page. There are two solutions that the command interpreter supports. One solution is that since a line is defined as all the characters until a newline character, the shell can handle a command that is so long that it wraps around on the console to the next line as long as the user does not enter a newline character. The second solution is that the shell views a backslash character, “\”, as escaping the next character. Thus, a backslash character immediately before a newline character is not considered to be the start of a new line by the shell.

In this handout whenever a command is long it will be shown on multiple lines but with a backslash character at the end of each line except the last line. It is important when entering a command in this manner that the newline character (generated by pressing the ENTER key) be immediately after the backslash character.

You can display the contents of a directory using the ls (LiSt) command.

Next, use the tar command to create a directory named GridServices with several subdirectories and files in it:

Change to the GridServices directory. This directory and its contents are created so that you could work on this assignment. This is a fairly simple framework that is given to you so that when you write grid services, compilation and deployment will be much easier.

When you create a grid service, you must deploy them into a globus container to make the grid service available. Since all students will deploy their services into the same container it is necessary to have unique names for every service that is deployed. This assignmnet uses a script (originally written by Sam Daoud) that takes your username into account and modifies every occurrence of assignments, whether it is a folder name or contents of a java source file. The script replaces assignments with yourusernameAssignments, where yourusername is the username you used to logon to cohn. You should run the script only once and you should do so from your GridServices directory as follows:

[yourusername@cohn GridServices]$ ./nameChangeScript
When the script runs a number of messages will be displayed stating each change the script attempted to make and whether the change succeeded.

An obvious question is “What happens if you have already run the nameChangeScript and you run it again?” No damage will occur. When the script runs the second time the last few of the messages that will be displayed will say that the change failed. This is because the directory named assignments has already been changed to the name yourusernameAssignments. However, you can continue with the rest of the steps of the assignment.

Step 2: Define the Grid Service Interface using WSDL and Specify Namespace Mappings

            The first step in developing a Grid Service is defining the interface for the service. The interface is defined using the Web Services Description Language (WSDL) which specifies what operations are exposed through the Grid Service to client(s). Assuming that you are in your GridServices directory, /home/yourusername/GridServices , the WSDL for this is in 

schema/yourusernameAssignments/MathService_instance/Math.wsdl
Look at the WSDL file, using cat or more, and compare it with the file in Chapter 3. In the above WSDL, you can see that you specify the name of the service, the target namespace, and that this appears again in the xmlns:tns tag. The target namespace specifies that all operations defined in the file will be part of that namespace.

The lines 
portType name="MathPortType" 
wsdlpp:extends="wsrpw:GetResourceProperty"
names the PortType for this service and specifies that it uses the extensions to WSDL provided by the WSDL preprocessor

It is also necessary to specify how the WSDL namespaces match up with the java packages for use with the build script.  When you create additional services you just add their mappings to this file. Assuming that you are in your home directory, /home/yourusername/GridServices, the file for this is named

namespace2package.mappings

and the contents of that file is:

http\://www.globus.org/namespaces/examples/core/MathService_instance=yourusernameAssignments.stubs.MathService_instance
http\://www.globus.org/namespaces/examples/core/MathService_instance/bindings=yourusernameAssignments.stubs.MathService_instance.bindings
http\://www.globus.org/namespaces/examples/core/MathService_instance/service=yourusernameAssignments.stubs.MathService_instance.service

Step 3: Defining the grid service with Java.

The Grid Service for this assignment is a simple Math Service that can perform basic arithmetic for a client, such as addition and subtraction, and send the result back to the client. The Math Service itself is stateful, meaning that the result of any previous arithmetic operation is remembered by the service, and the previous result is used in forthcoming calculations. The second step in developing the Math Service is implementing the service in Java. This is done using two files, one that defines the qualified names or QNames that we will use to refer to the Value, the LastOp and the MathResourceProperties of the service, and one that provides the code for the service (and in this simple case for the resource also). Assuming that you are in your GridServices directory, /home/yourusername/GridServices, the Java code for the QNames and the service are both located in the 

yourusernameAssignments/services/first/impl
directory and are called MathQNames.java and MathService.java respectively. As you can see MathService has two resource properties, Value and LastOp and three methods add, subtract and getValue, that are the operations exposed to the clients. Each of these methods must throw a RemoteException because the services use Java Remote Method Invocation (RMI) behind the scenes.

Step 4: Configuring the Deployment using WSDD and JNDI

            The deployment descriptor defines how the Grid Service will be deployed. Assuming that you are in your directory, /home/yourusername/GridServices, the Deployment descriptor for the Math Service and the JNDI are both located in 

yourusernameAssignments/services/first
and are called deploy-server.wsdd and deploy-jndi-config.xml In the deployment descriptor, one section is the most important and specific to the Math Service. This section describes the Math Service. The service name is the location of where the service will be placed in the Globus container. The className specifies the class which implements the service and wsdlFile specifies to the WebServices container where the WSDL description of the service interface is found.

Step 5: Building the Math Service - Creating the GAR file with Ant

From your GridServices directory, you can build your Math Service by using the globus-build-service script. The build script takes two arguments. The first is the path to your service and the second is the path to the WSDL file for that service. To run the build script, perform the following:

[yourusername@cohn GridServices]$ ./globus-build-service.sh \
-d yourusernameAssignments/services/first/ \
-s schema/yourusernameAssignments/MathService_instance/Math.wsdl
The backslash character is because the command is on more than one line. Each backslash character must immediately precede a newline character.

            During the build process, a new directory is created in your GridServices directory that is named build.  All of your stubs and class files that were generated will be in that directory and its subdirectories. More importantly, a GAR file is created called 

yourusernameAssignments_services_MathService.gar
The GAR file is the package that contains every file that is needed to successfully deploy your Math Service into the Globus container. The files contained in the GAR file are the java class files, WSDL, compiled stubs, and the deployment descriptor. The text file generated using script shows the output of the build command.

Step 6: Compiling the Client

Make sure you are in your GridServices directory. The client code for this service can be found at 

usernameAssignments/clients/MathService_instance/Client.java
When the client is run from the command line you pass it one argument which is the URI of the service. The URI is a URL that specifies where the service resides. The location of the service is relative to the namespace the Math Service was deployed to.

To compile the java client code, first 

[yourusername@cohn GridServices]$ source $GLOBUS_LOCATION/etc/globus-devel-env.sh
to put the globus libraries in your CLASSPATH, and then from your GridServices directory do the following:

[yourusername@cohn GridServices]$ javac -classpath ./build/stubs/classes/:$CLASSPATH \
yourusernameAssignments/clients/MathService_instance/Client.java
The backslash characters are because the command is on more than one line. Each backslash character must immediately precede a newline character.

Step 7: Deploying the Math Service

To deploy the Math Service you will use globus-deploy-gar, which in turn uses a tool called ANT (Another Neat Tool). ANT (http://ant.apache.org) is a build tool somewhat like the make program. However make-like tools are shell-based while the configuration files for ANT are XML (eXtensible Manipulation Language)-based.

In our environment, only the globus user can deploy services and run containers, so to deploy the service you must become the globus. However first you must put the GAR file somewhere globus can read it. To do this copy it to /tmp. 

[yourusername@cohn GridServices]$ cp yourusernameAssignments_services_MathService.gar   /tmp

Next, become the globus user by using su: 

[yourusername@cohn GridServices]$ su - globus
You will be prompted for globus's password, which was supplied in class. Now deploy the Math Service:

[globus@cohn ~]$  globus-deploy-gar /tmp/usernameAssignments_services_first.gar
Make sure that you substitute your username in for yourusername in the above command. If the deployment is successful, you will see output similar to the following file

If there were no errors at this point, the service has been deployed. Any container that is started on this machine by any user will list your service as one of the deployed (and thus, available) services.

Step 8: Finding Which TCP Ports are in use

First you need to determine whether cohn can support running another container. A container process requires a substantial amount of main memory. At most a few containers can be run on the same machine without thrashing occurring. For example, on a machine with 512 megabytes of main memory we recommend certainly no more than four containers running and preferably less. Thus, if several users are using the same machine to complete this assignment they should coordinate to prevent overcommitment of main memory. Use the uptime command to see what the current load average is on cohn. In the example below the load average is 0.00.

[yourusername@cohn GridServices]$ uptime

[globus@cohn ~]$ uptime

If the load average is above two or three you should not start a container. The commands vmstat and ps aux can be used to monitor in more detail  the memory usage of a container process.

In the next step you will want to start a container process running. A container process listens on a TCP port when it is running. If you do not specify what port it will listen on then it will choose port 8080 by default. Often another process is using port 8080. Since only one process can be listening on a port at a time, you need to determine which ports are free before you start the container. The netstat (NETwork STATistics) command can be used 

yourusername@cohn ~]$ netstat –t –all
The –t flag and the –all flag causes the netstat command to show all the TCP ports that are currently in use.

Step 9: Start the Container for your Grid Service

Now that the client code is compiled you can start the Globus container. The Globus container contains all services that have been deployed. To start the container, you must be in the Globus Toolkit directory. This directory is specified by the GLOBUS_LOCATION environment variable and on cohn is /usr/local/globus. To start the container, do the following:

[yourusername@cohn GridServices]$ cd $GLOBUS_LOCATION
[yourusername@cohn globus]$ globus-start-container -p yourportnumber -nosec

The string yourportnumber is a placeholder for the port you determined is free from using the netstat command in the previous step. If the container command exits stating that the address is already in use, you can try using a different port number in the range from 8081 to 65535. Starting a container often takes a minute or so.

Now that the container is running, you will see your MathService listed as one of the services available. One of the lines should look similar to the following. The IP address 131.123.35.10 is the address of cohn which is the machine on which the container is running.

[54]: http://131.123.35.10:yourportnumber/wsrf/services/yourusernameAssignments/first/MathService
for examples 
[54]: http://131.123.35.10:8083/wsrf/services/farrellAssignments/first/MathService
A sample output of Steps 8 and 9 are in the file.

Note that there are quite a number of services listed. Any service that has been deployed on this machine by any user will appear in this list. A service will remain deployed until it is explicitly undeployed. How to undeploy a service is described in a Step 13 in this assignment.
Troubleshooting : The container may fail to start if :

Step 10: Run the Client

To start the client, you need to open another terminal connection to cohn. This is because the container will not return to the command prompt once it starts running. Once you logon a second time to cohn in this second shell use cd to move to your GridServices directory.

To start the client from your GridServices directory, do the following which passes the URI of the service as the argument. Note that the in the middle of the URI is the string yourportnumber . This is a placeholder that you will replace with the port number on which your container is listening. As always the string yourusername must be replaced by your username on cohn.

[yourusername@cohn GridServices]$  java -classpath ./build/stubs/classes/:$CLASSPATH \
yourusernameAssignments.clients.MathService_instance/Client \
http://127.0.0.1:yourportnumber/wsrf/services/yourusernameAssignments/first/MathService

The backslash characters are because the command is on more than one line. Each backslash character must immediately precede a newline character. The IP address 127.0.0.1 is being used since this refers to the local machine. Since your container is running on cohn, you could also use cohn’s IP address. If the client runs fine you will get this output:

Current value: 15
Current value: 10
If you run it again you should get 
Current value: 15
Current value: 10
You should always stop the container as in Step 13 after you have finished testing, since only a limited number of containers can run.

Step 11: Add Multiplication to Your Math Service

Congratulations, you have successfully compiled, deployed, and tested your first Grid Service. However, you are not finished yet. You need to modify the Math Service to support multiplication. Assuming that you are in your GridServices directory, /home/yourusername/GridServices, the file that you will need to edit is at the relative path: 

yourusernameAssignments/services/first/impl/MathService.java
In that file insert a multiply method.

Also you will need to edit the WSDL file at (assuming you are in your GridServices directory)

schema/yourusernameAssignments/MathService_instance/Math.WSDL
so that the multiply method is exposed to clients.

Also edit yourusernameAssignments/clients/MathService/Client.java (assuming you are in /home/yourusername/GridServices) and use the add, subtract, and multiply methods in any way you want, but all methods have to be used and results of each calculation should be displayed on the screen using the getValue method and System.out.println.

Once those files are edited, you can follow steps 5 through 7 for building and deploying the Math Service and compiling the Client code. Note that you will have to stop the container, as in Step 13 and restart it, in order for the revised service to be available

Step 12: Create a New Service MathModService that does Arithmetic Modulus p

On this part you are going to deploy a new service that does arithmetic modulus p, where p is a number specified by the client.

First create a new directory GridServices2 in your home directory. 

[yourusername@cohn ~]$ mkdir GridServices2
Then copy the files in your original directory to it 
[yourusername@cohn ~]$ cp -r GridServices/* GridService2
  1. Modify this new version so that it will deploy as MathModService rather than MathService.
  2. Add a new resource to the service similar to Value to hold the modulus p.
  3. Also add a new operation exposed to the user, setmod, which sets the value of this resource.
  4. Modify the add, subtratct, and multiply operations to do arithmetic modulus p, for example add(number) should give the result 
     Value = Value + number (mod p)
  5. Modify the client to test out the new service, and use the setmod, add, subtract, and multiply methods in any way you want, but all methods have to be used and results of each calculation should be displayed on the screen using the getValue method and System.out.println.

    . Note that you should use the setmod operation first to set the modulus.

Once those files are edited, you can follow steps 5 through 7 for building and deploying the Math Service and compiling the Client code. Note that you will have to stop the container again, as in Step 13 and restart it, in order for the revised service to be available

Step 13: Ending the Session

You have now completed creating and deploying a service, creating a client, and using that client to access that service. Your client program has finished running. However, you have started a globus container process. You have also deployed a service that is available within that container. Even if you logoff of cohn the service remains deployed.

In our case, we will use inelegant method of killing the container process by typing 

^C
(Control-C) in the terminal in which it is running. It should then exit with the message: 
Stopped SOAP Axis server at: http://131.123.35.10:yourportnumber/wsrf/services/
A service remains deployed after you logoff and even after the container that you started has terminated. Any new container started on that machine will list the service that you had deployed as available. The service deployed in Step 7 can be undeployed using the following command. 
[globus@cohn globus]$ globus-undeploy-gar usernameAssignments_services_first
Note that you must do this as the globus user. Sample output of this command is given in the file.

Step 14: Document your Work

Leave the programs in your GridServices and GridServices2 directories on cohn. Turn in the following:

Acknowledgements

This assignment is derived from
“Classroom Exercises for Grid Services” by A. Apon, J. Mache, Y. Yara, and K. Landrus, Proc. 5th Int. Conference on Linux Clusters: The HPC Revolution, May 2004.

 

Appendix A: Additional Resources

            In addition to this assignment text, there are many good resources on the internet to help ease the pain of writing Grid Services for the Globus Toolkit 4.

The Globus Alliance:

http://www.globus.org/

The Globus Toolkit 4 Programmer's Tutorial:

http://gdp.globus.org/gt4-tutorial/

The Apache Web Services Project

http://ws.apache.org/

Apache AXIS

http://ws.apache.org/axis/

 

Apache ANT:

http://ant.apache.org/

In the command above recall that the yourportnumber must be replaced by the port number on which you have the container listening.