The DSB implements and provides Web service notifications support as defined in the OASIS WSN specifications. It focuses on Web service Base Notification, Web service Topics and Web service Resources.

The current section describes how it is implemented and how it can be used by clients.

High level Architecture

The WSN library used to provide WSN support is described here. This library provides all the basic features needed to provide a simple and efficient notification support in any runtime. The DSB provides two different WSN implementations, the first one is provided by a DSB component (Petals JBI component) and the second one is a native WSN support inside the DSB kernel.

Sequence description

• Step 1: Interested parties subscribes to some notification by sending a WSN Subscribe message to the DSB Notification Producer interface. The information needed is the Topic name and the endpoint reference which will be in charge of receiving WSN notification messages when new messages are posted to the specified topic.
• Step 1' : The Notification producer forward the subscribe request(s) to the core engine hosted somewhere in the DSB. When the notification engine receives the subscribe message, it stores all the information needed to contact the subscriber when new messages will be available.
• Step 2 and 3 : A notification consumer client sends a notifiction message to the Notification Consumer interface. This message is automatically sent to the Notification engine.
• Step 4 : The notification engine detects that there are some actors which are interested in notifications posted in the given topic. The Notification engine selects an endpoint to send message to. This selection is possible since all the required information has been stored in Step 1' i.e. if the subscriber is a Web service, the notification automatically detects that the notification MUST be sent using the SOAP connector. Based on that deduction, the Notification engine will send the message to right 'protocol binding' component and not directly. This is a key point of the DSB integration: the message will be routed to a DSB service which is able to send the message to the notification subscriber in the right format and protocol i.e. the notification engine is transport and protocol independent.
• Step 4' : The Protocol binding forward the notification message to the subscriber.

Implementations

DSB component

A specific DSB component is in charge of the WSN stuff. It embeds the core notification engine and expose interfaces defined in WSN such as:

• NotificationProducer: Subscribe and GetCurrentMessage operations support. Allows to Subscribe to notifications i.e. a client send a Subscribe message with an endpoint reference interested in receiving some notifications. The notification the subscriber is interested in are classified into a WSN Topic and is specified in a Subscribe message element.
• NotificationConsumer: Notify operation support. The component can receive notification messages through the Notify operation. When the client sends a notify message on a Topic, the notification engine will select all the subscribers which are interested in receiving messages for the given topic and sends notification message to all interested parties. By using the DSB, you do not have to care about the transport to use to send notifications to subscribers, it is up to the DSB to route the message to the right services with the right transport and protocol.

There are some additional interfaces which are exposed and which allows to manage resources such as WS Topics:

• NotificationProducerResourceProperty. Resources are used to manage topics. With this interface you can get, modify supported topics, ... Supported Resources calls are:
  • TopicSet : Get the list of topics
  • FixedTopicSet : check if the topic set if fixed or not
  • TopicExpression : Get the topic expression list
  • TopicExpressionDialect : Get the list of topic dialects

The endpoints provided by this component are automatically exposed by the DSB at startup and are available by default at:

• http://localhost:8084/petals/services/NotificationProducerPortService?wsdl
• http://localhost:8084/petals/services/NotificationConsumerPortService?wsdl

This means that all calls to these endpoints will be forwarded to the notification engine, independently to its node location.

DSB service 

A WSN engine is also embedded as a core kernel service. Other kernel services are able to use this WSN engine to subscribe to topics, send notifications, ... directly with the Java APIs defined in module dsb-kernel-pubsubservice.

Additionally, the WSN engine is exposed by the DSB at startup as Web services and provides the same features listed in the previous section (DSB component) at the following URLs:

• http://localhost:7600/petals/ws/NotificationProducer
• http://localhost:7600/petals/ws/NotificationConsumer

Java services

The WSN support is not only for external stuff. We can also use the DSB kernel features to register Java classes as listeners and send notifications directly from Java code. It is explained in the extensions sections.

Using notifications

XML Payloads

In this section we describe the payloads of the WSN messages supported by the DSB. If you do not use the Java clients listed below, be sure to manipulate the messages in the right way to retrieve required data.

Subscribe

SubscribeResponse

Unsubscribe

XML clients

In this part, we describe how notifications can be used with SOAP client and services. As an example, just think that all external actors are SOAP ones in the architecture figure above. This really simple sample is composed of several external actors : Some WS notification subscribers which will receive notifications they are interested in; A notification producer which will be in charge of sending notifications to a topic and the DSB which will route notification messages to the right notification subscribers.

It is important to note that in the DSB, the notification engine is a core service a so is automatically exposed as Web service by the SOAP connector. But, even if we only use Web services in this sample, we can also have DSB service clients which directly send subscribe and notify messages to the DSB WSN endpoint itself.

A code sample is available at https://svn.petalslink.com/svnroot/trunk/research/commons/dsb/samples/dsb-wsn-sample/src/main/java/org/petalslink/dsb/sample/wsn/Main.java

It uses Web service clients to send subscribe and notify messages; service exposed with the help of CXF to receive notifications; and the DSB as notification broker.

Simple HTTP Clients

There are also some simple Java clients available which allows the developer to bypass the XML manipulations and directly access to the useful information such as subscription ID, topic, EPR...:

The HTTP clients are available in the Maven dependency org.petalslink.dsb:dsb-notification-httpclient.

In order to unsubscribe, you need to give the UUID returned by the original subscribe request. There is no way for now to retrieve these UUIDs from any API, so be sure to manage them on the client side.

Configuration

The notification configuration files are located under $DSB/conf/ folder. You can configure kernel and business services level from these configuration files.

conf/topics/*-topicset.xml

Describes the topicsets supported by the notification engine. For example:

You can configure topic sets for :

• kernel service in the kernel-topicset.xml file
• business services in the business-topicset.xml file

conf/notification.cfg

The default configuration file for the notification engine. Provides a way to define the engine internal endpoint/interface/service values. For example:

You do not have to change this file

conf/subscribers.cfg

This file allows to create subscribers at DSB startup. All the subscribers defined in this file will be automatically added as subscribers in the notification engine and so will receive notifications when some notifications are published in the associated topics.

For example:

In the previous snippet, the subscriber0 will receive notifications on _http://localhost:9000/services/RawService_ when a message is published in the topic DSBTopic (+ topic URI and Prefix).

Note that you can add several subscribers using the same format, just change the prefix (subscriber0) in order to be unique in the file.

You can use CSV values in the consumerReference value if these subscribers need to subscribe to the same topic.

conf/consumer.cfg

This file allows the DSB to automatically subscribes to notifications at startup and so to receive notifications when they are published in the associated topics. Note that it is also possible to subscribe on behalf of others just by setting a consumerReference which is not the DSB.

With such configuration, a subscribe message will be sent to http://localhost:9000/services/RawService and the consumer reference (the one which will receive notifications) will be http://localhost:9000/services/RawService111.