Warning:
This wiki has been archived and is now read-only.

Remove Delivery and Mode

From Web Services Resource Access Working Group Wiki
(Redirected from Redundant Extension Points)
Jump to: navigation, search

As submitted, the WS-Eventing specification defines the wse:Subscribe request as follows: 

<s:Envelope ...>
  <s:Header ...>
    <wsa:Action>
      http://schemas.xmlsoap.org/ws/2004/08/eventing/Subscribe
    </wsa:Action>
    ...
  </s:Header>
  <s:Body ...>
    <wse:Subscribe ...>
      <wse:EndTo> endpoint-reference </wse:EndTo> ?
      <wse:Delivery Mode="xs:anyURI"? ...>
        xs:any *
      </wse:Delivery>
      <wse:Expires>[xs:dateTime | xs:duration]</wse:Expires> ?
      <wse:Filter Dialect="xs:anyURI"? ...>
        xs:any *
      </wse:Filter> ?
      xs:any *
    </wse:Subscribe>
  </s:Body>
</s:Envelope>

Note that the ellipsis (i.e. "…") indicate a point of extensibility that allows additional attribute content.

The /wse:Subscribe/wse:Delivery/@Mode attribute is described as follows:

The delivery mode to be used for notification messages sent in relation to this subscription. Implied value is "http://schemas.xmlsoap.org/ws/2004/08/eventing/DeliveryModes/Push", which indicates that Push Mode delivery should be used. See Section 1.2 Delivery Modes for details.

If the event source does not support the requested delivery mode, the request MUST fail, and the event source MAY generate a wse:DeliveryModeRequestedUnavailable fault indicating that the requested delivery mode is not supported.

Section 1.2 Delivery Modes describes the concept of modes:

In order to support this broad variety of event delivery requirements, this specification introduces an abstraction called a Delivery Mode. This concept is used as an extension point, so that event sources and event consumers may freely create new delivery mechanisms that are tailored to their specific requirements.

It is clear then, that the Mode attribute is a named extension point that is intended to indicate the use of Notification delivery mechanisms outside those defined by WS-Eventing (i.e. Push). The following sections provide various arguments against the use of the wse:Mode attribute and constitute the case for its removal and the removal of the wse:Delivery wrapper from the WS-Eventing specification. The arguments within this page relate to issues 6432 and 6692 in the W3C WS-RA Working Group.

1. Mode Violates WS-* Design Principles

One of the core architectural principles of WS-* is the idea of "decentralized composition". WS-* technologies and specifications can be developed independently to solve specific problems then combined as needed to provide solutions with synergistic properties. For example, one could combine WS-AtomicTransaction and WS-ReliableMessaging to create a solution that leveraged the automated transmission retry facilities of WS-RM to minimize the number transactions aborted due to network errors. The Mode attribute is an anti-pattern for this form of composition because every combination of technologies that it can support must be described a priori and assigned a unique URI.

2. Mode is Not Scalable

The value of the Mode attribute is a single URI. The use of any single value to express all the combinations of a number of different options is inherently non-scalable. For example, suppose there is an extension that defines a "Pause" operation that will temporarily halt the transmission of Notifications for a Subscription. Further suppose that there are two additional options to the basic Pause function; an auto-pause feature that pauses the Subscription after every N Notifications and a feature that requests that the Event Source persist any Notifications that were produced while the Subscription was paused. To cover all the combinations of this feature you would need 4 separate Mode URIs (pause, pause-with-auto-pause, pause-with-persist, and pause-with-persist-and-auto-pause). If you added another sub-feature or option you would need 8 Mode URIs.

Contrast this with the standard WS-* pattern of indicating extensions via discrete elements or attributes. The request to enable the "Pause" extension could be indicated via the presence of the "foo:Pause" element in the wse:Subscribe request. The "foo:Pause" element could be defined to include two optional boolean attributes, "autoPause" and "persist". This "foo:Pause" extension element could occur alongside other extension elements without the need to define unique URIs that describe such combinations.

3. Mode is Redundant

The use of a named element or attribute as an extension point does not impart any qualities beyond those that apply to "anonymous" extension points (i.e. those that are defined by the use of unnamed xs:any and xs:anyAttribute within XML Schema). For example, the following element: 

<ns:Foo>
  <ns:SomeStuff> some stuff </ns:SomeStuff>
  <ns:Extension>
    xs:any *
  </ns:Extension> ?
</ns:Foo>

is no more extensible than: 

<ns:Foo>
  <ns:SomeStuff> some stuff </ns:SomeStuff>
  xs:any *
