WS Notification and WS Topics in the WS Resources Framework
This article continues our discussion of the WS-Resource Framework, a set of proposed standards that formalizes the relationship between Web services and state. In this part, the third of a multi-part series, we cover the use of notifications and topics. It is excerpted from chapter 8 of the book Building Web Services with Java: Making sense of XML, SOAP, WSDL, and UDDI, written by Steve Graham et al. (Sams; ISBN: 0672326418).
WS Notification and WS Topics in the WS Resources Framework - Subscribing for Notification (Page 2 of 6 )
When we reviewed the basic notification consumer and notification producer roles, we explained that notification consumers register their interest in receiving notifications. This is done with a subscribe operation. The subscribe operation is provided by any notification producer to allow other entities to register interest in receiving notifications it produces.
There is an additional subtlety that we haven't yet described. WS-Notification defines an additional role: a subscriber. A subscriber is an entity that actually does the registration—that is, it invokes the subscribe operation. Many times, the subscriber and the notification consumer are the same entity. However, in many situations the subscriber role and the notification role are played by different entities. For example, the Web service that places a PurchaseOrder (by invoking the doSubmission operation on the POSubmissionportType) might subscribe for changes in the status of the PurchaseOrder (because it has the relationship with the Purchase Order service), but it may indicate that a separate inventory management system is the notification consumer. The most general form of the roles related to notification registration is depicted in Figure 8.3.
Figure 8.3 Subscriber's role in notification
Four types of information can be found within a subscribe request:
Where is the location of the notification consumer that will receive the notification messages?
What is the situation of interest?
Should all the related notification messages be sent, or just a subset of them?
Do any other constraints or policies govern the circumstances under which notification messages should be sent to the notification consumer?
Let's examine these components of a subscribe request that The Skateboard Warehouse might send to a PurchaseOrder WS-Resource. In this case, The Skateboard Warehouse is interested in receiving notification when the status resource property of the PurchaseOrder changes. Because the POPortType (the interface of the Web service that SkatesTown provides for customers to access PurchaseOrder WS-Resources) has been extended with the notification producer operations, The Skateboard Warehouse can use the endpoint reference to its PurchaseOrder WS-Resource to subscribe for changes on that PurchaseOrder. Here is an example SOAP message to subscribe one of The Skateboard Warehouse's Web services to receive notification messages:
This example subscribe request registers a service available at http://www.skateboardwarehouse.com/services/ inventoryManagement to be a notification consumer for notification messages produced by the Purchase Order service, related to the PurchaseOrder WS-Resource indicated in the poRP:POResourceID SOAP header (following the implied resource pattern).
The actual location of the notification consumer is identified by the ConsumerReference element in the subscribe request message. This component is an endpoint reference; it could be a WS-Resource–qualified endpoint reference or any other kind of endpoint reference. In this case, the lack of a ReferenceProperties element indicates that it isn't a WS-Resource–qualified endpoint reference. This component addresses the first kind of subscription information: Where is the notification consumer?
The second component, TopicPathExpression, indicates the situation of interest. The topic expression is the heart of the subscription; it specifies which subset of all the notification messages produced by the notification producer is of interest to the subscriber. This component can come in different dialects that can be as simple as a qualified name (as shown in this example) or as complex as a path-based expression language that includes subtopics, wildcards, and so on. (We'll examine the topic expression dialects a little later, in the section "Topics and Topic Spaces.")
In this particular example, the subscriber is indicating that the topic named poPR:status is of interest to this subscription. Any message associated with that topic should be forwarded to the notification consumer. How does a subscriber know which topics are supported by a given notification producer? The subscriber can examine the topics resource property of the notification producer, as we'll describe in the section "Resource Properties of a Notification Producer."
A subscription request can have components in addition to the ones we've shown in this example. These components are summarized in the following list:
ConsumerReference—Identifies the notification consumer: the Web service that will receive the notification message associated with the situations of interest described by the subscription.
TopicExpression—Identifies which topic or topics are of interest to the subscriber. The topic expression is associated with a dialect that describes the contents of the topic expression. The purpose of a TopicExpression is to describe a collection of zero or more topics. Each notification message associated with topic(s) identified by this expression will potentially be sent to the notification consumer.
UseNotify—Specifies whether the "raw" notification message is sent to the notification consumer, or whether the message is wrapped in such a way as to invoke the Notify operation of the notification consumer. If this component is absent, the notification producer will invoke the Notify operation on the notification consumer.
Precondition—An expression that is evaluated against the notification producer. This condition must be true before notification messages on this subscription are sent to the notification consumer. One example use of this component is to specify a Boolean XPath expression to be evaluated against the resource properties of the notification producer. This is one way of subsetting the notification messages to be sent to the notification consumer.
Selector—An expression that is evaluated against each notification message associated with the subscription. This expression acts like a filter; when the expression is evaluated against a notification message and the evaluation results in a Boolean false, then that notification message isn't sent to the notification consumer.
SubscriptionPolicy—A policy statement, such as a WS-Policy element, that allows the subscriber to associate policies to govern the subscription. This element could be used to specify that notification messages should be batched (in groups of five messages for example) and sent in bulk. Other sorts of policy assertions could include a message rate (no more than five messages per second, for example). There is work to be done by the WS-Notification policy team to specify a notification discipline–specific policy grammar.
InitialTerminationTime—An initial request for how long the subscription should last. This component requests the initial setting of the TerminationTime resource property defined in the WS-ResourceLifetime specification (see the section "Resource Lifetime").
If the subscribe request is accepted by the notification consumer, a subscription is set up that associates the notification producer and the notification consumer under the conditions specified by the components of the subscribe request. To record this association, a new WS-Resource is created: a Subscription WS-Resource. A WS-Resource–qualified endpoint reference to the subscription resource is returned to the subscriber in response to the subscribe request. Therefore, you can regard the subscribe request as a WS-Resource factory.
As you'll see when we examine the Subscription WS-Resource in more detail in the next section, the Subscription WS-Resource allows the subscriber to manage the subscription, including making modifications to the components of the subscription and maintaining the lifetime of the subscription.