WS-Notification 1.3 Developers Guide

The caGrid Notification tools are a client-side API which simplifies the process of subscribing to and receiving notifications from resource properties of caGrid services.

	Contents Depending on the Notification Tools The Notification Helper API Initial Set-up Subscription Listeners Subscribing to Notifications Unsubscribing from Notifications Notification Subscription Exceptions

Depending on the Notification Tools

The caGrid WS-Notification tools are found in the caGrid directory, under projects/introduce-clienttools. There are several ways to obtain the tools and use them in your project:

1. All Introduce-generated grid services will automatically have the libraries from this project included. Developers working with such a grid service don't need to do anything additional to make use of the Notification tools
2. The client tools project itself has no inward dependencies, so the only Jar file required is the one it generates. Developers can obtain this jar and add it to their projects:
   1. Simply copy the jar from projects/introduce-clienttools/build/lib to your project's build path.
   2. Depend on the client tools project via Ivy:

      <dependency rev="1.3" org="caGrid" name="introduce-clienttools" conf="impl->default"/>

The Notification Helper API

The Notification Helper API simplifies the process of subscribing to a resource property and receiving notifications when it changes on the service side.

Initial Set-up

The Notification Helper tools make use of lower-level Globus code to perform subscriptions and listen for notifications. To get these classes properly bootstrapped, a special system property must be set so the listener can locate the local Globus installation.

The Java system property "GLOBUS_LOCATION" must be set to a value which is the location on the file system where your Globus Java WS-Core exists (typically set to the environment variable $GLOBUS_LOCATION). This can be accomplished in one of two ways:

1. Set the system property when the JVM starts up
   1. 

       -DGLOBUS_LOCATION = <path-to-globus-dir> 

2. Set the property prior to using the Notification Helper APIs programatically

   1. System.setProperty("GLOBUS_LOCATION", "<path-to-globus-dir>");

Subscription Listeners

The Notification Helper API provides an interface through which notifications are passed when they are received and processed. The Java interface org.cagrid.notification.SubscriptionListener requires a single method to be implemented:

public void subscriptionValueChanged(
    org.oasis.wsrf.properties.ResourcePropertyValueChangeNotificationType notification);

The parameter notification passed to this method is a standard type generated by and part of the Globus WS-Notification implementation. It contains both the new and the old value of the resource property, which can be obtained by calling getNewValue() and getOldValue() respectively.

Notifications are only passed along to this interface method if the message from the service is not null.

Subscribing to Notifications

The SubscriptionHelper provides a simple public method which developers can use to subscribe to a resource property:

public SubscribeResponse subscribe(Object client, 
    QName resourcePropertyType, SubscriptionListener listener)
        throws SubscriptionCreationException

The parameters are all required to be non-null:

• client
  • An instance of your grid service client which supports WS-Notification. This value is of the type Object because there is as yet no consistent Java interface which Introduce clients implement for notification purposes. However, all Introduce clients supporting WS-Notification implement certain methods for subscribing and unsubscribing, and the SubscriptionHelper expects these to exist, and will throw an exception if they are not present.
• resourcePropertyType
  • The XML QName of the resource property to which the client wishes to subscribe.
• listener
  • An instance of an implementation of the SubscriptionListener interface which will handle notifications for the subscribed resource property.

The SubscribeResponse returned by the method is the result of calling the subscribe method on the grid service client, and can be used to reference this particular subscription. It can be used to unsubscribe from notifications later.

To subscribe to notifications, begin by constructing a SubscriptionHelper instance:

SubscriptionHelper helper = new org.cagrid.notification.SubscriptionHelper();

Next, subscribe to the resource property you are interested in.

ServiceClient client = ...; // whatever code is required to create an
// instance of your grid service's client would go in here
javax.xml.namespace.QName resourcePropertyName = 
    ...; // the QName of the resource property you're interested in
SubscriptionListener listener = new SubscriptionListener() {
    // implementation of your listener
};

org.oasis.wsn.SubscribeResponse subscribe = 
    helper.subscribe(client, resourcePropertyName, listener);

Unsubscribing from Notifications

Once a notification subscription has been made, the client will continue to receive notifications from the service until the service terminates, the client application terminates, or the client unsubscribes. The SubscriptionHelper utility provides a method to perform the latter of these three options:

public void unSubscribe(SubscribeResponse subscription) 
    throws NotificationSubscriptionException

The subscription parameter passed to this method should be the same one obtained by the call to the subscribe() method. Calling this will call out to the grid service to cease sending notifications, and terminate the client side listener.

Notification Subscription Exceptions

The unSubscribe()_ method of the SubscriptionHelper utility may throw a NotificationSubscriptionException. This exception indicates a problem was encountered in either shutting down the client-side subscription listener, or sending the subscription cancellation to the service.