WS-Notification in WebSphere Application Server Version 6.1

This article introduces you to the concepts of WS-Notification and describes how to use it in WebSphere® Application Server Version 6.1 to provide an open standards approach to publish and subscribe messaging.

Share:

Ben Bakowski (bakowski@uk.ibm.com), Software Test Engineer, IBM

Ben Bakowski photoBen Bakowski is the technical test lead for WS-Notification in WebSphere Application Server 6.1. Based in IBM United Kingdom Lab in Hursley, Ben has worked with a wide range of Web services and embedded messaging technologies since the inception of the service integration bus in WebSphere Application Server 6.0. You can contact Ben at bakowski@uk.ibm.com.



Chris Whyley (whyleyc@uk.ibm.com), Software Test Engineer, IBM

Author photoChris Whyley is a technical leader in web services testing at the IBM Hursley Software Laboratory in the UK, where he helps to put Service Integration Bus technologies through their paces. Chris has worked with a wide range of web services technologies across several releases of WebSphere Application Server, and is co-author of the WebSphere Version 6 Web Services Handbook. You can contact Chris at whyleyc@uk.ibm.com.



Matt Roberts (matt.roberts@uk.ibm.com), WS-Notification Architect and Development Lead, IBM

Matt RobertsMatt Roberts is the architect and development team lead for support of WS-Notification in WebSphere Application Server. He is an active member of the OASIS WS-Notification technical committee responsible for producing the WS-Notification specifications, and works both inside and outside IBM to promote adoption of WS-Notification. Matt has worked on the Service Integration Bus development team for the past five years, with responsibility for design and implementation of a range of components including the Publish/Subscribe Bridge (for pub/sub interoperability between SIB and WebSphere Businesss Integration Message Broker), Java™ Message Service (JMS), and topology and routing management. Before joining the SIB team, Matt worked in the WebSphere MQ JMS development team. You can contact Matt at matt.roberts@uk.ibm.com.



15 November 2006

What is the WS-Notification standard?

The WS-Notification specification provides a standards-based framework through which Web service applications can participate in publish and subscribe messaging patterns. The standards-based approach ensures that applications written by different vendors or teams can easily share information. Using Web services means that developers can write applications in a variety of languages, and on different software platforms.

The WS-Notification specification consists of the following documents:

Document namePurpose
WS-BaseNotification Defines the basic producer, consumer and subscriber roles that can be taken on by applications, and the interactions between them
WS-BrokeredNotification Defines the concept of a notification broker, which can act as a middle man between producer and consumer applications in order to help simplify the programming of producer applications, or provide value-add services
WS-Topics A stand-alone specification, which defines syntaxes for classifying events using a topic, and which can be leveraged by the other two specifications.

For more information on the WS-Notification standard, refer to the IBM Systems Journal article, "Events and service-oriented architecture: The OASIS Web Services Notification specifications", and the OASIS home page, referenced in the Resources section.


How is WS-Notification exposed in WebSphere Application Server?

You can use WS-Notification in WebSphere Application Server (hereafter called Application Server) in the following ways:

  1. Write a Web service application that uses the WS-Notification specifications by either:
    • Exposing a Web service endpoint that implements one or more of the port types defined by WS-Notification (such as NotificationConsumer).
    • Writing a Web service client application that invokes operations defined by WS-Notification on other services (such as Notify)

    Writing a Web service application that uses the WS-Notification specifications is exactly the same as writing any other Web service application. The first step is to obtain the WSDL for the service you want to expose (or in the case of a Web service client, the WSDL describing the operation you want to invoke). Once you've located the relevant WSDL, you can use Web service tools, such as WebSphere Application Server Toolkit V6.1, to generate the appropriate runtime artifacts from the WSDL, into which you can insert your business logic.

    For a step-by-step example of writing a simple application using the WebSphere Application Server Toolkit, see the IBM Redbook Web Services Handbook for WebSphere Application Server V6.1.

  2. Configure the Application Server to expose itself as a WS-Notification NotificationBroker endpoint that other applications can connect to, as described in the following section.

Configuring the Application Server to expose a NotificationBroker endpoint

Application Server Version 6 includes a built-in messaging provider called the service integration bus (SIBus), which provides publish/subscribe functionality to other server components and applications such as those written using the Java™ Message Service (JMS).

Application Server V6.1 provides an option that enables the administrator to expose a WS-Notification NotificationBroker that leverages the SIBus to provide the basic pub/sub functionality.

There are two advantages to configuring the server to expose itself as a NotificationBroker in this way:

  • A generic advantage of using a NotificationBroker interposed between a producer and a consumer application rather than communicating directly is that the broker is responsible for handling the complicated tasks of keeping records of subscriptions and matching notifications to the relevant subscriptions for delivery. This simplifies the logic that must be written for producer applications, which would otherwise have to handle these tasks themselves.
  • A specific advantage of using the server NotificationBroker is that it is simple to use the broker to enable WS-Notification applications to participate in pub/sub messaging patterns with other clients of the bus such as JMS, so event notifications published using WS-Notification can be consumed by JMS clients and vice versa.

There are three steps to configuring a simple set-up in which the Application Server exposes itself as a NotificationBroker:

  1. Step 1: Select the SIBus that will provide the underlying publish/subscribe functionality.
  2. Step 2: Select one or more servers that should expose a NotificationBroker endpoint to which applications can connect.
  3. Step 3: [Optional]. If you want to share notifications between WS-Notification and JMS, associate a WS-Notification topic namespace with a SIBus topic space.

Step 1: Select the SIBus

To expose the resources of a SIBus via WS-Notification, you need to configure a WS-Notification service.

  1. In the Application Server administrative console, select WS-Notification services in the Service integration section as shown in Figure 1:
    Figure 1. Select WS-Notification in the administrative console
    Figure 1. Select WS-Notification in the administrative console
  2. In the New WS-Notification Service dialog, select the SIBus bus you want to access with this WS-Notification service from the list in the Service integration bus name field, as shown in Figure 2. Note that before you can create a WS-Notification service, you must first have created a SIBus containing at least one bus member. For information on how to do this, refer to the Application Server Information Center topic Creating a bus.
  3. You can also specify a Name (which will form part of the URL for the Web service endpoints) and a Description for the WS-Notification service.
  4. For this example, leave the default settings for Enable dynamic topic namespaces and Requires registration.
    Figure 2. Create a new WS-Notification service
    Figure 2. Creating a new WS-Notification service

