Web Services Architecture and Its Specifications [Electronic resources] : Essentials for Understanding WS-* نسخه متنی

Eventing

Many systems can proactively search for updated information, but it is also common to receive alerts (or events) as alarms within a system. Although many technologists immediately think of systems management solutions as an example application, our book collection scenario is also easily expanded to take advantage of Web services eventing.

For each of the book collections, other instructors or students might want to be notified if the collection is updated or deleted. In the scenario we discuss in this section, either Professor Cabrera or his Teaching Assistant (TA) might update the course book collection.

If the TA makes an update, the professor would like to be alerted of the change. Additionally, the professor is interested in changes to the book collection provided by his department head. WS-Eventing can be used to set up and manage these subscriptions, as shown in Figure 16-3.

A Subscribe message [Message 1] is sent to the Microsoft Press event source. When the subscription is created, its endpoint reference and other information are returned in a SubscribeResponse [Message 2].

When events occur and they match the subscription requirements, event notifications [Message 3] are sent to the subscriber, or event sink.

If a subscription is about to expire, the event sink can request that the subscription be extended through a Renew request [Message 4]. The response to this request is returned in a RenewResponse message [Message 5].

If the current status of a particular subscription is not known, the event sink might request that information using a GetStatus message [Message 6]. Subscription status information is returned in a GetStatusResponse [Message 7].

If the event sink does not want to receive any more notifications for the subscription, it can cancel the subscription by sending an Unsubscribe message [Message 8]. The response to this request is an UnsubscribeResponse message [Message 9].

Finally, the event source might no longer be able to provide the subscription as requested. In this case, the source can send a SubscriptionEnd message [Message 10] to notify the subscribers.

The Subscribe message requests a new subscription on a particular topic. A sample message is shown here:

Subscribe
(01)  <env:Envelope>
(02)   <env:Header>
(03)    <wsa:Action>
(04)     http://schemas.xmlsoap.org/ws/2004/08/eventing/Subscribe
(05)   </wsa:Action>
...
(06)   </env:Header>
(07)   <env:Body>
(08)    <wse:Subscribe>
(09)     <wse:EndTo>endpoint reference</wse:EndTo>
(10)     <wse:Delivery>
(11)      <wse:NotifyTo>
(12)       <wsa:Address>http://fineartschool.com/subscriptions</wsa:Address>
(13)       <wsa:ReferenceProperties>
(14)        <sfa:Subscriber>t.johnson@fineartschool.com</sfa:Subscriber>
(15)       </wsa:ReferenceProperties>
(16)      </wse:NotifyTo>
(17)      <wse:Expires>2005-06-30T23:59:59.0000-08:00</wse:Expires>
(18)      <wse:Filter Dialect="http://ex.mspress.microsoft.com/collections">
(19)       <msp:Collection>l.cabrera@fineartschool.com</msp:Collection>
(20)       <msp:Collection>c.kurt@fineartschool.com</msp:Collection>
(21)      </wse:Filter>
(22)     </wse:Delivery>
(23)    </wse:Subscribe>
(24)   </env:Body>
(25)  </env:Envelope>

Lines 0305 This value for Action specifies that this is a Subscribe message, as defined in the WS-Eventing specification.

Line 09 The endpoint reference for where a SubscriptionEnd message is sent may be specified. Details are omitted here.

Lines 1116 The endpoint reference for event notifications is specified. This reference includes both the HTTP address of the school's subscription sink service, as well as reference properties to help ensure that the event is routed properly.

Line 17 This subscription expires at the end of the school yearjust before midnight on June 30, 2005.

Lines 1821 The topic filter is specified here. This filter uses a specific dialect for book collections, as defined for the Microsoft Press system. This custom dialect uses a list of collection owners to identify which collections to watch for changes. The request is for a single subscription that sends events when either Professor Cabrera's or Professor Kurt's collections are updated.

Once the subscription is created, the endpoint reference for the subscription manager is returned, along with a confirmation of the expiration time:

SubscribeResponse
(01)  <env:Envelope>
(02)   <env:Header>
(03)    <wsa:Action>
(04)      http://schemas.xmlsoap.org/ws/2004/08/eventing/SubscribeResponse
(05)    </wsa:Action>
...
(06)   </env:Header>
(07)   <env:Body>
(08)    <wse:SubscribeResponse>
(09)     <wse:SubscriptionManager>
(10)      <wsa:Address>http://ex.mspress.microsoft.com/eventing</wsa:Address>
(11)      <wsa:ReferenceParameters>
(12)       <msp:SubscriptionID>1524658a</msp:SubscriptionID>
(13)      </wsa:ReferenceParameters>
(14)     </wse:SubscriptionManager>
(15)     <wse:Expires>2005-07-01T00:00:00.0000-00:00</wse:Expires>
(16)    <wse:SubscribeResponse>
(17)   </env:Body>
(18)  </env:Envelope>