</ns:Foo>

The latter is, in fact, more efficient because extensions can simply be added to the ns:Foo element without the need for the surrounding ns:Extension element. The ns:Extension element doesn't provide any additional semantics, since any element that is not defined in the schema for ns:Foo is, by definition, an extension.

Either of the above examples is preferable to: 

<ns:Foo>
  <ns:SomeStuff> some stuff </ns:SomeStuff>
  <ns:Extension>
    xs:any *
  </ns:Extension> ?
  xs:any *
</ns:Foo>

for the following reasons:

  1. Implementations that consume the ns:Foo element must check two locations for the presence of extensions; both inside the optional ns:Extension element and at the end of the ns:Foo element (after the ns:SomeStuff element in cases where the ns:Extension is not present, or after the ns:Extension element in cases where it is). Checking two locations is less efficient and more error prone than checking a single location.
  2. Developers that wish to extend the ns:Foo element must decide whether to add the extension as a child element of ns:Extension or of ns:Foo. If the specification for ns:Foo defines differences in the processing of extensions between these two points (e.g. differences in the behavior for non-understood extensions), such differences must be clearly described or it is likely that developers will pick the wrong point for their extension. A single extension point is more efficient in terms of both the developers time and the actual runtime costs.

It should be noted that the wse:Subscribe message is analogous to our final example above, except that wse:Subscribe has several more layers of extensibility including SOAP Headers, the wse:Subscribe element, the wse:Delivery element, the extensibility of the various wsa:EndpointReferences, and the Mode attribute. The following sections show how these multiple layers of extensibility could be removed in a manner that still allows the wse:Subscribe message to support the use cases that are supported by the Member Submission. We sill use the following definition of wse:Subscribe for these examples: 

<wse:Subscribe ...>
  <wse:NotifyTo> endpoint-reference </wse:NotifyTo>
  <wse:EndTo> endpoint-reference </wse:EndTo> ?
  <wse:Expires>[xs:dateTime | xs:duration]</wse:Expires> ?
  <wse:Filter Dialect="xs:anyURI"? ...>
    xs:any *
  </wse:Filter> ?
  ...
</wse:Subscribe>

3.1 WSMAN PushWithAck

The WS-Management v1.0.0.a specification defines a WS-Eventing delivery mode extension called "PushWithAck". This extension is described as follows:

With this mode, each SOAP message has only one event, but each event is acknowledged before another may be sent. The service MUST queue all undelivered events for the subscription and only deliver each new event after the previous one has been acknowledged.

A request for a subscription with "PushWithAck" delivery mode might look like the following example: 

<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope"
            xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing"
            xmlns:wse="http://schemas.xmlsoap.org/ws/2004/08/eventing">
  <s:Header>
    <wsa:Action>http://schemas.xmlsoap.org/ws/2004/08/eventing/Subscribe</wsa:Action>
    <wsa:MessageID>uuid:d7c5726b-de29-4313-b4d4-b3425b200839</wsa:MessageID>
    <wsa:ReplyTo>
      <wsa:Address>http://www.example.com/MyEventSink</wsa:Address>
    </wsa:ReplyTo>
    <wsa:To>http://www.example.org/oceanwatch/EventSource</wsa:To>
  </s:Header>
  <s:Body>
    <wse:Subscribe>
      <wse:Delivery Mode="http://schemas.dmtf.org/wbem/wsman/1/wsman/PushWithAck">
        <wse:NotifyTo>
          <wsa:Address>http://www.example.com/MyEventSink/OnStormWarning</wsa:Address>
        </wse:NotifyTo>
      </wse:Delivery>
    </wse:Subscribe>
  </s:Body>
</s:Envelope>

Using the new definition of our wse:Subscribe element, this request might look like this: 

<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope"
            xmlns:wsa="http://www.w3.org/2005/08/addressing"
            xmlns:wse="http://www.w3.org/2009/02/ws-evt"
            xmlns:wsman="http://schemas.dmtf.org/wbem/wsman/2/wsman.xsd">
  <s:Header>
    <wsa:Action>http://schemas.xmlsoap.org/ws/2004/08/eventing/Subscribe</wsa:Action>
    <wsa:MessageID>uuid:d7c5726b-de29-4313-b4d4-b3425b200839</wsa:MessageID>
    <wsa:ReplyTo>
      <wsa:Address>http://www.example.com/MyEventSink</wsa:Address>
    </wsa:ReplyTo>
    <wsa:To>http://www.example.org/oceanwatch/EventSource</wsa:To>
    <wsman:UseNotifyAcks mustUnderstand="1"/>
  </s:Header>
  <s:Body>
    <wse:Subscribe wsman:NotifyAcks="1">
      <wse:NotifyTo>
        <wsa:Address>http://www.example.com/MyEventSink/OnStormWarning</wsa:Address>
      </wse:NotifyTo>
    </wse:Subscribe>
  </s:Body>