For more information about the options available when creating a WS-Notification service, refer to the Information Center topic Configuring WS-Notification using the administrative console.

You can also use the JACL or Jython scripting languages in wsadmin to do all the administrative actions in this article. For more information, refer to the Information Center topic Configuring WS-Notification resources through the command line.

Step 2: Select one or more servers on which to expose the NotificationBroker

Next determine which servers should expose a NotificationBroker by configuring one or more WS-Notification service points. There are two steps to this part of the configuration:

  1. In the Create a New WS-Notification Service Point dialog, specify a Name for the new service point.
  2. Select a server or cluster on which to expose the endpoint. Because of the way that the server NotificationBroker leverages the SIBus, the server, or cluster, must be a bus member for the bus with which the WS-Notification service is associated. Select the bus member from the list in the Select a bus member field, as shown in Figure 3. This field lists all of the existing bus members for the SIBus you chose in Step 1.
    Figure 3. Create a new WS-Notification service point
    Create a new WS-Notification service point
  3. Next, choose the binding type that applications will use to connect to the NotificationBroker (for example SOAP/HTTP or SOAP/JMS). This information is stored as part of an endpoint listener. You can select an existing endpoint listener or create a new one.

For more information about the options available when creating a WS-Notification service point, refer to the Information Center topic Configuring WS-Notification using the administrative console.

Step 3 [Optional]: Map from WS-Notification into the SIBus

This step is required only if you want to have close control over how WS-Notification maps into the SIBus world; for example, in order to share notifications with JMS applications, or configure topic-level security permissions.

If you want to share notifications between WS-Notification and JMS applications (or other clients of the SIBus), you must create a permanent topic namespace. This provides an association between the URI namespace, which is used to group topics in the WS-Notification world, and the name of the SIBus topic space destination that provides the equivalent concept in the SIBus world.

If you want only to share notifications among WS-Notification applications (and have checked the default option for Enable dynamic namespaces), you don't need to do this step because the server automatically provides support for the topic namespaces your applications use.

For more information about the options available when creating a WS-Notification service point, refer to the Information Center topic Configuring WS-Notification using the administrative console.

Figure 4. Configure a permanent topic namespace
Configure a permanent topic namespace

What sorts of applications can you write for WS-Notification?

You can write many types of applications using WS-Notification depending upon what you want to accomplish. The following list describes the types of applications you might want to write, and the advantages and disadvantages of each, along with the environments in which you can deploy them.

Applications to receive notifications:

  1. Receive notifications as soon as they are generated
  2. Receive notifications when the application is ready to request them
  3. Receive notifications in a lightweight device or environment
  4. Receive notifications from a producer inside a firewall
  5. Use an event notification to drive an existing or non-WS-Notification Web service

Applications to emit event notifications:

  1. Send notifications from a lightweight device or environment
  2. Send notifications as part of an application such as an EJB or MDB
  3. Expose a service from which other applications can connect in order to receive notifications
  4. Emit notifications only when there are other applications listening for the notifications
Application type A: Receive notifications as soon as they are generatedClient?Server?

Traditional message-oriented middleware provides two approaches for applications that want to receive notifications. Applications that want to receive notifications as soon as they are generated by the publisher use a mechanism that provides asynchronous delivery of events (the other option is synchronous delivery of events, and is described in Type B below). Asynchronous receipt in JMS is achieved by the application registering an implementation of the javax.jms.MessageListener interface.

In the WS-Notification world, the asynchronous delivery mechanism is exposed by a NotificationConsumer Web service port type that must be implemented by the consuming application (refer to Section 3 of the WS-BaseNotification specification). The NotificationConsumer port type defines a single operation Notify, which allows an array of notifications to be delivered to the consumer within a single Web service call.

In the WebSphere environment, Web service endpoints can be exposed only by deploying an appropriate enterprise application to the server container; for example, a JSR109 application that deploys the Web service into the Web container. The Java 2 Enterprise Edition (J2EE) application client environment does not support applications that want to expose an endpoint, so it's not possible to asynchronously consume notifications in the client container.

NoYes
Application type B: Receive notifications when the application is ready to request themClient?Server?

The second approach provided by message-oriented middleware for consuming of messages is synchronous receipt (in contrast to asynchronous receipt as described in Type A). In JMS this concept is embodied by an application calling one of the receive methods on a MessageConsumer.

In the WS-Notification world, synchronous receipt is provided by using a pull point (refer to Section 5 of the WS-BaseNotification specification). A pull point is a storage area for notifications that you can create by calling createPullPoint on a service that implements the CreatePullPoint port type (for example, the NotificationBroker provided in Application Server V6.1).

Once a pull point has been created, it can be passed in as the ConsumerReference of a Subscribe request sent to a NotificationProducer or NotificationBroker. This informs the producer/broker that notifications matching the new subscription should be stored in the pull point rather than being asynchronously delivered to the consumer application. At a later point, the consuming application can retrieve the notifications from the pull point using the GetMessages operation of the pull point.

The main advantage of this pattern is that it allows your application to choose the time at which it is ready to process notifications from the subscription - in the asynchronous case, the application is driven as soon as the notifications become available, which may not suit the programming model for some applications. As an example a (non-Web service) Enterprise Java Bean (EJB) application could use a pull point to receive notifications as part of an EJB method, possibly in response to some other processing carried out by the EJB.

Creating and interacting with a pull point requires only that the application be capable of invoking Web service operations on other services (and not expose any endpoint of its own). This means that pull points can be used by any Web service client technology, such as JAX-RPC stubs, which is capable of running in either the client or server environments.

YesYes
Application type C: Receive notifications in a lightweight device or environmentClient?Server?

Applications running in lightweight or resource-constrained environments are often unable to expose a NotificationConsumer Web service endpoint that can asynchronously receive notifications from a producer (as in Type A).

