Example: Subscribing a WS-Notification consumer

Example: Subscribing a WS-Notification consumer

Use this task to write the code for a JAX-RPC client acting in the publisher registration role, registering a publisher (producer) application with a broker, based on the example code extract provided.

This example is based on using the Java API for XML-based remote procedure calls (JAX-RPC) APIs with code generated using the WSDL2Java tool (run against the Notification Broker WSDL generated as a result of creating the WS-Notification service point) and WebSphere Application Server APIs and SPIs.
In WebSphere Application Server there are two implementations of the WS-Notification service: Version 6.1 and Version 7.0. This JAX-RPC example can interact successfully with Version 6.1 or Version 7.0 WS-Notification service points. However to use WS-Notification with policy sets, for example to enable composition with WS-ReliableMessaging, then the WS-Notification applications must be encoded to use the Java API for XML-based Web Services (JAX-WS) programming model and must interact with Version 7.0 WS-Notification service points. If we are new to programming JAX-WS client applications, see the following topics:

JAX-WS

JAX-WS client programming model

Implement static JAX-WS web services clients

Writing JAX-WS applications for WS-Notification

Web services hints and tips: JAX-RPC versus JAX-WS, Part 1
The article Writing JAX-WS applications for WS-Notification includes an example of a JAX-WS subscriber client application.
Raw subscriptions:
In this example, the first optional code block shows you how to create a raw subscription. This concept is defined in section 4.2 of the Web Services Base Notification specification.
In the normal case, a wrapped subscription causes the Notify operation of the NotificationConsumer to be driven when matching event notifications become available. If the Subscriber instead creates a raw subscription, then only the application specific content of the event notification (that is, the contents of the NotificationMessage element) are sent to the target consumer endpoint. Note that the web service endpoint specified in the ConsumerReference of the Subscribe request that also specifies UseRaw (that is, a raw subscription request) does not have to implement the NotificationConsumer port type because the Notify operation will not be used to deliver event notifications.
This means that the consumer must be able to accept operations for each of the types of application content that will be published on the specified topic. This pattern allows WS-Notification to invoke a group of existing web service applications that are not WS-Notification aware, but that want to receive the same information.
JAX-WS supports action-based dispatch, and JAX-WS raw consumer applications must accept the http://docs.oasis-open.org/wsn/bw-2/NotificationConsumer/Notify action URI. For more information, see the troubleshooting tip A JAX-WS application that is a raw consumer of brokered notifications must recognize a notification broker SOAP action.
To write the code for a JAX-RPC client acting in the publisher registration role, registering a publisher (producer) application with a broker... referring to the example code extract for further information.

Look up the JAX-RPC service. The JNDI name is specific to the web services client implementation.

Get a stub for the port on which to invoke operations.

Create the ConsumerReference. This either contains the address of the consumer web service that is being subscribed to, or a reference to a pull point. Specifying a pull point EPR indicates that the consumer is to use pull-based notifications.

Create the filter. This provides the name of the topic to which to subscribe the consumer.

Create a topic expression and add it to the filter. The prefixMappings are mappings between namespace prefixes and their corresponding namespaces for prefixes used in the expression.

Create an XPath 1.0 message content filter. For example you could select a subset of the available messages in the topic, based upon salary level. For an example of message content filter usage, see Filtering the message content of publications.

Create the InitialTerminationTime. This is the time when we want the subscription to terminate. For example, you could set a time of 1 year in the future.

Create the Policy information.

Optional: Construct a policy indicating that the consumer is to receive raw style notifications.

Create holders to hold the multiple values returned from the broker:

The subscription reference

The current time at the broker

The termination time for the subscription

Any additional elements

Invoke the Subscribe operation by calling the associated method on the stub.

Get the returned values:

An endpoint reference for the subscription that has been created. This is required for subsequent lifetime management of the subscription, for example pausing the subscription.

The current time at the broker.

The termination time of the subscription.

Any other information.

Example
The following example code describes a subscriber client application that can subscribe a consumer application with a broker:
// Look up the JAX-RPC service. The JNDI name is specific to the web services client implementation InitialContext context = new InitialContext();
javax.xml.rpc.Service service = (javax.xml.rpc.Service) context.lookup(
    "java:comp/env/services/NotificationBroker");

// Get a stub for the port on which to invoke operations NotificationBroker stub = (NotificationBroker) service.getPort(NotificationBroker.class);