Lines 0305 This value for Action specifies that this is a SubscribeResponse message, as defined in the WS-Eventing specification.

Lines 0914 The endpoint reference for this subscription manager is returned in the response. Any requests for changes or status related to this subscription are addressed as instructed by this endpoint reference. An additional reference parameter is included to facilitate message processing.

Line 15 The expiration time for the subscription is returned. In this example, the subscription manager did not accept the requested expiration time and changed it to the beginning of the next day, GMT.

Once the subscription is established, notifications can be sent to the event sink. The WS-Eventing specification does not dictate what the body of a notification contains. We can identify a notification by the reference parameters that were sent in the Subscribe message.

Event Notifications
(01)  <env:Envelope>
(02)   <env:Header>
(03)    <wsa:Action>
(04)     http://ex.mspress.microsoft.com/eventing/notification
(05)    </wsa:Action>
(06)    <wsa:Address>http://fineartschool.com/subscriptions</wsa:Address>
(07)    <sfa:Subscriber>t.johnson@fineartschool.com</sfa:Subscriber>
...
(08)   </env:Header>
(09)   <env:Body>
(10)    <msp:CollectionChanged>
(11)     <msp:Collection>c.kurt@fineartschool.com</msp:Collection>
(12)    </msp:CollectionChanged>
(13)   </env:Body>
(14)  </env:Envelope>

Lines 0305 This value for Action specifies that this is an notification message, as defined by Microsoft Press.

Lines 0607 The addressing information and reference properties included in the Subscription message are used to help deliver and process the notification.

Lines 1012 This sample notification informs the event sink of which collection has changed.

An event sink can request that its subscription be renewed at any time. In our example scenario, the professor does not need to make any changes to his subscriptions, so he simply requests that the current one be extended for another year.

Renew
(01)  <env:Envelope>
(02)   <env:Header>
(03)    <wsa:Action>
(04)     http://schemas.xmlsoap.org/ws/2004/08/eventing/Renew
(05)    </wsa:Action>
(06)    <wsa:To>http://ex.mspress.microsoft.com/eventing</wsa:To>
(07)    <msp:SubscriptionID>1524658a</msp:SubscriptionID>
(08)        ...
(09)   </env:Header>
(10)   <env:Body>
(11)    <wse:Renew>
(12)      <wse:Expires>2006-07-01T00:00:00.0000-00:00</wse:Expires>
(13)    </wse:Renew>
(14)   </env:Body>
(15)  </env:Envelope>

Lines 0305 This value for Action specifies that this is a Renew message, as defined in the WS-Eventing specification.

Lines 0607 The renew request is routed to the subscription manager, along with the reference parameters provided in the SubscribeResponse above.

Line 12 The new expiration date requested is provided in the SOAP Body.

The new expiration date for the subscription is returned in the RenewResponse message:

RenewResponse
(01)  <env:Envelope>
(02)   <env:Header>
(03)    <wsa:Action>
(04)     http://schemas.xmlsoap.org/ws/2004/08/eventing/RenewResponse
(05)    </wsa:Action>
(06)        ...
(07)   </env:Header>
(08)   <env:Body>
(09)    <wse:RenewResponse>
(10)     <wse:Expires>2006-07-01T00:00:00.0000-00:00</wse:Expires>
(11)    </wse:RenewResponse>
(12)   </env:Body>
(13)  </env:Envelope>

Lines 0305 This value for Action specifies that this is a RenewResponse message, as defined in the WS-Eventing specification.

Line 10 The extended expiration date for the subscription is confirmed.

The GetStatus message is used for an event sink to request information about the subscription, such as when it expires:

GetStatus
(01)  <env:Envelope>
(02)   <env:Header>
(03)    <wsa:Action>
(04)     http://schemas.xmlsoap.org/ws/2004/08/eventing/GetStatus
(05)    </wsa:Action>
(06)    <wsa:To>http://ex.mspress.microsoft.com/eventing</wsa:To>
(07)    <msp:SubscriptionID>1524658a</msp:SubscriptionID>
...
(08)   </env:Header>
(09)   <env:Body>
(10)    <wse:GetStatus/>
(11)   </env:Body>
(12)  </env:Envelope>