In order to work around this restriction, lightweight applications can use a pull point as described in Type B above; for example, using JAX-RPC stubs to interact with an appropriate provider of pull points.

Unfortunately, WS-Notification does not provide a mechanism by which an application running in a lightweight environment can receive notifications in an asynchronous fashion. It is the responsibility of the application to query the pull point when it is ready to consume notifications.

YesNo
Application type D: Receive notifications from a producer inside a firewallClient?Server?

In certain circumstances a consuming application may be running on the opposite side of a firewall from the producing application; for example, a client running on the internet that wants to receive notifications from a NotificationBroker provided by a company, and running inside its enterprise firewall.

In this scenario, it's usually possible for the consumer to call into the enterprise through the firewall, but not for the producer (NotificationBroker) to call out of the firewall back to the consumer. This prevents the standard pattern required in order to use asynchronous delivery of notifications from the producer to the consumer (that is, using a NotificationConsumer as in Type A).

Consuming applications that want to operate in this scenario are able to use pull points as described in Type B because the pull point pattern does not require any Web service invocations to be initiated by the producing app, only calls from the consumer to the producer or pull point.

YesYes
Application type E: Use an event notification to drive an existing or non-WS-Notification Web serviceClient?Server?

Most of the WS-Notification specification discusses how applications written for WS-Notification communicate with each other in order to send or receive event notifications. Another important class of applications is those existing applications that have no knowledge of the WS-Notification and that may already be participating in proprietary implementations of publish/subscribe style patterns.

WS-Notification defines a subscription policy called UseRaw (refer to Section 4.2 of the WS-BaseNotification specification), which instructs the NotificationProducer or NotificationBroker to provide the content of the notification message directly to the consuming application instead of wrapping it in the WS-Notification Notify element as would normally be the case.

The raw subscription approach means that a notification message can be used to invoke an operation on an existing (non-WS-Notification aware) Web service endpoint. This means that it's often possible to replace proprietary publish/subscribe implementations with a NotificationProducer (or NotificationBroker) that can do the required matching of notifications to consumers, while retaining the ability to invoke existing Web service endpoints.

Two conditions have to be satisfied in order for raw subscriptions to be successfully used:

  • The content of the notification message (that is, the top-level XML element of the message) must match an existing operation of the target Web service
  • Since the existing Web service application is unaware of WS-Notification a separate application must act as the Subscriber in order to set up the association between the producing application and the existing consumer.
NoYes
Application type F: Send notifications from a lightweight device or environmentClient?Server?

Many real world uses of publish/subscribe messaging involve information being collected from large numbers of remote devices and collated by a central intermediary, or broker, which interested parties can subscribe to in order to receive the aggregated data.

The sources of raw data are dependent upon the specific scenario, but might include weather sensors spread over a large geographical area, monitoring devices for an oil pipeline, or a series of network-attached printers that want to indicate when they have run out of paper.

In situations like this, the device is often resource constrained in some way; for example, it has limited processing power or intermittent network connectivity and is usually unable expose a Web service endpoint. Applications that want to emit event notifications under these conditions are able to use a Web service client (such as JAX-RPC stubs) to notify events to a consuming application such as a NotificationConsumer or NotificationBroker Web service. This approach can also be used for applications running in the WebSphere J2EE Application Client environment (launchClient).

YesNo
Application type G: Send notifications as part of an application such as an EJB or MDBClient?Server?

Sending event notifications from an existing application such as an EJB or servlet is very similar to the application described above for sending notifications from a lightweight environment. In both cases the application is acting as a client which invokes operations on a Web service endpoint exposed by another application. The same approach described above is suitable for fulfilling this requirement.

NoYes
Application type H: Expose a service from which other applications can connect in order to receive notificationsClient?Server?

The main actor of publish/subscribe messaging is an entity to which interested parties can subscribe in order to initiate the flow of notifications in which they are interested. In the WS-Notification world, this concept is embodied by an application that exposes a NotificationProducer endpoint (the port type for which defines the Subscribe operation - see Section 4 of the WS-BaseNotification specification).

The NotificationProducer is responsible for keeping track of subscriptions that have been created by subscribing applications (including managing their life cycle) and matching any notifications that are generated against the relevant subscriptions, then handling delivery of the notification to the consumer application. Additionally the NotificationProducer application must advertise the topics on which it can publish using the ResourceProperties defined in the WS-Notification specification.

In the WebSphere environment, a NotificationProducer application can be written as a Web service enterprise application (EAR file) that uses JSR 109 to define the Web service behavior.

NoYes
Application type I: Emit notifications only when there are other applications listening for the notifications Client?Server?

One of the disadvantages of the brokered pattern of notification common in message-oriented middleware (and exposed by WS-Notification) is that the producing application has no way of knowing whether there are any consumers listening for notifications that the producer might emit (because the broker separates the producers and consumers). This means that the producer can expend resources and effort to generate a notification and publish it to the broker, only to have the notification discarded because there are no consumers listening.

In certain scenarios this waste of effort can be very costly, such as where transmission of the notifications is financially costly (for example, transmission by satellite uplink) or detrimental to the operation of the sending device (where CPU cycles are limited and could be productively used for something else).

To address the problem, the WS-Notification specifications define the concept of a demand-based publisher (see section 4 of the WS-BrokeredNotification specification), a special variation of a NotificationProducer, which is informed by the NotificationBroker when there are active consumers for the notifications that the producer emits. The flow of logic in this pattern is as follows:

  1. The NotificationProducer registers with the NotificationBroker indicating the topic or topics about which it will publish notifications, and the fact that it wants to be a demand-based publisher.
  2. The NotificationBroker subscribes back to the NotificationProducer for the topics indicated by the producer.
  3. At any point during the lifetime of the registration, if the NotificationBroker has no active consumers for the specified topics, the subscription to the producer is paused. If there are active consumers, the subscription is resumed.
NoYes

Overview of the scenario

The scenario in this article takes you through each step of the process of extending an existing JMS-based enterprise to take advantage of WS-Notification in order to reach a wider market segment. The scenario illustrates many of the types of applications that we described above, and example application code that demonstrates the various application patterns.

Life before WS-Notification

