Network Deployment (Distributed operating systems), v8.0 > Develop and deploying applications > Develop web services - Notification (WS-Notification) > Develop applications that use WS-Notification


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 by using the WSDL2Java tool (run against the Notification Broker WSDL generated as a result of creating your WS-Notification service point) and WAS APIs and SPIs.

In WAS there are two implementations of the WS-Notification service: v6.1 and v7.0. This JAX-RPC example can interact successfully with v6.1 or v7.0 WS-Notification service points. However to use WS-Notification with policy sets, for example to enable composition with WS-ReliableMessaging, then your WS-Notification applications must be encoded to use the Java API for XML-based Web Services (JAX-WS) programming model and must interact with v7.0 WS-Notification service points. If you are new to programming JAX-WS client applications, see the following topics:

The article Write 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, complete the following steps, referring to the example code extract for further information.


Procedure

  1. Look up the JAX-RPC service. The JNDI name is specific to your web services client implementation.
  2. Get a stub for the port on which to invoke operations.
  3. 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.
  4. Create the filter. This provides the name of the topic to which to subscribe the consumer.
  5. 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.
  6. 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 Filter the message content of publications.
  7. Create the InitialTerminationTime. This is the time when you want the subscription to terminate. For example, you could set a time of 1 year in the future.
  8. Create the Policy information.

  9. Optional: Construct a policy indicating that the consumer is to receive raw style notifications.
  10. 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

  11. Invoke the Subscribe operation by calling the associated method on the stub.
  12. 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 your 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 you 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;

JAX-RPC
WS-Notification
Use WS-Notification for publish and subscribe messaging for web services
Secure WS-Notification


Related


WSDL2Java command
WS-Notification troubleshooting tips
http://www.ibm.com/developerworks/websphere/techjournal/0811_partridge/0811_partridge.html

+

Search Tips   |   Advanced Search