Lines 0305 This value for Action specifies that this is a GetStatus message, as defined in the WS-Eventing specification.

Lines 0607 The status request is routed to the subscription manager, along with the reference parameters provided in the SubscribeResponse message above.

Line 10 The SOAP body contains only an empty GetStatus element.

The response to this message contains the current expiration time for the subscription:

GetStatusResponse
(01)  <env:Envelope>
(02)   <env:Header>
(03)    <wsa:Action>
(04)     http://schemas.xmlsoap.org/ws/2004/08/eventing/GetStatusResponse
(05)    </wsa:Action>
...
(06)   </env:Header>
(07)   <env:Body>
(08)    <wse:RenewResponse>
(09)     <wse:Expires>2006-07-01T00:00:00.0000-00:00</wse:Expires>
(10)    </wse:RenewResponse>
(11)   </env:Body>
(12)  </env:Envelope>

Lines 0305 This value for Action specifies that this is a GetStatusResponse message, as defined in the WS-Eventing specification.

Line 09 The expiration time for the subscription is provided.

When a subscription is no longer needed, either the event source or event sink may cancel it. To cancel its subscription, the event sink sends an Unsubscribe message to the event source. In our example scenario, the School of Fine Art application cancels the subscription for Professor Cabrera.

Unsubscribe
(01)  <env:Envelope>
(02)   <env:Header>
(03)    <wsa:Action>
(04)     http://schemas.xmlsoap.org/ws/2004/08/eventing/Unsubscribe
(05)    </wsa:Action>
(06)    <wsa:To>http://ex.mspress.microsoft.com/eventing</wsa:To>
(07)    <msp:SubscriptionID>1524658a</msp:SubscriptionID>
...
(08)   </env:Header>
(09)   <env:Body>
(10)    <wse:Unsubscribe/>
(11)   </env:Body>
(12)  </env:Envelope>

Lines 0305 This value for Action specifies that this is an Unsubscribe message, as defined in the WS-Eventing specification.

Lines 0607 The request is routed to the subscription manager, along with the reference parameters provided in the SubscribeResponse message above.

Line 10 The SOAP body contains only an empty Unsubscribe element.

When the subscription is deleted, an UnsubscribeResponse message is returned:

UnsubscribeResponse
(01)  <env:Envelope>
(02)   <env:Header>
(03)    <wsa:Action>
(04)     http://schemas.xmlsoap.org/ws/2004/08/eventing/UnsubscribeResponse
(05)    </wsa:Action>
...
(06)   </env:Header>
(07)   <env:Body/>
(08)  </env:Envelope>

Lines 0305 This value for Action specifies that this is an UnsubscribeResponse message, as defined in the WS-Eventing specification.

Line 07 The SOAP Body of an UnsubscribeResponse can be empty.

Similarly, the event source might end a subscription for any reason. If possible, the event source should notify the sink that the subscription is ended so that resources can be recovered or new subscriptions can be requested.

When the event source ends a subscription, it sends a SubscriptionEnd message to the event sink. In our sample scenario, this is because the subscription manager service is being shut down.

No reply message is specified for a SubscriptionEnd message.

SubscriptionEnd
(01)  <env:Envelope>
(02)   <env:Header>
(03)    <wsa:Action>
(04)     http://schemas.xmlsoap.org/ws/2004/08/eventing/SubscriptionEnd
(05)    </wsa:Action>
(06)    <wsa:Address>http://fineartschool.com/subscriptions</wsa:Address>
(07)    <sfa:Subscriber>t.johnson@fineartschool.com</sfa:Subscriber>
...
(08)   </env:Header>
(09)   <env:Body>
(10)    <wse:SubscriptionEnd>
(11)     <wse:SubscriptionManager>
(12)      <wsa:Address>http://ex.mspress.microsoft.com/eventing</wsa:Address>
(13)      <wsa:ReferenceParameters>
(14)       <msp:SubscriptionID>1524658a</msp:SubscriptionID>
(15)      </wsa:ReferenceParameters>
(16)     </wse:SubscriptionManager>
(17)     <wse:Status>
http://schemas.xmlsoap.org/ws/2004/08/eventing/SourceShuttingDown
(18)     </wse:Status>
(19)     <wse:Reason xml:lang="en-us">System shutdown</wse:Reason>
(20)    </wse:SubscriptionEnd>
(21)   </env:Body>
(22)  </env:Envelope>