MyQuoteBroker is an information broker that coordinates publishers of stock quote data and organizations that want to receive stock quote data. They operate a centralized server to which trusted partners are able to connect in order to provide and obtain stock information.

All the participants in the existing infrastructure use the JMS interfaces for the SIBus provided by Application Server V6.x to deliver and receive the stock information using a predefined topic hierarchy administered by MyQuoteBroker as shown in Figure 5:

Figure 5. The existing MyQuoteBroker scenario
The existing MyQuoteBroker scenario

MyQuoteBroker aggregates its stock quote information from two sources:

  • StockExchangeOne supplies most of the stock data from their J2EE server environment, and charges MyQuoteBroker per price update that is transmitted between the two companies. The range of symbols that StockExchangeOne provides data for is based on the agreement between the two companies, but the price update information is published regardless of whether any MyQuoteBroker's active clients are going to receive it.
  • PartnerOne supplies information on a small number of specialist symbols not covered by StockExchangeOne using a lightweight J2EE application client to connect to the MyQuoteBroker server. MyQuoteBroker pays a flat monthly subscription fee to receive these updates regardless of the quantity of data that is transmitted.

Clients of MyQuoteBroker connect to the MyQuoteBroker server in order to receive stock price updates on stock symbols that they are interested in. Currently there are two main mechanisms for implementing this pattern, as demonstrated by ClientOne and ClientTwo:

  • ClientOne has deployed a Message Driven Bean (MDB) to their application server, which is configured to connect to the MyQuoteBroker server and receive messages on the topic related to the stock symbol that they are interested in.
  • ClientTwo is a small business that does not have its own application server, so it uses a J2EE application client to make the connection. A JMS MessageListener is registered so that price updates are processed asynchronously.

The messages flowing through the system have the following structure:

Listing 1. Example of the MyQuoteBroker message format
<stockQuote>
  <symbol>
    IBM
  </symbol>
  <stockPrice>
    80.00
  </stockPrice>
</stockQuote>

The challenge

MyQuoteBroker wants to expand its client base by providing access to its service via a Web service interface, which will enable them to reach both non-Java and non-J2EE organizations, as well as existing J2EE enterprises that do not use JMS.

The CIO at MyQuoteBroker has decided that, rather than develop their own proprietary system for interfacing with Web service applications, they will use the open standards defined by the WS-Notification specifications. This will enable MyQuoteBroker to interact with other vendors in the marketplace who have already started down a similar path.

MyQuoteBroker has identified the following companies as being typical of the new market they want to address;

Figure 6. New opportunities for MyQuoteBroker
New opportunities for MyQuoteBroker
  • WSStockExchangeTwo provides a similar service to WSStockExchangeOne, except that they believe in using open standards at all levels of the enterprise. In particular, they don't expose their service using JMS because it requires all parties to be using the same JMS provider. They have chosen to expose their business service as a WS-Notification NotificationProducer application to which their customers can connect to receive prices updates
  • WSPartnerTwo is a smaller company that does not have the IT infrastructure to expose Web service endpoints publicly, but they are able to make Web service invocations against endpoints provided by the organizations with which they have contracts to supply data
  • WSClientThree exposes a WS-Notification NotificationConsumer application that can be connected, or subscribed to a source of events such as a NotificationBroker or a NotificationProducer
  • WSClientFour is committed to Web services as their preferred mechanism for receiving updates, however they have yet to examine the WS-Notification specifications. They expose a Web service interface, which expects to be given the price updates directly, rather than wrapped in the WS-Notification flavoring.
  • WSClientFive is another small business that does not have the infrastructure to expose a Web service endpoint, however they are still keen to use the WS-Notification standards to ensure that they are able to consume price updates from a variety of vendors using a single application.

The solution: WS-Notification

WS-Notification helps MyQuoteBroker in their aim of broadening their business market by providing an open standard for participating in publish/subscribe messaging patterns. Using an open standard makes it possible for the different organizations to write their applications to comply with the specification, and be confident that they will be able to interoperate with applications written by other vendors.

In particular the mechanism by which different applications communicate with each other at the wire level is standard (invoking the WS-Notification Web service operations results in a well-known SOAP message being sent over the requested protocol such as HTTP). This is an advantage over the JMS standard, which defines only a standard programming interface against which applications are written, and does not standardize the implementation of those interfaces, which means that implementations of JMS from different vendors are not normally able to communicate with each other.

A more tangible benefit to MyQuoteBroker is in their interactions with StockExchangeOne, where they are required to pay a fee for each stock quote that is transmitted between the two companies. Since WSStockExchangeTwo provides a NotificationProducer Web service, it's possible to register WSStockExchangeTwo as a demand-based publisher for the MyQuoteBroker server, and therefore, stock quotes need only flow between the two companies when one or more of the clients of MyQuoteBroker is listening to receive those quotes, saving MyQuoteBroker time and money.

WS-Notification also provides a mechanism called raw subscriptions that allows MyQuoteBroker to publish stock quote updates to customers like WSClientFour, who have not yet embraced the WS-Notification standard.


Install and run the example scenario: Life before WS-Notification

In this section we'll describe how to install and run the sample applications and scripts for the example scenario shown in Figure 5. In this initial situation, there are no WS-Notification applications configured - all the interaction between applications occurs using JMS messaging.

Before you begin

Before you can run the applications, complete the following steps:

  1. Install Application Server V6.1.
  2. Create a standalone Application Server profile. For the purposes of this article, we recommend that you configure the Application Server to run on the local machine with the default ports (that is, bootstrap port 2809, default host port 9080, and SIB endpoint 7276). If you use other ports, you'll need to edit the sample code. Refer to the Information Center topic Creating an Application Server profile for more information.
  3. Install the SDO repository as described in the InfoCenter topic Installing and configuring the SDO repository. In a development environment, you can use the createDb option to automatically configure the required database backend.
  4. Create a working directory to run the applications from. In this article, we'll assume a working directory of C:\developerWorks on a Windows platform. However you can also use any of the other operating systems supported by Application Server (such as Linux) by substituting an alternative working directory where appropriate.
  5. Optionally, install a development environment. If your Application Server profile is using the default ports as recommended above, you don't need to do this step, unless you want to use a development environment to view the sample application source code. If your profile uses non-default port numbers, you'll need to recompile the sample applications to take this into account.

    We recommend using the WebSphere Application Server Toolkit V6.1, which includes improvements over previous versions of the WebSphere development environments (including Rational Application Developer V6). Previous versions may cause problems when creating applications using port types from WS-Notification.

