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