</s:Envelope>

In this example we chose to extend the wse:Subscribe request with a attribute of type xs:boolean. This is because there are no parameters or other modifiers for this extension; it is either on or off. If there where parameters such as the expected acknowledgment interval, etc. this extension would have taken the form of an added child-element within wse:Subscribe.

Note the use of the wsman:UseNotifyAcks SOAP Header. This header is used to conform to the extension semantics of the Mode attribute wherein extensions that are not understood must generate a fault and fail to create a subscription. There are cases in which the Subscriber may want to omit this header. We will cover such cases in a later section.

An even more literal translation of this extension might look like the following: 

<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope"
            xmlns:wsa="http://www.w3.org/2005/08/addressing"
            xmlns:wse="http://www.w3.org/2009/02/ws-evt"
            xmlns:wse06="http://schemas.xmlsoap.org/ws/2004/08/eventing"
            xmlns:wsman="http://schemas.dmtf.org/wbem/wsman/2/wsman.xsd">
  <s:Header>
    <wsa:Action>http://schemas.xmlsoap.org/ws/2004/08/eventing/Subscribe</wsa:Action>
    <wsa:MessageID>uuid:d7c5726b-de29-4313-b4d4-b3425b200839</wsa:MessageID>
    <wsa:ReplyTo>
      <wsa:Address>http://www.example.com/MyEventSink</wsa:Address>
    </wsa:ReplyTo>
    <wsa:To>http://www.example.org/oceanwatch/EventSource</wsa:To>
    <wse06:UseDelivery mustUnderstand="1"/>
  </s:Header>
  <s:Body>
    <wse:Subscribe>
      <wse:NotifyTo>
        <wsa:Address>http://www.example.com/MyEventSink/OnStormWarning</wsa:Address>
      </wse:NotifyTo>
      <wse06:Delivery Mode="http://schemas.dmtf.org/wbem/wsman/1/wsman/PushWithAck"/>
    </wse:Subscribe>
  </s:Body>
</s:Envelope>

The above example actually preserves the use of the wse:Delivery element and it's @Mode attribute in their original, WS-Eventing 200603 namespace, but treats them as extensions in our proposed uniform extension model. The purpose of this is to allow existing implementation to support both WS-Eventing 1.0 and 200603 using a common codebase.

The above examples illustrate a literal translation of the semantics of the existing WS-Management 1.0 "PushWithAck" extension using the proposed uniform extension model. In general, the DMTF and other organizations should be encouraged to re-use existing web service standards where appropriate rather than inventing idiosyncratic alternatives for the same functionality. In this case this would entail the use of WS-ReliableMessaging to provide the acknowledgment framework and retry semantics. A Subscribe request that includes the indication that Notifications should be sent using WS-RM might look like the following: 

<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope"
            xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing"
            xmlns:wse="http://www.w3.org/2009/02/ws-evt"
            xmlns:wsman="http://schemas.dmtf.org/wbem/wsman/2/wsman.xsd">
  <s:Header>
    <wsa:Action>http://schemas.xmlsoap.org/ws/2004/08/eventing/Subscribe</wsa:Action>
    <wsa:MessageID>uuid:d7c5726b-de29-4313-b4d4-b3425b200839</wsa:MessageID>
    <wsa:ReplyTo>
      <wsa:Address>http://www.example.com/MyEventSink</wsa:Address>
    </wsa:ReplyTo>
    <wsa:To>http://www.example.org/oceanwatch/EventSource</wsa:To>
    <wsman:UseEPRPolicy mustUnderstand="1"/>
  </s:Header>
  <s:Body>
    <wse:Subscribe>
      <wse:NotifyTo>
        <wsa:Address>http://www.example.com/MyEventSink/OnStormWarning</wsa:Address>
        <wsa:Metadata>
          <wsp:Policy>
            <wsrmp:RMAssertion>
              <wsp:Policy>
                <wsrmp:DeliveryAssurance>
                  <wsp:Policy>
                    <wsrmp:ExactlyOnce/>
                    <wsrmp:InOrder/>
                  </wsp:Policy>
                </wsrmp:DeliveryAssurance>
              </wsp:Policy>
            </wsrmp:RMAssertion>
          </wsp:Policy>
        </wsa:Metadata>
      </wse:NotifyTo>
    </wse:Subscribe>
  </s:Body>
