This page describes a sample grid service used as an example in an IVOA tutorial given on 12th October 2003 as an adjunct to ADASS 2003.

What are "Grid Services"?

Grid Services are web services with special arrangements to remember and manage per-user state. "State" means any results of operations on the web service that persist between operations; e.g. files of query results cached by the service. "Per-user" means state associated with an individual's session or work-flow as distinct from state seen by all users of the service. A web service operating a bulletin board has state, since operations by users change the content of the board, but this state is shared: all users see the same content. A web-service providing a private diary to users has per-user state in that each user sees his or her own diary entries. This latter service could be implemented using grid services.

Not all web services maintaining per-user state are grid services. True grid services conform to the Open Grid services Interface specifiction (OGSI) which defines the WSDL port-types that manage the state.

OGSI services distinguish the state for different users by means of service instances. To use a grid service, a user calls a creation operation on a stateless factory service and they factory generates a new service instance, which is a web service with its own address. The user then works with that specific service instance and the instance remembers the state for that specific user. Instances of the same service keep their states entirely separate. When a user is finished with the state in an instance (e.g. has finished the workflow in which that state is used), he invokes an operation on the instance to destroy it. When the instance is destroyed, it frees up any resources (e.g. cached files) associated with the state. If a user abandons a servcie instance, then the instance will destroy itself after some agreed period of time in order to free its resources.

The operations for controlling the lifetime of service instances are provided by the gridService port-type, defined by OGSI and present in all grid services.

The state in a servie instance is usually exposed to the world via the service data of the instance. Service data are formally declared in the service's WSDL and can be interrogated and sometime modified via special methods on the service's gridService port. Service data are part of the definition of a port-type in a grid service. The OGSI-specified ports have service data and application-specific ports can have them too.

Per-user state isn't very usable unless users can be identified. The users need to use their state in subsequent interacgtions with the service, so the service has to know which user is calling. In addition, the service instances are exposed on the public internet, so the states must be protected and only accessible to their owners. OGSI doesn't specify the details access-control systems, but implementations of OGSI inevitably have them.

In summary:

• Grid services are a special kind of web service.
• Grid services maintain per-user state.
• Grid services expose state through service data.
• Grid services identify users and control access.

The sample service

Grid services do things that simple web services cannot; therefore grid services are not simple. Real grid services like OGSA-DAI are complicated and do not make good examples for teaching. For the tutorial, the example service is a toy, written specially to display the special features as simply as possible. This does not mean that all grid services are toys!

The sample service caches data and gives them back on demand. Each instance of the service caches just one string. It's called Gcache.

The service has two operations: store, which takes a string argument and returns nothing; and fetch which takes no arguments and returns a string.

The sample service is hosted at IoA Cambridge. The URLs for the service factories are

  http://cass123.ast.cam.ac.uk:9095/ogsa/services/astrogrid/gcache/GcacheFactory
  http://cass123.ast.cam.ac.uk:9095/ogsa/services/astrogrid/gcache/GcacheSFactory

of which the first refers to the unsecured service and the second refers to the secured service. The secured clients must be used with the secured service (otherwise access is denied). Either the secured or unsecured clients can be used with the unsecured service.

The sample clients

StoreClient

The class org.astrogrid.ogsa.gcache.StoreClient is a client for the sample service. It can be run from the command line:

  java org.astrogrid.ogsa.gcache.StoreClient <URL for Gcache factory> <string to be stored>

creates a new instance of the Gcache service and stores the given string in it. The client writes to the terminal the URL for the new service-instance.

• StoreClient.java: Client to cache a string, unsecured version

Most of the client is identical to what you would find in a client for an Axis web-service. The only differences lie in the creation of the service instance. Note that where Axis conventionally uses an xxxLocator class, the grid client uses a xxxGridLocator version that supports some extra overloaded methods. This class interacts with the name-resolution code in OGSI to locate the service instance.

StoreClientS

The class org.astrogrid.ogsa.gcache.StoreClientS is a version of StoreClient with security features added.

• StoreClientS.java: Client to cache a string, secured version

The explicit security-code is in the SecurityHelper class. Calling this sets properties on the service stub - i.e. on the object representing the service in the client - that alert the infrastructure sofware to the need for secured access. The infrastructure then loads the user's proxy identity-certificate from file and uses it to establish a security context with the service. You don't need to know the details of the security process to write and use clients and it's better not to ask; it's subtle, arcane and badly documented.

The SecurityHelper class is just a place to keep the names and values for the properties. I copy this class into the package of most clients where I use secured access.

FetchClient

The class org.astrogrid.ogsa.gcache.FetchClient is a client for the sample service. It can be run from the command line:

  java org.astrogrid.ogsa.gcache.StoreClient <URL for Gcache instance>

locates the named instance, reads the string stored in it and prints that string to the terminal.

• FetchClient.java: Client to retrive the cached string, unsecured version.

FetchClient is similar to StoreClient but instead of talking to the factory to create aq service instance, it talks directly to an existing instance; the factory is not involved.

FetchClientS

The class org.astrogrid.ogsa.gcache.FetchClientS is a version of FetchClient with security features added. The coding for the security is identical to StoreClientS.

• FetchClientS.java: Client to retrieve the cached string, secured version

EndTimeClient