Step 1: Download resources

In the pre-WS-Notification part of the scenario, an application client EAR file is used to demonstrate the behaviour of both PartnerOne and ClientTwo. Two Jython scripts are provided to generate the necessary artifacts on the Application Server. These resources are provided in the Downloads section.

Download the following files to your working directory:

FileComments
WSN_Intro_JMS_Setup.pyScript to set up necessary JMS resources.
WSN_Intro_Common.pyScript containing library functions and definitions for use by WSN_Intro_JMS_Setup.py.
JMSClient.earJ2EE JMS pub/sub application. It has two modes of operation, enabling it to act as PartnerOne (publishing) or ClientTwo (subscribing/consuming), using messages containing stock price information.

The scripts and application enable you to run the pre-WS-Notification scenario shown in Figure 7. The scripts create a service integration bus, add the new server as a bus member, and create a topic space destination. They then create the TopicConnectionFactory and Topic objects that the JMS application will use to connect to the SIBus.

Figure 7. Relationship between the JMS application JMSClient.ear and the two JMS roles of publish and subscribe
Figure 7. Relationship between the JMS application JMSClient.ear and the two JMS roles of publish and subscribe

Step 2: Configure resources

In this step, you'll create the necessary JMS and SIBus resources on the Application Server.

  1. If your single server topology differs from a default topology running on localhost (that is, bootstrap port 2809, default host port 9080, and SIB endpoint 7276), edit the Jython library script WSN_Intro_Common.py to reflect the correct values. You can check the port numbers by loading the administration console for the server and drilling down to Servers, Application Servers, server1, Ports.
  2. From the bin directory of the Application Server V6.1 profile, run the configuration script (all on one line)

    wsadmin -conntype none -lang jython -f 
    c:\developerWorks\WSN_Intro_JMS_Setup.py -profile
    c:\developerWorks\WSN_Intro_Common.py

    This creates a bus and the necessary resources for JMS. In this simple application, messages are produced to and consumed from the topic with JNDI name jms/stockTopic. This topic is configured to use the physical topic stockTopic in the topic space dWTopicSpace on the SIBus dWBus.

  3. Restart the Application Server for the definition of the bus and JMS JNDI resources to take effect.
  4. [Optional] Import the application into the development environment by doing the following:
    • In Application Server Toolkit V6.1, switch to the J2EE perspective.
    • Select File => Import => EAR file.
    • Click Next and Browse to JMSClient.ear, then click Finish.
    This will enable you to examine the source code.

Step 3: Run the application

In this step, the application is used to demonstrate JMS technologies to disseminate stock information. The application is designed to work in one of two modes; either producing (publishing) stock information in order to simulate the PartnerOne enterprise, or consuming (via a subscription) stock information simulating ClientTwo. Two instances of the enterprise application are run, one in each of the JMS modes of produce and consume.

  1. Open two command prompts, and in each navigate to the bin directory of your Application Server profile (or another directory from which you can run the launchClient script).
  2. Shell 1 (PartnerOne): enter the following command:
    launchclient C:\developerWorks\JMSClient.ear produce

    Shell 2 (ClientTwo): enter the following command:
    launchclient C:\developerWorks\JMSClient.ear consume

Note: The application assumes an Application Server with a bootstrap port exposed at localhost:2809. Should the installation differ from this, you need to edit the Constants.java class in the utilities package to reflect the actual port details (visible under the appClientModule in the J2EE perspective of AST 6.1), as shown.

Figure 8. Source code for Constants.java
Figure 8. Source code for Constants.java

Step 4: Monitor the application output

In this step, we'll examine the output of the applications to confirm that pub/sub has been successful.

The application logs to the standard output stream of the environment in which it is running. You'll see that the producing application, PartnerOne, is publishing stock information, while ClientTwo will regularly poll its subscription, reporting the stock price when it successfully receives a stock message. Listing 1 and 2 show example output for the producer and consumer modes.

Note that the consumer does not receive messages until it has subscribed, and any publications that are sent before an active consumer is running are discarded by the SIBus. For the purposes of this simple application, it's important that both the producer and consumer roles are running concurrently.

The two applications will each run for around three minutes producing or consuming stock quotes before they terminate.

Listing 1. Sample output from the JMSClient in produce mode
> Using default hostname and port number.
> Hostname: localhost
> Port: 2809
> Mode selected: produce
> Initialising new JMS producer
> Configuration successful. Starting publishing cycle
> Publication 1: Stock price 100.01
> Publication 2: Stock price 100.02
> Publication 3: Stock price 100.03
> Publication 4: Stock price 100.04
> Publication 5: Stock price 100.05
Listing 2. Sample output from the JMSClient in consume mode
> Using default hostname and port number.
> Hostname: localhost
> Port: 2809
> Mode selected: consume
> Initialising new JMS consumer
> Configuration successful. Starting subscription polling cycle
> Listening...
> Got stock price: 100.01
> Got stock price: 100.02
> Got stock price: 100.03
> Got stock price: 100.04
> Got stock price: 100.05

Install and run the example scenario: Configure the WS-Notification infrastructure

In this section, you'll learn how to extend the configuration we did in the previous section to demonstrate some of the functionality offered by WS-Notification in the example scenario shown in Figure 6. In this situation, all interactions are through applications exploiting the capabilities offered by WS-Notification.

Before you can run the WS-Notification applications described here, make sure that the you have completed the steps in Before you begin.

Step 1: Download resources

In this scenario, two application client EAR files and a deployable Web service are used to demonstrate the behavior of WSPartnerTwo, WSClientThree, and WSClientFive. Two Jython scripts are provided to generate the necessary artefacts on the Application Server. All resources are provided in the Downloads section.

Download the following files to your working directory:

FileComments
WSN_Intro_WSN_Setup.pyScript to set up necessary WS-Notification resources.
WSN_Intro_Common.pyScript holding library functions and definitions for use by WSN_Intro_WSN_Setup.py.
WSNClient.earJ2EE WS-Notification client application. It has two modes of operation, enabling it to act as WSPartnerTwo (lightweight producer) or WSClientFive (lightweight consumer), sending or receiving the stock quote messages.

This J2EE application will be run in the client container; this environment does not support the exposure of a Web services endpoint; therefore the consumer side of the application is restricted to using pull points.

WebServiceAysncConsumer.earA Web application that acts as WSClientThree, exposing a NotificationConsumer Web service endpoint. In contrast to WSClientFive, notifications are consumed asynchronously. The delivery of notifications is initiated by the broker, unlike with a pull point where the consumer initiates the requests for messages.
ThirdPartySubscriber.earA J2EE client application that creates a subscription on behalf of WSClientThree. In contrast, WSClientFive makes its own subscription.
developerWorks_consumer.wsdlWSDL used to generate WebServiceAysncConsumer.ear. The Notify operation is invoked by the NotificationBroker when the latter wants to notify the consumer. In the simple implementation in WSN_AsyncConsumer.ear, the consumer application simply outputs information extracted from the notification to the Application Server log.

The WS-Notification set-up script creates a WS-Notification Service on the SIBus dWBus, and a WS-Notification service point on the server that uses the SOAP/HTTP transport. It then creates a permanent topic namespace object that associates the topic namespace http://dW.ibm.com with the topic space destination dW_TopicSpace that we created in the previous section. The WS-Notification applications listed above interact with the server through the WS-Notification Service as shown in Figure 9:

Figure 9. Relationship between the WS-Notification applications WSNClient.ear, WebServiceAysncConsumer.ear and ThirdPartySubscriber.ear
Figure 9. Relationship between the WS-Notification applications WSNClient.ear, WebServiceAysncConsumer.ear and ThirdPartySubscriber.ear

Step 3: Configure resources

In this step, you'll create the necessary WS-Notification resources on the Application Server. If you have completed the first part of the scenario, the JMS and SIBus resources required by this step are present.

  1. Ensure that the Application Server is started.
  2. From the bin directory of the Application Server V6.1 profile, run the configuration script (all on one line):
    wsadmin -lang jython -f c:\developerWorks\WSN_Intro_WSN_Setup.py 
    -profile c:\developerWorks\WSN_Intro_Common.py

    This creates the necessary resources for the WS-Notification scenario. A permanent topic namespace is created, which maps to the same topic space used in the earlier JMS sample.

    Note that when creating a WS-Notification service, it's not possible to run in -conntype none mode.

    The WS-Notification setup script also starts the new endpoint listener application that was created by the WS-Notification service point, which means that you don't have to restart the server at this point. With the exception of starting endpoint listener applications, all changes to WS-Notification configuration are reflected as soon as the configuration is saved, without having to restart the server.

  3. [Optional] Import the applications into the development environment, using the same procedure as outlined for importing JMSClient.ear, import the following J2EE applications into the development environment: WSNClient.ear, WebServiceAysncConsumer.ear and ThirdPartySubscriber.ear. Examine the source code. If all sample applications have been imported, the J2EE perspective of Application Server Toolkit will be similar to that shown in Figure 10.
    Figure 10. J2EE perspective view of the sample applications
    Figure 10. J2EE perspective view of the sample applications

Step 4: Install the asynchronous NotificationConsumer Web service

In this step, WebServiceAysncConsumer.ear is deployed on the Application Server.

  1. Open up a browser window, and log into the Application Server's administrative console.
  2. Select Install New Application from the Applications section of the task bar.
  3. Click Browse and navigate to the downloaded WebServiceAysncConsumer.ear sample code.
  4. Click Next and install the application, accepting all defaults.
  5. Save the configuration and start the newly deployed application WebServiceAsyncConsumer using the administrative console.
  6. Ensure that the application is correctly deployed and started by opening a new browser window, and entering the service's endpoint appended with ?wsdl as the URL. If you're using the default installation, the URL is:
    http://localhost:9080/WebServiceAysncConsumerProject/services/ developerWorks_consumerSOAP?wsdl.

    This displays the WSDL for the Web service in the browser windows, as shown in Figure 11:

    Figure 11. Test the deployed Web service: viewing the WSDL
    Testing the deployed Web service: viewing the WSDL

Note: The Web service is deployed assuming the default installation of Application Server. If you want to deploy against a server with a non-localhost host name or different port, you should regenerate the Java bean skeleton WSDL with a corrected soap:address location.

Step 5: Run the applications

In this step, the sample WS-Notification applications demonstrate the use of WS-Notification to disseminate stock information. In this scenario, different stock prices are used to distinguish the flow of information from the earlier JMS example.

We also demonstrate two different types of consumer application, showing synchronous and asynchronous receipt of notifications. A third party subscriber application is also used to subscribe on behalf of the deployed Web service consumer application.

  1. Open up three command prompts, and in each one navigate to the bin directory of your Application Server install (or another directory from which you can run the launchClient script).
  2. Shell 1 (WSPartnerTwo): Enter the following command:
    launchclient c:\developerWorks\WSNClient.ear produce

    Shell 2 (WSClientFive): Enter the following command:
    launchclient c:\developerWorks\WSNClient.ear consume

    Shell 3 (subscribing on behalf of WSClientThree): Enter the following command:
    launchclient c:\developerWorks\ThirdPartySubscriber.ear

