Title:	GT4 Introductory Practical
Subtitle:	How to Build a Java Service Using GT4
Tutors:	Rachana Ananthakrishnan, Charles Bacon, Lisa Childers
Authors:	Globus Alliance Staff

Table of Contents

GT4 Introductory Practical:
How to build a Java service using GT4

Document Conventions

Throughout this tutorial, narrative material appears in green. In the live version of the tutorial such information is delivered by an instructor.
For the hands-on exercises:

Instructions for the hands-on exercises are written in black
The first several exercises requires that you issue commands from two different command windows running on your machine:

One window will be used to run Globus Toolkit software and will be referred to as the GT window in these notes. Commands typed in the GT window will be bounded by a box of this color.

The second window will be used to modify and execute student code and will be referred to as the Exercise window. Exercise commands will be bounded by a box of this color.

Later in the tutorial a third command window will be required.

Red command text can be cut and pasted directly into your command window
Black command text indicates that intelligent replacement is required

You might consider coloring the backgrounds of your Terminal/Command/Xterm windows to match the colors used in the tutorial. Though not necessary, you may find this helpful in identifying windows.

Brief Introduction to GT4

The Globus Toolkit (GT) is a collection of development tools, libraries, clients and services for building Grid infrastructure. The figure above shows a high-level view of the major components in the current release (version 4). GT4 is the result of over a decade of development. The newer components in the toolkit reflect a focus on service-oriented architectures based on Web Services (WS) standards. Because of its pervasiveness as an implementation language for Web services, many of the newer GT components are written in Java. This tutorial will show how to build a custom Java web service using GT4.

More introductory information on GT4

Hands-On Exercise Overview

This tutorial is organized around a series of exercises in which increasing functionality is added to a skeletal service. The exercises are designed to demonstrate common Grid-based interactions and patterns using GT4. The demonstration code has trivial functionality in order to maintain focus on the mechanics of service writing. Each exercise includes:

A discussion of the concepts behind the exercise
A discussion of implementation details
Hands-on exercise steps

In order to avoid wasting time on syntactic errors, each exercise consists of uncommenting code fragments. A word of warning: it is possible to complete all the exercises by blindly uncommenting and commenting code. However, in order to get the most from this tutorial you should take time to read and understand your edits.

Exercise 1: Deploy a Service

Concepts

The sample code we'll be modifying during the course of this tutorial is a simple web service written in Java. The service is called StickyNote; it stores and returns a text message. The purpose of this first exercise is to build and deploy StickyNote using GT4.

More information about deploying StickyNote

Implementation Details

As part of this exercise we'll install the GT4 binary, and do a test build of the exercise code. We'll then verify that our environment is set up properly by running a couple of clients.

Further reading on development tools needed for building GT4-based services

Exercises

If you haven't yet done so, now is the time to:

Open a command window for running the Globus container (the GT window)

Open a second window for building, modify and executing demonstration code (the Exercise window)

Ok! Time to begin!

1.1 Untar the gt install tarball in the GT window:

Install the Globus software as follows:
$ mkdir /gt4/$USER/
$ mkdir /gt4/$USER/intro/
$ cd /gt4/$USER/intro/
$ wget http://www.gs.unina.it/~gt4/introductory/globus-4.0.2-java-norft.tar.gz
$ tar xzf globus-4.0.2-java-norft.tar.gz

1.2 Set environment variables in the GT window:

$ cd globus-4.0.2-java-norft
$ export GLOBUS_LOCATION=$PWD
$ echo $GLOBUS_LOCATION
/gt4/childers/intro/globus-4.0.2-java-norft

1.3 Untar the tutorial tarball in the Exercise window:

Install the exercise software as follows:
$ cd /gt4/$USER/intro/
$ wget http://www.gs.unina.it/~gt4/introductory/exercise-install.tar.gz
$ tar xzf exercise-install.tar.gz
$ cd exercise-install/stickynote/source

1.4 Set environment variables in the Exercise window:

$ export GLOBUS_LOCATION=[use the value that was echoed earlier in the GT window, not $PWD]

1.5 Build and deploy the tutorial code in the Exercise window:

$ ant deploy
Buildfile: build.xml

init:

bindings:

[... many more build messages...]

BUILD SUCCESSFUL
Total time: 27 seconds

1.6 Verify that the show-note client built successfully by checking that it exists:

$ ls $GLOBUS_LOCATION/bin/show-note
/gt4/childers/intro/globus-4.0.2-java-norft/bin/show-note

If you get an error, see the Exercise 1 troubleshooting section.

1.7 Start a web service container without security in the GT window:

$ bin/globus-start-container -nosec
Starting SOAP server at: http://192.168.123.100:8080/wsrf/services/
With the following services:

[1]: http://192.168.123.100:8080/wsrf/services/InMemoryServiceGroupEntry
[2]: http://192.168.123.100:8080/wsrf/services/TriggerFactoryService
[3]: http://192.168.123.100:8080/wsrf/services/IndexFactoryService
[4]: http://192.168.123.100:8080/wsrf/services/Version
[5]: http://192.168.123.100:8080/wsrf/services/IndexService
[6]: http://192.168.123.100:8080/wsrf/services/NotificationConsumerService
[7]: http://192.168.123.100:8080/wsrf/services/DefaultTriggerServiceEntry
[8]: http://192.168.123.100:8080/wsrf/services/TriggerServiceEntry
[9]: http://192.168.123.100:8080/wsrf/services/IndexServiceEntry
[10]: http://192.168.123.100:8080/wsrf/services/StickyNoteService
[11]: http://192.168.123.100:8080/wsrf/services/AdminService
[12]: http://192.168.123.100:8080/wsrf/services/DefaultIndexService
[13]: http://192.168.123.100:8080/wsrf/services/DefaultIndexServiceEntry
[14]: http://192.168.123.100:8080/wsrf/services/DefaultTriggerService
[15]: http://192.168.123.100:8080/wsrf/services/ShutdownService
[16]: http://192.168.123.100:8080/wsrf/services/ContainerRegistryService
[17]: http://192.168.123.100:8080/wsrf/services/TriggerService
[18]: http://192.168.123.100:8080/wsrf/services/gsi/AuthenticationService
[19]: http://192.168.123.100:8080/wsrf/services/InMemoryServiceGroupFactory
[20]: http://192.168.123.100:8080/wsrf/services/InMemoryServiceGroup
[21]: http://192.168.123.100:8080/wsrf/services/ContainerRegistryEntryService
[22]: http://192.168.123.100:8080/wsrf/services/SubscriptionManagerService

Control will not return to the prompt. This container will stay running until you exit it with Control-C. If you need to start up the container on an alternate port, use the "-p" command-line argument (e.g., "bin\globus-start-container -nosec -p 8888" will cause the container to listen on port 8888)

1.8 In the Exercise window, run the show-note client against your StickyNote service:

$ $GLOBUS_LOCATION/bin/show-note -s http://localhost:8080/wsrf/services/StickyNoteService
<ns1:noteContent xmlns:ns1="http://tutorial.globus.org/stickynote">hello.</ns1:noteContent>

In the GT window, you should see a message appear like the following:

2005-01-24 12:48:54,668 INFO stickynote.SingleNoteHome [Thread-2,findSingleton:29] Creating a single StickyNote.

This is just a debugging message printed by your service. See if you can find where in the code this message came from.

1.9 Write a single word (no embedded spaces) on the note from the Exercise window:

$ $GLOBUS_LOCATION/bin/write-note -s http://localhost:8080/wsrf/services/StickyNoteService cheese
Message written.

$ $GLOBUS_LOCATION/bin/show-note -s http://localhost:8080/wsrf/services/StickyNoteService
<ns1:noteContent xmlns:ns1="http://tutorial.globus.org/stickynote">cheese</ns1:noteContent>

Troubleshooting for exercise 1:

ant deploy failures

If you get an error during ant deploy like:
BUILD FAILED
file:/home/bacon/tmp/playground/java/stickynote/source/build.xml:62: /home/bacon/tmp/install/share/schema not found.

Check to make sure that GLOBUS_LOCATION is set correctly, and that $GLOBUS_LOCATION/share/schema exists.
If you get an error during ant deploy like:
Error: JAVA_HOME is not defined correctly.
We cannot execute java

Make sure you have Java installed, that the javac command is on your PATH, and that JAVA_HOME is set to the directory where Java is installed.
If you get an error during ant deploy like:
Warning: JAVA_HOME environment variable is not set (or not exported).
If build fails because sun.* classes could not be found
you will need to set the JAVA_HOME environment variable
to the installation directory of java.

Make sure you have JAVA_HOME set to the directory where JAVA is installed on your machine.

globus-start-container failures

If you get an error during globus-start-container like the following:
Error: GLOBUS_LOCATION invalid or not set:

Your GLOBUS_LOCATION is either not set, or set to an incorrect directory. Run echo $GLOBUS_LOCATION to see what the value is set to. If necessary, correct it to the same location you had set when you ran ant deploy. Remember, you have to have this value set in both windows you're using.
If you get an error during globus-start-container like the following:
Failed to start container: Container failed to initialize [Caused by: Secure container requires valid credentials]

Remember to include the "-nosec" option when starting the container.
If you get an error during globus-start-container like the following:
Failed to start container: Container failed to initialize [Caused by: Address in use]

You already have a server running on the same port as the container is trying to use. Make sure to either stop that server or start the container on some other port using the -p option.
If you get an error during globus-start-container like the following:
Failed to obtain a list of services from
'http://140.221.57.104:8080/wsrf/services/ContainerRegistryService' service: ;
nested exception is: java.net.ConnectException: Connection timed out

Then your machine probably has a name assigned to it that does not correspond to the IP address you have during this tutorial. Find out your current IP address, and add a line to
$GLOBUS_LOCATION/etc/globus_wsrf_core/server-config.wsdd under the <globalConfiguration> section:
<parameter name="logicalHost" value="xxx.xxx.xxx.xxx"/>

Here's an example of the file with that parameter set:

<globalConfiguration>
    <parameter name="sendXsiTypes" value="true"/>
    <parameter name="logicalHost" value="192.168.123.104"/>

Exercise 1 complete!

- table of contents -