// Create the ConsumerReference. This contains the address of the consumer web service that is being
// subscribed, or alternatively is a reference to a pull point (see alternative below). Specifying a // pull point EPR indicates that the consumer is to use pull-based notifications.
EndpointReference consumerEPR = 
    EndpointReferenceManager.createEndpointReference(new URI("http://myserver.mycom.com:9080/Consumer"));

/*
// Alternative ConsumerReference for pull-based notifications:

EndpointReference consumerEPR = pullPointEPR;

*/

// Create the Filter. This provides the name of the topic to which to subscribe the consumer
Filter filter = new Filter();

// Create a topic expression and add it to the filter. The prefixMappings are mappings between namespace // prefixes and their corresponding namespaces for prefixes used in the expression
Map prefixMappings = new HashMap();
prefixMappings.put("abc", "uri:example");
TopicExpression exp =
    new TopicExpression(TopicExpression.SIMPLE_TOPIC_EXPRESSION, "abc:ExampleTopic", prefixMappings);        
filter.addTopicExpression(exp);


//Create an XPath 1.0 message content filter
//This example selects a subset of the available messages in the topic, based upon salary level
String filterExpression = "/company/department/employee/salary > 10000";
URI xpathURI = new URI(http://www.w3.org/TR/1999/REC-xpath-19991116);

QueryExpression qexp = 
    new QueryExpression(xpathURI, filterExpression);

filter.addMessageContentExpression(qexp);

// Create the InitialTerminationTime. This is the time when we want the subscription to terminate.
// For example, set a time of 1 year in the future.
Calendar cal = Calendar.getInstance();
cal.add(Calendar.YEAR, 1);
AbsoluteOrRelativeTime initialTerminationTime = new AbsoluteOrRelativeTime(cal);

// Create the Policy information
SOAPElement[] policyElements = null;

/*
Optional --------
The following lines show how to construct a policy indicating that the consumer is to 
receive raw style notifications:

    javax.xml.soap.SOAPFactory soapFactory = javax.xml.soap.SOAPFactory.newInstance();
    SOAPElement useRawElement = null;

    if (soapFactory instanceof IBMSOAPFactory) {
        // We can use the value add methods provided by the IBMSOAPFactory API to create the SOAPElement
        // from an XML string.
       String useRawElementXML = "<mno:UseRaw xmlns:mno=\"http://docs.oasis-open.org/wsn/b-2\"/>";
        useRawElement = ((IBMSOAPFactory) soapFactory).createElementFromXMLString(useRawElementXML);
    } else {
        useRawElement = soapFactory.createElement("UseRaw", "mno", "http://docs.oasis-open.org/wsn/b-2");
    }

    policyElements =  new SOAPElement[] { useRawElement };
*/

// Create holders to hold the multiple values returned from the broker:
// The subscription reference
EndpointReferenceTypeHolder subscriptionRefHolder = new EndpointReferenceTypeHolder();

// The current time at the broker
CalendarHolder currentTimeHolder = new CalendarHolder();

// The termination time for the subscription
CalendarHolder terminationTimeHolder = new CalendarHolder();

// Any additional elements AnyArrayHolder anyOtherElements = new AnyArrayHolder();

// Invoke the Subscribe operation by calling the associated method on the stub
stub.subscribe(consumerEPR, filter, initialTerminationTime, policyElements, anyOtherElements, subscriptionRefHolder, currentTimeHolder, terminationTimeHolder);

// Get the returned values:
// An endpoint reference for the subscription that has been created. It is required for
// subsequent lifetime management of the subscription, for example pausing the subscription
com.ibm.websphere.wsaddressing.EndpointReference subscriptionRef = subscriptionRefHolder.value;

// The current time at the broker
Calendar currentTime = currentTimeHolder.value;

// The termination time of the subscription
Calendar terminationTime = terminationTimeHolder.value;

// Any other information
SOAPElement[] otherElements = anyOtherElements.value;
Related concepts

WS-Notification

Related tasks

Writing a WS-Notification application that exposes a web service endpoint
Writing a WS-Notification application that does not expose a web service endpoint
Filtering the message content of publications
Example: Pausing a WS-Notification subscription
Example: Publishing a WS-Notification message
Example: Create a WS-Notification pull point
Example: Getting messages from a WS-Notification pull point
Example: Registering a WS-Notification publisher
Example: Create a Notification consumer web service skeleton
Use WS-Notification for publish and subscribe messaging for web services
Secure WS-Notification

WS-Notification troubleshooting tips
Writing JAX-WS applications for WS-Notification