</s:Envelope>

Although this may look a bit intimidating, note that the majority of the extension material lies within the NotifyTo EPR. There is an implicit architecture underlying this in which there are separate, WS-RM components that can understand and parse this policy. The wsman:UseEPRPolicy serves as an indication to the Event Source that this Subscribe request contains policies within one or more of its EPRs. The semantics may be defined such that the Event Source must understand and be capable of complying with the contain policies or it must reject the Subscribe request (again, we're not trying to present a full-fledged design on the composition of WS-RM and WS-Eventing, we're just trying to show the kinds of extensions that are possible within our uniform model).

3.2 WSMAN Pull

The WS-Management v1.0.0.a specification defines a WS-Eventing delivery mode extension called "Pull". This extension is described as follows:

WS-Management defines a custom event delivery mode, "pull mode", which allows an event source to maintain a logical queue of event messages received by enumeration.

A request for a subscription with "Pull" delivery mode might look like the following example: 

<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope"
            xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing"
            xmlns:wse="http://schemas.xmlsoap.org/ws/2004/08/eventing">
  <s:Header>
    <wsa:Action>http://schemas.xmlsoap.org/ws/2004/08/eventing/Subscribe</wsa:Action>
    <wsa:MessageID>uuid:d7c5726b-de29-4313-b4d4-b3425b200839</wsa:MessageID>
    <wsa:ReplyTo>
      <wsa:Address>http://www.example.com/MyEventSink</wsa:Address>
    </wsa:ReplyTo>
    <wsa:To>http://www.example.org/oceanwatch/EventSource</wsa:To>
  </s:Header>
  <s:Body>
    <wse:Subscribe>
      <wse:Delivery Mode="http://schemas.dmtf.org/wbem/wsman/1/wsman/Pull">
        <wse:NotifyTo>
          <wsa:Address>http://www.example.com/MyEventSink/OnStormWarning</wsa:Address>
        </wse:NotifyTo>
      </wse:Delivery>
    </wse:Subscribe>
  </s:Body>
</s:Envelope>

As defined by WS-Management, a successful the wse:SubscribeResponse for such a request must be extended with a WS-Enumeration wsen:EnumerationContext as shown in the following example: 

<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope"
            xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing"
            xmlns:wse="http://schemas.xmlsoap.org/ws/2004/08/eventing"
            xmlns:wsen="http://schemas.xmlsoap.org/ws/2004/09/enumeration">
  <s:Header>
  </s:Header>
  <s:Body>
    <wse:SubscribeResponse>
      <wse:SubscriptionManager>
        <wsa:Address>http://www.example.org/oceanwatch/SubscriptionManager</wsa:Address>
      </wse:SubscriptionManager>
      <wse:Expires>P0Y0M0DT30H0M0S</wse:Expires>
      <wsen:EnumerationContext>uuid:c8e50110-2a13-11de-8c30-0800200c9a66</wsen:EnumerationContext>
    </wse:SubscribeResponse>
  </s:Body>
</s:Envelope>

3.3 WSMAN Batched

<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope"
            xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing"
            xmlns:wse="http://schemas.xmlsoap.org/ws/2004/08/eventing">
  <s:Header>
    <wsa:Action>http://schemas.xmlsoap.org/ws/2004/08/eventing/Subscribe</wsa:Action>
    <wsa:MessageID>uuid:d7c5726b-de29-4313-b4d4-b3425b200839</wsa:MessageID>
    <wsa:ReplyTo>
      <wsa:Address>http://www.example.com/MyEventSink</wsa:Address>
    </wsa:ReplyTo>
    <wsa:To>http://www.example.org/oceanwatch/EventSource</wsa:To>
  </s:Header>
  <s:Body>
    <wse:Subscribe>
      <wse:Delivery Mode="http://schemas.dmtf.org/wbem/wsman/1/wsman/Events">
        <wse:NotifyTo>
          <wsa:Address>http://www.example.com/MyEventSink/OnStormWarning</wsa:Address>
        </wse:NotifyTo>
        <wsman:MaxElements>6</wsman:MaxElements>
        <wsman:MaxTime>PT10M</wsman:MaxTime>
      </wse:Delivery>
    </wse:Subscribe>
  </s:Body>
</s:Envelope>
Retrieved from "https://www.w3.org/2002/ws/ra/wiki/index.php?title=Remove_Delivery_and_Mode&oldid=110"