Example: Subscribing a WS-Notification consumer

Example code that describes a client acting in the subscriber role, subscribing a consumer application with a broker.

Example

This example is based on using the Java API for XML-based remote procedure call (JAX-RPC) APIs in conjunction with code generated using the WSDL2Java tool (run against the Notification Broker WSDL generated as a result of creating your WS-Notification service point) and WebSphere® Application Server APIs and SPIs.

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 wish to receive the same information.

// 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 you want to invoke operations
NotificationBroker stub = (NotificationBroker) service.getPort(NotificationBroker.class);

// Create the ConsumerReference. This contains the address of the consumer Web service which is being
// subscribed, or alternatively is a reference to a pull point (see alternative below). Specifying a
// pull point EPR indicates that the consumer wishes 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 you want 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 the InitialTerminationTime. This is the time when you want the subscription to terminate.
// For this example we 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
wants 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
JAX-RPC
Learning about 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
WS-Notification - publish and subscribe messaging for Web services
Securing WS-Notification
Developing applications that use WS-Notification
Related reference
Example: Pausing a WS-Notification subscription
Example: Publishing a WS-Notification message
Example: Creating a WS-Notification pull point
Example: Getting messages from a WS-Notification pull point
Example: Registering a WS-Notification publisher
Example: Notification consumer Web service skeleton
Sharing event notification messages with other bus client applications
WS-Notification troubleshooting tips
Related information
WSDL2Java command for JAX-RPC applications
Reference topic Reference topic    

Terms and conditions for information centers | Feedback

Last updatedLast updated: Aug 31, 2013 12:02:36 AM CDT
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=pix&product=was-nd-zos&topic=rjwsn_ex_sub
File name: rjwsn_ex_sub.html