Document Actions

Key concepts and classes

Jump to:

The main classes used by a GRIA client when invoking services.

Identity

When you invoke a SOAP operation, the SOAP message is signed using your private key to let the receiver verify that it really is from you. The message contains:

The SOAP body itself, with the actual request.
A signature, made using your private key.
Your X.509 certificate, which comprises:

Your public key, corresponding to the private key that made the signature.
Your full distinguished name (DN).
Another signature, by your Certificate Authority (CA), asserting that the DN and the public key match. i.e. that the key belongs to you.

The system gets everything it needs to secure the message from an Identity object. An Identity contains your public and private keys, your certificate, and certificates of any CAs that you trust.

IdentityProvider

In many cases, the exact Identity used can change over time. For example, your certificate may expire and another one must be obtained. Therefore, we normally pass around IdentityProvider objects rather than plain Identity objects. A variety of IdentityProviders are supplied with GRIA:

The options are:

FixedIdentityProvider: You supply an Identity to the constructor. It always returns this.
TestIdentityProvider: A new key-pair and self-signed certificate is generated and then always returned. Use this only for test code.
KeystoreIdentityProvider: A Java KeyStore (JKS) file is loaded and used.
UsernameIdentityProvider: A new key-pair is generated and given a certificate signed by another Identity. This is for use in portals where users only have usernames and passwords rather then key-pairs.
KrbIdentityProvider: An Identity is fetched from a Kerberos service. This allows users with a Kerberos or Active Directory login to get an Identity automatically.
SwingIdentityProvider: This displays a dialog box asking the user to choose one of the other identity providers. This is the one used by the default GRIA client.

For example, this script will create and display an Identity from a keystore file:

import uk.ac.soton.itinnovation.grid.utils.KeystoreIdentityProvider

idp = new KeystoreIdentityProvider("/path/to/mykeystore.ks", "myname", "mypassword".toCharArray())
println idp.getIdentity()

To run the script, save it (e.g. as "keystore.groovy") and then run it using the GRIA client, like this:

gridcli keystore.groovy

It will print out the Distinguished Name from the certificate.

Transport

When invoking a SOAP operation (or a client-authenticated plain HTTPS connection), we need to make sure our IdentityProvider is used. This is done by using a Transport. For example, to fetch the WSDL for a service:

myTransport = new AxisTransport(idp)
wsdlDoc = myTransport.fetchWSDL(new URL("https://griademo1.it-innovation.soton.ac.uk/gria-basic-app-services/services/DataService?wsdl"))

Note: if you get the error "No trusted certificate found" then you need to add the service's certificate (or CA certificate) to your keystore. You can also set a CertificateTrustValidator on the Transport if you want to perform some other action, such as displaying a confirmation dialog box for unknown certificates. By default, the GRIA client supplies a default Transport which is configured this way (assuming you chose a KeystoreIdentityProvider when prompted):

WSDLCache

You'll probably want to download service WSDL in many places, so it makes sense to cache it. You can do this using a WSDLCache:

myWsdlCache = new WSDLCacheImpl(transport)
wsdlDoc = myWsdlCache.get(new URL("https://griademo1.it-innovation.soton.ac.uk/gria-basic-app-services/services/DataService?wsdl"))

Note that we're now using the default Transport ("transport") rather than "myTransport" for simplicity. You can use the WSDL document to get a RemoteMethod for the SOAP operation you want to invoke. This can be passed to Transport's invokeService method to actually invoke an operation.

EndpointReference

The EndpointReferenceType is defined in the WS-Addressing specification. Essentially, it's a glorified URL. EndpointReferences (or EPRs) are used in many places in GRIA to identify services and resources.

The easiest way to create an EPR is by using the ConversationID helper class. For example, this EPR represents a service:

jobServiceEPR = ConversationID.getEPR("https://griademo1.it-innovation.soton.ac.uk/gria-basic-app-services/services/DataService")

To create an EPR for a resource at a service, give the resource ID as a second argument. This EPR represents a particular job:

jobEPR = ConversationID.getEPR(
	"https://griademo1.it-innovation.soton.ac.uk/gria-basic-app-services/services/DataService",
	"2c908085-0c26311b-010c-39ec3c46-0010")

InvocationEngine

Transport provides a low-level way to invoke a SOAP operation, but in GRIA we often need to add a federation context (such as an SLA) or a security token to a message before sending it. This can be handled for you using an InvocationEngine:

Again, a default engine is available to the Groovy script (as "engine"), or you can create one manually.

ProxyFactory

Having to create a RemoteMethod from the WSDL and pass it to an invoke method is tedious, so it is more common to create a Java proxy to a remote service. Each SOAP operation on the service appears as method on the proxy which, when called, uses the invoke method on the invocation engine. Such proxies can be created using an InvocationEngineProxyFactory:

import uk.ac.soton.itinnovation.grid.comms.job.JobService;
import uk.ac.soton.itinnovation.grid.types.ConversationID;
import uk.ac.soton.itinnovation.grid.client.proxy.InvocationEngineProxyFactory;

jobServiceEPR = ConversationID.getEPR("https://griademo1.it-innovation.soton.ac.uk/gria-basic-app-services/services/DataService")
pf = new InvocationEngineProxyFactory(engine, myWsdlCache)
jobService = pf.createProxy(jobServiceEPR, JobService)
println jobService.getServiceProviderID()

This script creates a proxy to a JobService and then invokes the getServiceProviderID SOAP operation to print out the service's certificate details.

HelperProxyFactory

The proxies from an InvocationEngineProxyFactory simply invoke the SOAP operations on the service. You may want to use smarter proxies which add new convenience methods or modify the behaviour of existing ones. For example, data stagers in a GRIA 5.2 data service have a destroy SOAP operation (from the WS-ResourceLifetime specification). However, GRIA 5.0 services don't support this, and have a finishData operation instead. You can use a HelperProxyFactory to get a proxy that calls the correct method automatically by looking at the WSDL to see what is supported. The default proxyFactory variable provided to a Groovy script is a HelperProxyFactory configured with helpers from all available plugins:

To get a helper proxy, you need to specify the Java interface you want it to implement. For example, use DataConversation rather than DataStagerResource in the call to createProxy.

ServiceFactory

To create a proxy from a service's WSDL (rather than from an EPR), use a ServiceFactory instead. The "serviceFactory" variable provided to the Groovy script contains a factory configured to recognise all service types supported by the installed client plugins:

dataService = serviceFactory.createServiceProxy("https://griademo1.it-innovation.soton.ac.uk/gria-basic-app-services/services/DataService?wsdl")
println dataService.getServiceProviderID()

PersistentRegistry

A Registry can be used to store a collection of EPRs. The PersistentRegistry class persists its contents in an XML file. By default, the GRIA client has a single registry, stored in the "client.reg" file. This is available to Groovy scripts via the "registry" variable.

This registry is also included in the search path of the default InvocationEngine ("engine") and is used to find SLAs and trade accounts when invoking services.

Summary of Groovy bindings

The following bindings are set up automatically by the GRIA client and made available for use in Groovy scripts:

Name	Type	Value
argv	String[]	Command-line arguments passed to gridcli (including the name of the Groovy script)
idp	IdentityProvider	A SwingIdentityProvider.
transport	Transport	A Transport that uses the Swing identity provider.
wsdlCache	WSDLCache	A WSDLCacheImpl that uses "transport".
engine	InvocationEngine	A DefaultInvocationEngine that uses the transport, a DefaultAttributeSelector and a DefaultFederationSelector. Its search path contains "registry".
proxyFactory	ProxyFactory	A HelperProxyFactory configured to use an InvocationEngineProxyFactory with "transport" and helpers from "helperRegistry".
helperRegistry	Map	A mapping from interfaces to helpers for those interfaces, collected from the installed plugins.
registry	SimpleRegistry	A PersistentRegistry backed up by the "client.state" file.