## 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 =
...; // 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);
{code}
h3. 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:
{code}public void unSubscribe(SubscribeResponse subscription)
throws NotificationSubscriptionException
{code}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.
h3. 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.
Administration
...