----
h1. WS-Notification 1.4 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.
{cagridtoc:exclude=WS-Notification 1.4 Developers Guide}\\
h2. 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:
# All [Introduce|introduce14:Home]\-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
# 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:
## Simply copy the jar from _projects/introduce-clienttools/build/lib_ to your project's build path.
## Depend on the client tools project via Ivy:{code}<dependency rev="1.4" org="caGrid" name="introduce-clienttools" conf="impl->default"/>{code}
h2. 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.
h3. 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:
# Set the system property when the JVM starts up
## {terminal}\-DGLOBUS_LOCATION = <path-to-globus-dir>{terminal}
# Set the property prior to using the Notification Helper APIs programatically
## {code}System.setProperty("GLOBUS_LOCATION", "<path-to-globus-dir>");{code}
h3. 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:
{code}public void subscriptionValueChanged(
org.oasis.wsrf.properties.ResourcePropertyValueChangeNotificationType notification);
{code}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.
h3. Subscribing to Notifications
The _SubscriptionHelper_ provides a simple public method which developers can use to subscribe to a resource property:
{code}public SubscribeResponse subscribe(Object client,
QName resourcePropertyType, SubscriptionListener listener)
throws SubscriptionCreationException
{code}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:
{code}SubscriptionHelper helper = new org.cagrid.notification.SubscriptionHelper();
{code}Next, subscribe to the resource property you are interested in.
{code}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 =
Administration
...