1 Introduction
This document, Web Services Eventing Primer, provides an introductory description of the Web Services Eventing protocol and should be read alongside the formal description contained in the WS-Eventing [WS-Eventing] specification.
This non-normative primer describes when and how the WS-Eventing specification might be used by applications that require a standard mechanism for subscribing to a series of notifications about a set of external events.
This document assumes a basic understanding of XML 1.0, Namespaces in XML, WSDL 1.1 and SOAP.
This document begins by describing WS-Eventing usage scenarios and actors. Subsequent sections introduce the features of the WS-Eventing protocol and describes these features in the context of concrete examples.
2 Yet Another Eventing Spec
If there is one thing that most readers can probably agree on, it is that the IT industry does not need yet another pub/sub specification. Multiple, mature queuing and publish/subscribe technologies have existed in the marketplace for some time. Each of these technologies has their strengths and weaknesses, their suitability to particular domains, and a significant body of architectural, developmental and operational experience behind them. So what is the point of WS-Eventing?
Like many popular concepts in IT, the terms "pub/sub", "eventing", etc. have many different meanings, each with its own context. One aspect of the term "eventing" is its sense as a programming design pattern (also referred to, more formally, as "the Observer pattern" [Observer]). Essentially, WS-Eventing describes an interoperable implementation of the eventing design pattern using SOAP-based messaging technologies. It is primarily a SOAP specification, and secondarily an eventing specification. The design of WS-Eventing does not seek to break new ground in terms of functionality, performance, or flexibility. Rather it allows those who choose to use SOAP-based technologies access to a standard, interoperable API for implementing a popular and useful design pattern.
You might consider using WS-Eventing if one or more of the following applies to you:
- Your organization has standardized on the use of SOAP as an interoperable messaging framework or your solution will need to integrate with SOAP-oriented services such as service buses, security gateways, etc.
- Your solution seeks to leverage other SOAP-based technologies such as WS-Security or WS-MakeConnection.
- Your programmers are familiar/comfortable with SOAP-oriented tools and technologies such as WSDL-based code generators, SOAP APIs (such as JAX-WS), and SOAP-oriented IDE frameworks (such as the Eclipse Web Services Tools).
You might consider using something other than WS-Eventing if one or more of the following applies to you:
- Your solution requires a "true" publish/subscribe architecture in which the event sink and event source are decoupled through the use of intermediaries, topics, etc.
- Your solution has stringent performance requirements in either the notification rate or the number of subscribers.
3 Actors
The following figure is a block diagram of the main actors in WS-Eventing. The individual boxes represent logical components, not physically deployed entities. The location and organization of these components has been purposely left unconstrained by WS-Eventing. So, for example, it is possible for the Event Source and the Subscription Manager to co-reside within the same process. Nevertheless, from the perspective of the specification and for the purposes of this primer, these components are regarded as separate entities.
3.1 Subscriber
The Subscriber is responsible for managing the lifecycle of a Subscription from a consumers perspective. It performs the following basic activities:
- Initiates the creation of a Subscription by sending a Subscribe message to the Event Source.
- Fetches the current status of the Subscription by sending a GetStatus message to the Subscription Manager.
- Updates the expiration time of the Subscription by sending a Renew message to the Subscription Manager.
- Cancels the Subscription by sending a Unsubscribe message to the Subscription Manager.
3.2 Event Sink
The Event Sink is the consumer-side component responsible for receiving and processing Notifications. A key aspect of the mapping of the eventing design pattern to the SOAP messaging framework is that Event Sinks are modeled as SOAP receivers [SOAP Part 1].
3.3 Event Source
The primary responsibility of the Event Source is servicing Subscribe requests. Despite what its name suggests, the Event Source should not be thought of as "the source of events". Although it is possible that the process that implements the Event Source might also be responsible for transmitting Notifications to Event Sinks, WS-Eventing does not mandate this constraint; Notifications can originate from anywhere.
The processing of Subscribe requests entails a form of "hand off" from the Event Source to the Subscription Manager. The target of the Subscribe request is the endpoint of the Event Source, but the SubscribeResponse message contains an endpoint reference (EPR) to the Subscription Manager for the newly created Subscription.
3.4 Subscription Manager
The Subscription Manager is responsible for managing the lifecycle of a Subscription from the service perspective. It performs the following basic activities:
- Servicing GetStatus, Renew, and Unsubscribe messages.
- Monitoring the collection of active Subscriptions and cleaning up/deleting those that have expired or, for whatever reason, are no longer deemed to be viable.
Note that there is an implied but unspecified interface between the Subscription Manager and the components that transmit Notifications to the Event Sinks (which, as was mentioned before, may or may not include the component that implements the Event Source). For example, when a Subscription Manager successfully process a Unsubscribe message, the result is to cease transmitting Notifications to the Event Sink for that Subscription. In order for this to happen, the Subscription Manager needs to have some way of communicating with the components that emit Notifications for that Subscription. This interface is not specified in WS-Eventing because, within the context of the architecture of WS-Eventing, it represents an implementation detail that does not affect interoperability.
4 Subscriptions and their Properties
A Subscription is an agreement between the Subscriber and the Event Source/Subscription Manager to affect the transmission of Notifications to the Event Sink. This agreement is binding for the lifetime of the Subscription. The behavior and nature of the Subscription are affected by the properties described below.
4.1 Identity
Unlike specifications such as WS-ReliableMessaging [WS-ReliableMessaging], WS-Eventing does not identify Subscriptions with a discrete element like a "sequence ID" (wsrm:Identifier). Instead it uses the wse:SubscriptionManager endpoint reference (EPR). As the spec states, this EPR is "the EPR of the Subscription Manager for this Subscription" but, in this case, it is useful to keep in mind that every Subscription has its own, logical Subscription Manager. While it is true that all the Subscription Managers created by a Event Source may share certain characteristics (i.e. their endpoint URI) and code, nevertheless they are separate, logical entities.
The following are some examples of Subscription Manager EPRs.
<wse:SubscriptionManager>
<wsa:Address>
http://www.example.org/cetatrack/SubscriptionManager?id=28
</wsa:Address>
</wse:SubscriptionManager>In the above example the EPR is "made unique" via the use of a query string in the wsa:Address URI.
<wse:SubscriptionManager>
<wsa:Address>
http://www.example.org/cetatrack/SubscriptionManager
</wsa:Address>
<wsa:ReferenceParameters>
<ctx:id>28</ctx:id>
</wsa:ReferenceParameters>
</wse:SubscriptionManager>In the above example the EPR is made unique via the use of a "ctx:id" element as a reference parameter.
Either of these techniques, in addition to others not covered here, are valid mechanisms for identifying the Subscription and its Manager. Note that the semantics defined by WS-Addressing prevent the Subscriber from infering anything about the "id" of the Subscription (for example, that its value is "28"). Instead the Subscriber must simply treat the wse:SubscriptionManager EPR as an opaque reference in any future GetStatus, Renew, or Unsubscribe requests.
As we will see next section, the fact that a Subscription is identified by an EPR that references its Subscription Manager has some interesting consequences in the area of Subscription lifecycle management.
4.2 Lifecycle States
Subscriptions do not have "states" per se; they either exist or they don't exist. Though the spec speaks of "active subscriptions" there is no such thing as the corollogical "inactive subscription". Once a subscription expires or is otherwise cancelled, it simply ceases to exist. This means that there are circumstances in which a Subscriber's wse:SubscriptionManager EPR can refer to an endpoint that no longer exists. This impacts the exception-handling logic of the Subscriber.
For example, suppose a Subscriber creates a Subscription with a certain expiration time. Suppose the Subscriber allows the expiration to pass without performing a Renew request. Subsequent to this time passing, the Subscriber attempts a GetStatus request using the SubscriptionManager EPR. There are a number of things that could happen at this point:
- The SOAP node listening at the Subscription Managers address could respond with a wse:UnknownSubscription fault.
- The SOAP node listening at the Susbscripton Managers address could respond with "some other" SOAP fault indicating that it was unable to process the request.
- The underlying HTTP layer could respond with an error code such as a "404 Not Found".
- The underlying HTTP layer could generate an exception stemming from the inability to connect to the address in the SubscriptionManager EPR.
4.3 Delivery Mechanism
One of the key extension points of the WS-Eventing spec is the notion of the Delivery Mechanism. A Delivery Mechanism defines how Notifications are conveyed from their source to the Event Sink. The intent of this extension point is to allow implementations to extend WS-Eventing to support other, possibly non-SOAP based, transmission mechanisms. This extension point could also be used to support brokered Notifications.
The WS-Eventing spec defines a single Delivery Mechanism in which Notifications are transmitted as SOAP messages in a one-way exchange pattern. The key attribute of this Delivery Mechanism is the wse:NotifyTo EPR which references the endpoint to which Notifications are to be transmitted.
It should be noted that the extensibility provided by the Delivery Mechanism and the extensibility provided by the NotifyTo EPR overlap to a degree. A good example of this is the issue of "pulling" Notifications for non-addressable Event Sinks (i.e. Event Sinks that lie behind a firewall or NAT and are therefore unable to accept incoming connections). One choice would be to create a new WS-Eventing Delivery Mechanism that defined a "Pull" request on the Subscription Manager interface, etc. The other choice would be to leverage the extensibility of wse:NotifyTo/wsa:Address to indicate the use of WS-MakeConnection [WS-MakeConnection]. Obviously each implementation has to make its own choices based on its requirements and constraints but it is considered best practice to (a) re-use existing standards when possible and (b) implement the extension at the lowest, common extension point shared by all the components in the interaction.
The Delivery Mechanism and NotifyTo EPR are immutable properties of a Subscription; they are set at Subscribe-time and cannot be changed for the life of the Subscription.
4.4 Notification Format
As described in Section 2.3 of the WS-Eventing specification, the Notification Format defines how Notifications are serialized as messages. WS-Eventing defines two Formats, wrapped and unwrapped.
The Notification Format is an immutable property of a Subscription; it is set at Subscribe-time and cannot be changed for the life of the Subscription.
4.4.1 Wrapped Notifications
As described in the specification, all Wrapped Notifications have the wse:Notify element as the first/only child of the soap:Body element. The following is an example of a Wrapped Notification:
01 <soap:Envelope . . .> 02 <soap:Header> 03 <wsa:Action> 04 http://www.w3.org/2010/08/ws-evt/WrappedSinkPortType/NotifyEvent 05 </wsa:Action> 06 . . . 07 </soap:Header> 08 <soap:Body> 09 <wse:Notify actionURI="http://www.cetatrack.org/2010/TagReport"> 10 <ctx:TagUpdate xmlns:ctx="http://www.cetatrack.org/2010/" 11 xmlns:gpx="http://www.topografix.com/GPX/1/1"> 12 <ctx:ID>urn:uuid:32675b90-de3d-11df-85ca-0800200c9a66</ctx:ID> 13 <ctx:pt lat="53.080280" lon="-162.323565"> 14 <gpx:ele>-6.73</gpx:ele> 15 <gpx:time>2011-07-23T17:57Z</gpx:time> 16 </ctx:pt> 17 </ctx:TagUpdate> 18 </wse:Notify> 19 </soap:Body> 20 </soap:Envelope>
A few things to note about the above example: The event-specific information is "wrapped" in the wse:Notify element in lines 09-18. The wsa:Action value in line 04 is the same for all Wrapped Notifications. The @actionURI value in line 09 provides information that allows the Event Sink dispatch this particular Notification to code that has some knoweldge/expectation about its structure and contents.
The use of Wrapped Notifications allows an application to implement a single Event Sink that is capable of receiving any Wrapped Notification regardless of its originating Subscription or the structure of the event information contained within it. An example of where this is useful would be a logging Event System that simply records Notifications without attempting to process them in any semantically meaningful way.
The problem with Wrapped Notifications is that, if you process the WSDL in Appendix D of the WS-Eventing specification with common WSDL processing tools, the generated stubs will be very generic in nature. Any event-specific marshalling code will either need to be written by hand or generated using some other, presumably schema-based, code generation tool. This undercuts many of the motivations outlined in Section 2 of this primer.
4.4.2 Unwrapped Notifications
The converse of Wrapped Notifications are, obviously, Unwrapped Notifications. In an Unwrapped Notification the event information appears as a direct child of the soap:Body element. The following is the Unwrapped analog to the Wrapped Notification from Figure X:
01 <soap:Envelope . . .> 02 <soap:Header> 03 <wsa:Action> 04 http://www.cetatrack.org/2010/TagReport 05 </wsa:Action> 06 . . . 07 </soap:Header> 08 <soap:Body> 09 <ctx:TagUpdate xmlns:ctx="http://www.cetatrack.org/2010/" 10 xmlns:gpx="http://www.topografix.com/GPX/1/1"> 11 <ctx:ID>urn:uuid:32675b90-de3d-11df-85ca-0800200c9a66</ctx:ID> 12 <ctx:pt lat="53.080280" lon="-162.323565"> 13 <gpx:ele>-6.73</gpx:ele> 14 <gpx:time>2011-07-23T17:57Z</gpx:time> 15 </ctx:pt> 16 </ctx:TagUpdate> 17 </soap:Body> 18 </soap:Envelope>