Note: If you want to run these applications in an installation with non-default port assignments, you should edit the Constants.java class in the utilities package in each of the applications. You can determine the endpoints by viewing the WSDL associated with the services (that is, the service representing WSClientThree, or the services representing the Notification Broker. In the case of the latter, you can view these services by selecting Service integration => Web services => WS-Notification Services => dWWS-NotificationService and exporting the three sets of WSDL files from the broker, subscription manager, and publisher registration manager inbound settings, available in the Related Items section.

Step 6: Monitor the application output

In this step, we'll examine the output of the applications to confirm that notifications are flowing freely.

WSNClient.ear and ThirdPartySubscriber.ear log to the console. The latter should report no errors on attempting the subscribe, while the former application will log notifications produced (WSPartnerTwo) and consumed via a pull point (WSClientFive). In contrast, the deployed Web service application representing WSClientThree (WebServiceAsyncConsumer) logs to the application server's log.

The following listings show example output from the third party subscriber application, the WS-Notification client in produce and consume mode, and the asynchronous Web service consumer (server's log).

Note the consumer may report that it is "listening". This shows that the consumer has polled the pull point, but has found no notifications. This can happen if the subscription has not yet been made, and can also occur periodically as the consumer "races" the producer.

The WSNClient.ear producer and consumer each run for approximately 30 seconds before terminating, while the third party subscriber creates a subscription that expires after three minutes. Note that if you run the subscriber application twice within a given three minute period, the WebServiceAsyncConsumer running in the server may report receipt of duplicate publications, because two active subscriptions are delivering messages to the same consumer endpoint.

Listing 3. Sample output from the third party subscriber application
---------------------------------------------------------------------------------------
Usage: launchClient ThirdPartySubscriber.ear
---------------------------------------------------------------------------------------
> Broker endpoint   : http://localhost:9080/dWEPL/soaphttpengine/
	dWBus%2FdWWS-NotificationService
  	NotificationBroker%2FdWWS-NotificationServicePointNotificationBrokerPort
> Consumer endpoint : http://localhost:9080/developerWorks_WSN_
	AysncConsumerWeb/services/developerWorks_consumerSOAP
> Initialising new WS-Notification subscriber
> Set TopicExpression to: com.ibm.websphere.sib.WS-Notification.
	TopicExpression{topic=tns:stockTopic, 
  	dialect=http://docs.oasis-open.org/WS-Notification/t-1/TopicExpression/
	Simple,prefixMappings={tns=http://dW.ibm.com}, attributes={}} PT3M
> Subscription duration: 3 minutes.
> Third party subscription successful. Exiting client.
Listing 4. Sample output from the WS-Notification client in produce mode
---------------------------------------------------------------------------------------
Usage: launchClient WSNClient.ear produce|consume

For example, to produce: launchClient WSNClient.ear produce
             to consume: launchClient WSNClient.ear consume
---------------------------------------------------------------------------------------
> Broker Endpoint: http://localhost:9080/dWEPL/soaphttpengine/
	dWBus%2FdWWS-NotificationService
  	NotificationBroker%2FdWWS
	-NotificationServicePointNotificationBrokerPort
> Mode selected: produce
> Initialising new WS-Notification producer
> Set TopicExpression to: com.ibm.websphere.sib.WS-Notification.
	TopicExpression{topic=tns:stockTopic,
	dialect=http://docs.oasis-open.org/WS-Notification/t-1/
	TopicExpression/Simple, prefixMappings={tns=
  http://dW.ibm.com}, attributes={}}
> Configuration successful. Starting publishing cycle
> Publication 1: Stock price 200.01
> Publication 2: Stock price 200.02
> Publication 3: Stock price 200.03
> Publication 4: Stock price 200.04
> Publication 5: Stock price 200.05
> Publication 6: Stock price 200.06
> Publication 7: Stock price 200.07
Listing 5. Sample output from the WS-Notification client in consume mode.
---------------------------------------------------------------------------------------
Usage: launchClient WSNClient.ear produce|consume

For example, to produce: launchClient WSNClient.ear produce
             to consume: launchClient WSNClient.ear consume
---------------------------------------------------------------------------------------
> Broker Endpoint: http://localhost:9080/dWEPL/soaphttpengine/
	dWBus%2FdWWS-NotificationService
	NotificationBroker%2FdWWS-
	NotificationServicePointNotificationBrokerPort
> Mode selected: consume
> Initialising new WS-Notification consumer
> Set TopicExpression to: com.ibm.websphere.sib.WS-Notification.
	TopicExpression{topic=tns:stockTopic,
	dialect=http://docs.oasis-open.org/WS-Notification/t-1/
	TopicExpression/Simple, prefixMappings={tns=http://dW.ibm.com}, 
	attributes={}}
> Configuration successful. Starting subscription polling cycle
> Listening...
> Got stock price: 200.03
> Got stock price: 200.04
> Got stock price: 200.05
> Got stock price: 200.06
> Listening...
Listing 5. Sample output from the asynchronous Web service consumer (server's log)
[31/08/06 10:52:31:412 BST] 00000034 SystemOut	 
	O Notification 1 of 1: Got stock price: 200.01
[31/08/06 10:52:32:526 BST] 00000034 SystemOut 		
	O Notification 1 of 1: Got stock price: 200.02
[31/08/06 10:52:33:720 BST] 00000034 SystemOut     
	O Notification 1 of 1: Got stock price: 200.03
[31/08/06 10:52:34:994 BST] 00000034 SystemOut
	O Notification 1 of 1: Got stock price: 200.04
[31/08/06 10:52:36:259 BST] 00000034 SystemOut
	O Notification 1 of 1: Got stock price: 200.05
[31/08/06 10:52:37:463 BST] 00000034 SystemOut	
	O Notification 1 of 1: Got stock price: 200.06
[31/08/06 10:52:38:678 BST] 00000034 SystemOut
	O Notification 1 of 1: Got stock price: 200.07

Note that for the asynchronous consumer, multiple notifications may be wrapped in a single publish from the notification broker. In this example, notifications are delivered singly, as they are limited by the rate at which the WS-Notification client producer is publishing to the notification broker.


Install and run the example scenario: Interoperation between WS-Notification and JMS

In this section, you'll see how the applications presented for the two scenarios interoperate transparently. By using common infrastructure in the Application Server, producers and consumers are able to interact, regardless of whether they use the existing JMS technologies or leverage the capabilities provided by WS-Notification.

Step 1: Run the applications

In this example, interoperation is demonstrated between an existing JMS producer (PartnerOne), a WS-Notification producer (WSPartnerTwo), and a WS-Notification consumer (WSClientFive).

  1. Open up three command prompts, and in each navigate to the bin directory of your Application Server profile (or another directory from which you can run the launchClient script).
  2. Shell 1 (JMS: PartnerOne): Enter the following command:
    launchclient c:\developerWorks\JMSClient.ear produce

    Shell 2 (WS-N: WSPartnerTwo): Enter the following command:
    launchclient c:\developerWorks\WSNClient.ear produce

    Shell 3 (WS-N: WSClientFive): Enter the following command:
    launchclient c:\developerWorks\WSNClient.ear consume

Step 2: Monitor the application output

In this step, we'll execute the applications together to confirm that interoperation between WS-Notification and JMS clients is successful.

All applications log to the console. You'll see that the WS-Notification consumer receives stock information from both the JMS producer (unit price: ~ 100) and the WS-Notification producer (unit price: ~ 200).

Note: You can also demonstrate that the JMS consumer (ClientTwo) can successfully receive stock price information from both the JMS and WS-Notification producers.

Listings 7, 8, and 9 show example output from the JMS producer, the WS-Notification producer, and the WS-Notification consumer.

Listing 7. Sample output from the JMS producer
> Using default hostname and port number.
> Hostname: localhost
> Port: 2809
> Mode selected: produce
> Initialising new JMS producer
> Configuration successful. Starting publishing cycle
> Publication 1: Stock price 100.01
> Publication 2: Stock price 100.02
> Publication 3: Stock price 100.03
> Publication 4: Stock price 100.04
> Publication 5: Stock price 100.05
> Publication 6: Stock price 100.06
> Publication 7: Stock price 100.07
> Publication 8: Stock price 100.08
> Publication 9: Stock price 100.09
> Publication 10: Stock price 100.10
> Publication 11: Stock price 100.11
> Publication 12: Stock price 100.12
> Publication 13: Stock price 100.13
> Publication 14: Stock price 100.14
> Publication 15: Stock price 100.15
> Publication 16: Stock price 100.16
> Publication 17: Stock price 100.17
> Publication 18: Stock price 100.18
Output 8. Sample output from the WS-Notification producer
---------------------------------------------------------------------------------------
Usage: launchClient developerWorks_WSNClient.ear produce|consume

For example, to produce: launchClient developerWorks_WSNClient.ear produce
             to consume: launchClient developerWorks_WSNClient.ear consume
---------------------------------------------------------------------------------------
> Broker Endpoint: http://localhost:9080/dWEPL/soaphttpengine/
	dWBus%2FdWWS-NotificationService
	NotificationBroker%2FdWWS-NotificationServicePointNotificationBrokerPort
> Mode selected: produce
> Initialising new WS-Notification producer
> Set TopicExpression to: com.ibm.websphere.sib.WS-Notification.TopicExpression
	{topic=tns:stockTopic,
	dialect=http://docs.oasis-open.org/WS-Notification/t-1/TopicExpression/
	Simple,prefixMappings={tns=
  http://dW.ibm.com}, attributes={}}
> Configuration successful. Starting publishing cycle
> Publication 1: Stock price 200.01
> Publication 2: Stock price 200.02
> Publication 3: Stock price 200.03
> Publication 4: Stock price 200.04
> Publication 5: Stock price 200.05
> Publication 6: Stock price 200.06
> Publication 7: Stock price 200.07
> Publication 8: Stock price 200.08
Output 9. Sample output from the WS-Notification consumer, demonstrating input from both JMS and WS-Notification producers
---------------------------------------------------------------------------------------
Usage: launchClient WSNClient.ear produce|consume

For example, to produce: launchClient WSNClient.ear produce
             to consume: launchClient WSNClient.ear consume
---------------------------------------------------------------------------------------
> Broker Endpoint: http://localhost:9080/dWEPL/soaphttpengine/
	dWBus%2FdWWS-NotificationServiceNotification
	Broker%2FdWWS-NotificationServicePointNotificationBrokerPort 

> Mode selected: consume
> Initialising new WS-Notification consumer
> Set TopicExpression to: com.ibm.websphere.sib.WS-Notification.
	TopicExpression{topic=tns:stockTopic,
	dialect=http://docs.oasis-open.org/WS-Notification/t-1/TopicExpression/
	Simple, prefixMappings={tns=http://dW.ibm.com}, attributes={}}
> Configuration successful. Starting subscription polling cycle
> Listening...
> Got stock price: 100.15
> Got stock price: 200.05
> Listening...
> Got stock price: 100.16
> Got stock price: 200.06
> Got stock price: 100.17
> Got stock price: 200.07
> Got stock price: 100.18
> Got stock price: 200.08

Summary

This article introduced you to WS-Notification and how it is exposed in WebSphere Application Server V6.1. First, we gave you a bit of background about WS-Notification and described how WS-Notification is exposed in Application Server V6.1 and the three basic steps to configuring the Application Server to act as a NotificationBroker.

We talked about the different types of tasks an application writer might want to accomplish in the context of WS-Notification, and the types of environments in which these application types can be deployed.

Next, we introduced the MyQuoteBroker scenario and described how the MyQuoteBroker company can use WS-Notification to grow their business by reaching out to a larger market segment through adoption of open standards.

Finally, we walked through example scripts and applications (including source code) that demonstrate how to configure WS-Notification and write many of the types of applications discussed. We stepped through the process of installing and running the samples in order to see WS-Notification in action, including the ability to pass messages seamlessly between clients written using WS-Notification and other clients of the service integration bus such as JMS.

We hope you've found this article useful, and that we've piqued your interest in using WS-Notification in your enterprise.


Downloads

DescriptionNameSize
Utility functions for JMS and WS-N resourcesWSN_Intro_Common.py10KB
Script for configuring JMS resourcesWSN_Intro_JMS_Setup.py3KB
Script for configuring WS-Notification resourcesWSN_Intro_WSN_Setup.py4KB
Sample application for JMS pub/subJMSClient.ear17KB
Sample WS-Notification application clientWSNClient.ear405KB
Sample NotificationConsumer Web serviceWebServiceAysncConsumer.ear78KB
Sample third party subscriber applicationThirdPartySubscriber.ear398KB
Sample WSDL file for a NotificationConsumerdeveloperWorks_consumer.wsdl3KB

Resources

Learn

Get products and technologies

Comments

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 WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere, SOA and web services
ArticleID=171462
ArticleTitle=WS-Notification in WebSphere Application Server Version 6.1
publish-date=11152006