Leveraging Key WS-Notification Features in your Business Applications

Explanation and code for using WS-Notification in a general purpose publish/subscribe system

WS-Notification bundle of standards, WS-BaseNotification, WS-Topics, and WS-BrokeredNotification, can be used as a general purpose publish/subscribe interface for Service Oriented Architectures. To demonstrate these key WS-Notification features, a solution to the out-of-stock business situation was developed; SOAP messages and code snippets for this retail stock distribution network scenario are explained in this article.


Robert Chumbley (chumbley@us.ibm.com), Software Developer, IBM

Robert ChumbleyRob Chumbley is a member of the Emerging Software Standards team in the Strategy area of IBM's Software Group. He participates in the WS-I Basic Profile Work Group and has experience with many web service technologies and standards. Rob's favorite type of music is Texas Country.

Jacob Eisinger (jeising@us.ibm.com), Software Developer, IBM

Jacob EisingerJacob Eisinger is a member of the Emerging Software Standards team in the Strategy area of IBM's Software Group. Jacob participated in the Extreme Blue program and has experience with XML, Java, and web services.

09 April 2009

Also available in Chinese

Event Distribution

In a Service Oriented Architecture (SOA), there is often a need to monitor situations. This occurs from a computer management perspective or a much more broad scope of keeping up to date on real world events such as weather, financial transactions, healthcare, etc. To monitor these events, a client can poll for status changes or subscribe for status changes.

In the REST world, this type of monitoring is done via polling usually on feeds such as ATOM or RSS. In this case, the client is configured to actively ask the resource for its latest state. The more often the client polls for state, the more likely the client has an accurate resource representation. However, frequent polling requires bandwidth and resources on both sides to handle the connection. Thus polling is useful when monitoring timeliness is not an issue or network and hardware resources are abundant.

In the SOAP world, polling is less common as a client typically receives requests from the producer of events. With this peer to peer style, a publish/subscribe system can be created. In this system, the client requests that notifications be sent when they occur. This reduces the latency between the event occurring and the client processing it.

WS-Notification has been standardized by OASIS and is the only standard that solves this business problem of event distribution in heterogeneous complex event processing systems. It specifies an interface for a consumer to subscribe, filter notifications, and manage subscriptions and an interface for publishers to send notifications. Further, it describes a notification broker to allow for scaling of the system. See Resources for more information about the WS-Notification Working Group and specifications.

Why WS-Notification

WS-Notification is a standard that enables multiple implementations to work together. Having this standard allows for a larger community of producers and consumers to interoperate. WS-Notification is not meant to replace all messaging infrastructure such as low latency buses, industry standards, or existing infrastructure like JMS. However, WS-Notification systems should be able to integrate with these systems through simple adapters. Obviously, the key value to WS-Notification is its ability as a standard to allow for greater interoperability with a greater number of vendors and, thus, a lower cost for implementation.

Both the WS-Eventing specification and the WS-Notification standard are applicable to computer management scenarios. However key features of WS-Notifications allow for it to be used as well in general purpose publish/subscribe (pub/sub) situations. The scenario of a retail stock distribution is explored and how the features of WS-Notification enable a solution.

Distribution Network Scenario

To demonstrate these WS-Notification features, event distribution was applied to solve a typical retail and customer business problem of out-of-stock (OOS) situations; OOS situations occur when a store is unable to fulfill a customer's order. Although obviously, a sale is lost from the retail side, the customer and the retailer's relationship is also damaged. To better this customer relationship, this solution reduces OOS situations by tracking in-store shelf availability and reordering stock based on business driven thresholds.

See the Resources section for more business context surrounding OOS situations.

In this scenario, there are four roles:

  • Customer
  • Store
  • Distribution broker
  • Distributor
Figure 1. Distribution network showing off the interaction of the roles of customer, store, distribution broker, and distributor.
Distribution network showing off the interaction of the roles of consumer, store, distribution broker, and distributor.

Customers cause notifications for more inventory to be generated. When a customer purchases products from a store, the store's inventory is reduced. And, when the inventory drops below a threshold, the store sends a notification for more inventory to the distribution broker. The distribution broker then filters the notifications based on the active subscriptions. Finally, the distributors subscribed to the product are notified of the store's needs.

Distributors subscribe to the distribution broker for items they distribute. Distributors may pause and resume their subscriptions; any stock notifications sent are stored at the distributor broker until the distributor resumes the subscription.

The technical implementation of this scenario allows for the following:

  • An Event Processing system from one vendor receiving events produced by applications running on a another vendor's system
  • An Event Processing system from one vendor distributing events to applications running on another vendor's system
  • An Event Processing system from one vendor subscribing to request events from another vendor's system

This solution illustrates the spectrum of event distribution capabilities required for a scalable, high volume, efficient event processing solution and how to leverage the unique capabilities of WS-Notification, especially the Brokered Notification and Topics for the distribution and filtering of events.