The class org.astrogrid.ogsa.gcache.EndTimeClient is a client for the sample service. It operates on an existing service-instance in the same way as FetchClient. The invocation is

  java org.astrogrid.ogsa.gcache.EndTimeClient <URL for service instance>

This client reads the termination time of the service instance from the instance's service data and writes to the terminal the time that the instance has left to live.

• EndTimeClient.java: Client to read termination time, unsecured version

In EndTimeClient, there are no calls to operations declared in Gcache.wsdl. Instead, there is a call to an operation on the mandatory, OGSI-specified gridService port to read the service datum. As is normal with service data, the query and answer are packed as non-type-safe ExtensibilityTypes. This is because the code for the gridService port doesn't know at compile time the types of the service data so can't provide type-safe methods to access them.

EndTimeClientS

The class org.astrogrid.ogsa.gcache.EndTimeClientS is a secured version of EndTimeClient. The security coding is identical to that in StoreClientS.

• EndTimeClientS.java: Client to read termination time, secured version

Note on secured clients and services

The authentication in the example clients and service works...but the authorization on the service at Cambridge is suspect. I think that it may fail for all users who can't authenticate as Guy Rixon (which I hope strongly is everybody but me!). I will try to fix this over the next few days. In the meantime, anybody who can host a copy of the service on their own machine can rig the authorization to let themselves in.

Clients provided with GT3

The Globus toolkit (GT3) provides some standard clients that work with all kind of grid services. E.g.:

• org.globus.ogsa.client.CreateService creates a service instance from a factory.
• org.globus.ogsa.client.DestroyService destroys a service instance.
• org.globus.ogsa.client.RequestTermination changes the termination time for a service instance.

See the GT3 API documentation for more details and a fuller list of clients.

How to build the clients

Supporting software

You need Globus Toolkit 3.0.2. The "core" of GT3 - i.e. just the Java part - is sufficient. It is much easier and quicker to install the GT3 core than to install all of GT3. There is no need to build the core from source - Java is portable in binary form - so get the binary version unless you want to browse the source.

You need a JVM. I strongly suggest that you get Sun's JDK at version 1.4.2. There have been niggling, problems when GT3 is used with previous versions of Java 1.4.

To run the clients, you need to have on your classpath a large fraction of the jars supplied with GT3...and it's never been clear which ones are needed in any given situation so effectively you need them all. Manually building a classpath with ~20 jars is torture, so I suggest you don't try. Instead, I suggest that you load the jars from the lib sub-directory of GT3 into the sre/lib/ext sub-directory of the JDK. I.e., put the jars where the JRE will find them without reference to the classpath. You should then keep that copy of the JDK just for running GT3 clients as the pre-loaded jars may cause problems with other Java software. If you look at AstroGrid's web-site at Cambridge, you will find pre-prepared JDKs for Windows and Solaris. (Sorry, no Linux. Linux users are presumed to like DIY.)

You need the build tool ant. At least, you need it if you want to use the build-script supplied with this page. If you're happy to type the commands manually then you can do without ant. I recommend getting ant.

Getting the source code

Please download and unpack the zip file attached to this page. In there you'll find a gcache file-tree with three branches: client, seed and service.

The seed branch contains some files used to auto-generate parts of the source code. You're welcome to play with this, but be careful: if you build it, it will overwrite and/or delete the code you need to build for the tutorial. Yopu don'r need to use this branch to run the tutorial code.

The service branch contains the code for the service itself. You don't need to build or use this branch to do the tutorial but feel free to (try to) put the service on your own server. If you want to try this, the important ant commands are

  ant build
  ant deployToTomcat
  ant undeployFromTomcat
  ant clean

You'll need to edit build.properties and set ogsa.home to say where your copy of GT3 is and set tomcat.home to say where your copy of Tomcat is. This build file does not generate gar files for use with GT3's stand-alone container.

The client branch contains the source code for the tutorial. Please see the next section for the build process.

Build process: instructions

First, edit gcache/client/build.properties. Set ogsa.home to the name of the directory where you installed GT3.

Change directory to gcache/client.

Give the command

  ant build

The clients are now built. You'll find the .class files under build/classes and in the jar file in build. The clients need no configuration files to run, but just the classes.

Build process: explanation

In the build, the WSDL file for the service (gcache/client/src/wsdl/Gcache.wsdl) is used with the Axistooling supplied in GT3 to generate stub classes for the service. The stub classes are called by the hand-coded parts of the clients. The generated sourced code is put under gcache/client/build/src. The ant targte for this is generateStubs and it's using the WSDL2Java class from Axis to generate the code. This is the normal process for clients of Axis web-services and the tool hasn't been changed to support grid services.

The WSDL file includes (via the WSDL import element) some standard WSDL files that define the OGSI-specified parts of the grid service. Primarily, these imported files define the interface to the gridService port. In order for the service to work robustly, the import elements use relative URLs to find the imported files and use URLs that suit the way the service is layed out inside its service container. Therefore, to use the same WSDL file to generate the client stubs, the OGSI WSDL files have to be copied into the client tree in the same relative locations. The copyWSDL ant-target does this. It puts all the WSDL together under gcache/client/build/schema.

The compilation target, compile, is conventional. The generated stub-classes are done before the hand-coded classes that call them.

-- GuyRixon - last changed 14 Oct 2003