Introduction

Introduction

The standard GRIA client allows you to invoke service operations manually using a point-and-click graphical interface. However, it is often necessary to perform the same sequence of operations (such as processing some data using three different applications in series) many times. This can be done by writing some Java code, using GRIA's Java API. The API provides access to all of the service functionality. In fact, the standard GRIA client is just another application that uses the API.

The library has two parts:

• The core provides Java proxy objects (corresponding to remote services and resources), and a repository in which to store them.
• The Swing interface components let users view the repository and invoke operations manually.

The library handles security and encryption for you.

There are several ways to write code using GRIA:

• You can extend your own application to invoke service operations directly. For example, a 3D design tool could have a Render button that submits the scene to a rendering service and then downloads and visualises the results.
• You can write a plug-in for the standard client, extending its functionality.
• You can embed the Swing components into your application, so that users don't have to switch to a different application to perform tasks such as setting access control rights on data stagers.

Note that writing new GRIA services is outside the scope of this document. See the GRIA Service Developer Kit documentation for that.

This document is just a tutorial, so we only cover the most common cases. See the full JavaDoc API documentation for more details.

Creating a stand-alone client

To use the GRIA libraries from your own applications (rather than writing a plug-in for the standard client), ensure that all of the following are in your application's classpath:

1. All the jars from the standard client's lib directory, except for itinnov-grid-client-cli-VERSION.jar, which is the default client itself.

2. The client-config.wsdd and implementationfactory.properties files (from inside itinnov-grid-client-cli-VERSION.jar).

   The WSDD file causes messages to be signed correctly and contains type mappings telling Axis how to serialise various types, while the implementationfactory file says where to find classes implementing various interfaces.

3. The crypto.properties file from the client's conf directory, which gives details of the keystore to use.

Creating a plug-in

Plugins extend the functionality of the standard GRIA client. To create a plug-in:

1. Create an implementation of the GridClientPluginProvider interface.

2. List the implementation in your jar's META-INF/services/uk.ac.soton.itinnovation.grid.comms.client file.

3. Place your jar in the client's conf/plugins directory and restart the client.

The plug-in can then extend the client. For example, it could add extra items to the normal menus by adding a PluginHook to the Swing interface.

The StateRepository

A StateRepository stores resources (accounts, SLAs, jobs and data) and services. There are two implementations provided with the library:

• FileStateRepository stores them in an XML format file.
• MemoryStateRepository only stores them in memory. Quitting the application will cause them to be forgotton.

Creating a StateRepository

To create a new memory repository:

StateRepository repository = new MemoryStateRepository();

To create a new repository that stores its state in a file called client.state (this is what the standard client uses):

StateRepository repository = new FileStateRepository("client.state");

It is probably easiest to use FileStateRepository as you can create objects using the standard client and then use them from your own program.

Creating a Proxy to a Service XXX

Just as when using the graphical client interface, services must be added to the repository before they can be used. All the details about an object in a StateRepository are represented as a WS-Addressing EndpointReference. For example, to create a RemoteDataService proxy:

EndpointReference serviceEPR = ConversationID.getEPR("https://.../services/DataService");
RemoteDataService dataService = (RemoteSLAService)repository.getOrCreateObject(RemoteDataService.class, serviceEPR);

The getOrCreateObject method takes an EPR for the object you want, and a Java interface for the resulting object. If the object is already in the respository then it returns it, otherwise it creates a new one, adds it to the repository, and returns that.

Note: getOrCreateObject uses the ImplementationFactory class to find a suitable implementation of an interface (such as RemoteDataService) when creating new objects.