WS-Notification Key Features Demonstrated

Other WS-Notification Features

WS-Notification also provides other features useful for event distribution.

Distribution Control
A subscription defines notifications that should be delivered to a consumer.
Dynamic Create/Destroy
Subscriptions are managed at runtime allowing for new consumers of notifications to be added or removed on the fly.
Time Period
Subscriptions expire based on the time period provided during registration. The ability exists to specify a indefinite time period and to renew subscriptions.
Filter by Content
Notifications may not always be relevant to all consumers. Therefore, consumers may choose to receive only notifications whose content match the criteria provided.
Push Delivery
Rather than a consumer constantly polling for notifications, push notifications are delivered directly.

WS-Notification has a robust set of capabilities that increase productivity. By using them in architectures, common software components can be reused. Some of the key features include push/pull notifications, topics, pause/resume capabilities, broker scalability, and publisher registration.

Note: The code is in this article is based on the WebSphere Application Server Version 7.0 implementation of WS-Notification Broker.

WS-Notification Technology

WS-Notification specifies SOAP-based messages so that common SOAP components can be reused. This solution uses JAX-WS for the web service interfaces and reuses the WebSphere Application Server (WAS) 7.0’s implementation of the WS-Notification Broker. A more functional interface into W3C endpoint references (EPRs) was needed for tasks like adding and viewing reference parameters, so the WAS Service Provider Interfaces (SPIs) were used in the implementation as well. To illustrate the features, a combination of the example SOAP messages and JAX-WS code will be explained.

Other sources of notification can be consumed by the WAS WS-Notification broker as well. WS-Eventing, for example, is another specification that allows subscriptions to event sources. In this particular scenario, an adapter was developed to allow the broker to subscribe to WS-Eventing sources and transform WS-Eventing events into notification messages that the registered distributors could consume. There were no changes required to the WS-Eventing event producer to enable this support. While WS-Notification provides more capabilities than WS-Eventing, when working with WS-Eventing sources, only WS-Eventing compatible event notifications are communicated.


In even the most simple pub/sub environments, the amount of connections and boot strapping information can grow very quickly. If there are only 2 publishers and 2 consumers, and each consumer wants to be notified from each publisher, 4 connections need to be set up. Add one more consumer and you now have 6 connections; add another publisher and the total connections is now 9. The number of connections start to gow very quickly as more distributors and consumers are added; the required number of connections for m publishers and n consumers is m x n connections. To simplify this topology, WS-Notification standardized a notification broker that acts as an intermediary between publishers and consumers. Here, publishers and consumers are decoupled from each other and instead only require boot strap information to the broker. So, in the simple scenario of 3 publishers and 3 consumers, the required number of connections is 6: m + n.

Figure 2. This diagram shows the m x n connection problem when a broker is not used.
This diagram shows the m x n connection problem when a broker is not used.

In the retail scenario, a decoupling allows for flexible business relationships; distributors and stores may be added and removed without affecting the configuration of the current stores and distributors.


WS-Notification provides the concept of topics which group notifications that have commonality outside of the their message content. This can include common topics such as "all notifications that relate to stores" or more grabular topics such as "all notifications that relate to store number 123." Topics can also include actions; for example, "all sell actions." In short, topics enable notifications to be categorized not on their content, but on other metadata.

Topics allow for consumers to register for notifications about a given topic and not specific messages.

On-Demand Publisher

In the decoupled, brokered environment, the publishers don’t have direct contact with the consumer. So, a publisher is unable to know if a notification they generate will be consumed. And, since the generation and the transmission of a notification are resource intensive tasks, WS-Notification provides a standard way for a broker to communicate whether notifications should be sent or not. A publisher who implements these interfaces is said to be an on-demand publisher.

Publisher Registration

On-demand publishers need a way to describe to a broker what notifications they can produce. WS-Notification standardizes this publisher registration. During registration, the publisher indicates which notifications it can create through the use of topics. With this information the broker can efficiently communicate which notifications consumers have subscribed for and thus which ones the on-demand publisher should create.

Pausable Subscriptions

On the consumer side, there are times when they will be unable to receive or process notifications. For example, this would be the case during scheduled maintenance. In this situation, the consumer can use WS-Notification’s pause/resume capability to keep notifications from being sent on to the consumer until the consumer issues a resume command.

Listing 1. JAX-WS code for pausing a subscription.
SubscribeResponse subscribeResponse = ...;
W3CEndpointReference subEPR = subscribeResponse.getSubscriptionReference();
SubscriptionManager port =
	subEPR.getPort(SubscriptionManager.class, new AddressingFeature());
port.pauseSubscription(new PauseSubscription());
Listing 2. JAX-WS code for resuming a subscription.
SubscribeResponse subscribeResponse = ...;
W3CEndpointReference subEPR = subscribeResponse.getSubscriptionReference();
SubscriptionManager port =
	subEPR.getPort(SubscriptionManager.class, new AddressingFeature());
