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

Events and Message Delivery

Event subscriptions and notifications are particularly useful for systems management solutions. WS-Management puts one restriction on the WS-Eventing specification by requiring an additional reference parameter element in each resource's endpoint reference. The additional wse:Identifier reference parameter is used to identify the resource's subscription manager.

Endpoint Reference for a Fountain Resource
(01)     <wse:SubscriptionManager>
(02)      <wsa:Address>
(03)          http://control.fineartschool.com/facilities
(04)      </wsa:Address>
(05)      <wsa:ReferenceParameters>
(06)       <wsman:ResourceURI>
(07)           http://control.fineartschool.com/fountains
(08)       </wsman:ResourceURI>
(09)       <wsman:Key Name="ResourceID">b42f3North</wsman:Key>
(10)       <wse:Identifier>1524658a</wse:Identifier>
(11)      </wsa:ReferenceParameters>
(12)     </wse:SubscriptionManager>

Line 03 The Addresss element specifies the location of the resource manager service.

Line 0608 The Resource URI is used to group the resources by type. In this case, all drinking fountains are grouped together.

Line 09 The Key element is used to identify the specific resource being managed. In our example, the fountain being referenced is on the third floor of the north end of Building 42.

Line 10 The value of the Identifier is the unique ID for the resource. In our example, the value is assigned by the drinking fountain manufacturer.

Delivery Modes

When eventing is used in a systems management scenario, there is often a need to minimize or control network traffic from a high-volume event source, retrieve information from a source on a requestor-managed schedule, or broadcast events over other protocols. Our sample scenario can take advantage of all three WS-Management delivery mode types, referred to as Batched, Pull, and Trap, respectively.

Batched Delivery

Batched delivery allows multiple events from a source to be grouped together and delivered at once. In our sample scenario, the fountain sends an event each time it is used. During the period between classes, the hallways are very active and there is no need for every event to be received separately. The Subscribe request shown here allows events to be sent every 5 minutes, 100 events to be grouped together, and messages no larger than 500 Kbytes:

Subscribe (Batched Events)
(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:Delivery
Mode="http://schemas.xmlsoap.org/ws/2004/09/management/Batched">
(10)       <wse:NotifyTo>...</wse:NotifyTo>
(11)       <wse:Expires>...</wse:Expires>
(12)       <wse:Filter>...</wse:Filter>
(13)       <wsman:MaxItems>100</wsman:MaxItems>
(14)       <wsman:MaxCharacters>51120</wsman:MaxCharacters>
(15)       <wsman:MaxTime>PT300S</wsman:MaxTime>
(16)      </wse:Delivery>
(17)     </wse:Subscribe>
(18)    </env:Body>
(19)  </env:Envelope>

Lines 0305 Messages using batched delivery still follow the WS-Eventing Subscribe message semantics.

Line 09 Batched delivery mode is indicated within the Mode attribute of the Delivery element.

Line 13 The maximum number of events that can be batched together is 100.

Line 14 The maximum size of the event list allowed is 51120 bytes.

Line 15 The maximum time that events can be batched together is 5 minutes.

When a batch of events is sent to a subscriber, they are carried in the SOAP Body as a collection of Event elements. This message fragment shows a batch of three drinking fountain usage events:

Batched Event Notifications
(01)  <env:Envelope>
(02)   <env:Header></env:Header>
(03)    <wsa:Action>
(04)         http://schemas.xmlsoap.org/ws/2004/09/management/Events
(05)    </wsa:Action>
...
(06)   <env:Body>
(07)    <wsman:Events>
(08)     <wsman:Event>
(09)      <fcs:Usage Time="2005-06-30T11:56:03.0000-08:00" Volume="4.3"/>
(10)     </wsman:Event>
(11)     <wsman:Event>
(12)      <fcs:Usage Time="2005-06-30T11:56:50.0000-08:00" Volume="2.0"/>
(13)     </wsman:Event>
(14)     <wsman:Event>
(15)       <fcs:Usage Time="2005-06-30T11:58:10.0000-08:00" Volume="3.1"/>
(16)     </wsman:Event>
(17)    </wsman:Events>
(18)   </env:Body>
(19)  </env:Envelope>

Lines 0305 This is a WS-Management batched event message.

Lines 0717 The events are contained within an Event element as the SOAP Body.

Lines 0810 Each Event element contains the application-specific information. In this example, the Fountain Control System has defined a Usage element with attributes for the time of use and water volume dispensed by the drinking fountain.

Pull Delivery

An alternate event-delivery approach, referred to as Pull delivery, allows the event sink to retrieve events from the source. With this approach, the event source sends information only when it is requested, being responsible for the buffering of the set of events.

For our sample application, the drinking fountain queues event information locally and waits for the subscription holder to request the current set of events. WS-Eventing is used to set up the subscriptions, and retrieving the event list leverages WS-Enumeration.

Subscribe (Pull Delivery)
(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:Delivery
Mode="http://schemas.xmlsoap.org/ws/2004/09/management/Pull">
(10)            ...
(11)     </wse:Delivery>
(12)    </wse:Subscribe>
(13)   </env:Body>
(14)  </env:Envelope>

Lines 0305 This message is a WS-Eventing Subscribe message.

Line 09 The delivery mode is Pull. Events will not be sent to the subscriber as they occur. Instead, they will be buffered at the source and the subscriber will retrieve the event list as it requires.

Line 10 MaxItems, MaxCharacters, and MaxTime elements defined in WS-Management are not included in this Subscribe message. Because the events are queued at the source, their behavior is undefined.

The response to a Pull Delivery Subscription message adds the enumeration context that should be used when retrieving the events:

Subscribe Response (Pull Delivery)
(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)           ...
(10)     <wsen:EnumerationContext>...</wsen:EnumerationContext>
(11)    </wse:SubscribeResponse>
(12)   </env:Body>
(13)  </env:Envelope>

Lines 0305 This message is a WS-Eventing SubscribeResponse message.

Line 10 The enumeration context for the event list is returned in the response. To retrieve all the events, the Manager uses this enumeration context to iterate through the event list.

Trap Delivery

The third delivery approach for management events is Trap Delivery. This approach uses UDP multicast messages to efficiently send small messages to many subscribers.

Subscribe (Trap Delivery)
(01)  <env:Header>
(02)   <wsa:Action>
(03)    http://schemas.xmlsoap.org/ws/2004/08/eventing/Subscribe
(04)   </wsa:Action>
...
(05)  </env:Header>
(06)  <env:Body>
(07)   <wse:Subscribe>
(08)    <wse:Delivery
Mode="http://schemas.xmlsoap.org/ws/2004/09/management/Trap">
(09)        ...
(10)    </wse:Delivery>
(11)   </wse:Subscribe>
(12)  </env:Body>

Lines 0204 A subscription requests to an event source for Trap delivery is a Subscribe message as defined in WS-Eventing.

Line 08 The identifier for the Trap delivery mode is included in the Delivery element.

The SubscriptionResponse message includes the UDP multicast address where subscribers will receive messages. This is specified in a new endpoint reference element called wsman:MulticastAddress.