port.resumeSubscription(new ResumeSubscription());

The response from the Notification Broker for a subscribe operation contains an end point reference to the Subscription Manager responsible for that subscription. You can pause and resume your subscription by invoking those operations on the Subscription Manager.

Pull Subscriptions

In secure environments, such as behind firewalls, the push model for event distribution is the most efficient. In this mode, as events occur, notifications are sent and processed quickly. However some environments have security requirements that disallow a notification consumer from receiving direct events. For example, this would likely occur when a firewall is between the publisher and the consumer. This could occur when the distributor, store, and the distributor broker are on different networks with a firewall between them. In this case, WS-Notification specifies a standard pull model interaction; the consumer continuously polls the publisher for new notifications. The publisher is responsible for maintaining a cache on a best effort basis of previous notifications. WS-Notification specifies that the first or the last message may be dropped when storage is met.

To enable this workflow, the consumer requests for the broker to create a pull point. And, then the consumer sends a subscribe request with the topics of interest and that pull point as the consumer reference. Finally, the consumer polls the pull point for notifications.

Listing 3. JAX-WS code for creating a pull point from a broker.
NotificationBroker port = ...;
CreatePullPointResponse response = port.createPullPoint(new CreatePullPoint());
W3CEndpointReference pullPointEpr = response.getPullPoint();
Listing 4. JAX-WS code for polling the pull point.
NotificationBroker port = pullPointEpr.getPort(NotificationBroker.class,
  new AddressingFeature());
GetMessagesResponse getMessageResponse = port.getMessages(new GetMessages());

As you can see, the message pattern and the JAX-WS code is straight forward. WS-Notification specifies an empty message to be sent to create the pull point. And, to retrieve notifications, the GetMessages operation is called. WS-Notification allows for an optional MaximumNumber element to be used to specify the maximum number of notifications to be returned. Here we omitted the MaximumNumber element and thus all notifications stored at the pull point should be returned.

WS-Notification Scenario Specifics

WS-Notification was used in this retail distribution supply chain scenario for the notifications from the store to the broker and from the broker to the distributors. This was done through a number of different steps:

  1. The distributor registered their interest with the broker.
  2. The store either was configured to send notifications to the broker or was configured to register itself as a publisher to the broker.
  3. If store registered itself as a publisher to the broker, the broker would ask for notifications from the store.
  4. The store would send stock order notifications to the broker.
  5. The broker would forward this stock order notifications on to interested distributors.

From the user interface perspective, their are two interfaces: the store and the distributor. The store is responsibible for allowing consumers to make purchases of products. The distributor interface allows users to manager which products they can restock and an interface to monitor distribution notifications as they arrive. See Figure 3 for a pictorial view of the retail stock distribution scenario.

Figure 3. User's perspective of the retail stock distribution scenario showing the interface for the store and distributor.
User's perspective of the retail stock distribution scenario showing the interface for the store and distributor.

WS-Notification Distributor Subscribe Request

The distributor subscribe request is a message sent from the distributor to the broker to request notifications to be sent. It contains the product id for a product that the distributor wishes to distribute.

Listing 5. SOAP body contents of a subscribe request for notification delivery.
<wsnt:Subscribe xmlns:wsa="http://www.w3.org/2005/08/addressing"

In this subscription request, the MegaDistributor requests for notifications for products with id EAT84.

WS-Notification Stock Distribution Message

The stock distribution message is the notification sent between the store and the broker and the broker and the distributor. The notification contains the product code and the quantity requested.

Listing 6. SOAP body contents of a notification for more products.
<wsn:Notify xmlns:wsn="http://docs.oasis-open.org/wsn/b-2">
    <wsn:Topic Dialect="http://docs.oasis-open.org/wsn/t-1/TopicExpression/Simple"
      <d:quantity xmlns:d="http://www.ibm.com/xmlns/wsn/demo/distributor">6</d:quantity>

In the notification message, the item id is mapped to the topic and the quantity requested is mapped to the message contents. In this specific notification, the item id is ELE19 and the quantity requested for distribution is 6.


This article discussed how the WS-Notification bundle of standards, WS-BaseNotification, WS-Topics, and WS-BrokeredNotification, can be used as a general purpose publish/subscribe interface for a Service Oriented Architecture. We introduced the retail stock distribution network scenario to help demonstrate the WS-Notification features and explained how WS-Notification is the standard of choice for event distribution and processing.



Get products and technologies



developerWorks: Sign in

Required fields are indicated with an asterisk (*).

Need an IBM ID?
Forgot your IBM ID?

Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.


All information submitted is secure.

Dig deeper into SOA and web services on developerWorks

Zone=SOA and web services, WebSphere
ArticleTitle=Leveraging Key WS-Notification Features in your Business Applications