Async Extension for SOAP1.1/HTTP

Proposed by:

Ümit Yalçınalp (SAP), Anish Karmarkar (Oracle), Francisco Curbera and Katy Warr (IBM)

 

Contents:

  1. Motivation
  2. Requirements
  3. Proposal
    1. Detailed Proposal for WS-Addressing WSDL Binding Document
    2. Addendum to the WS-Addressing SOAP Binding Document
  4. SOAP 1.2/HTTP and WSDL 2.0
  5. Open Issues

1. Motivation:

As we all know, the usage of WS-Addressing is limited in its current form. This proposal defines an addition to the wsaw:UsingAddressing element in the WS-Addressing WSDL binding to indicate an extension specific to SOAP 1.1/HTTP binding. 

The current SOAP 1.1/HTTP binding does not allow response messages or fault messages to be sent over a different HTTP connection from that of the request message. 

Without an extension to SOAP/HTTP bindings, the wsa:ReplyTo and wsa:FaultTo headers (and any response header that uses WS-A semantics) can not contain URIs other than the normative Anonymous address as defined by WS-Addressing specification. This precludes any asynchronous use case when using SOAP 1.1/HTTP (as well as SOAP 1.2/HTTP).  Clearly, an extension to the SOAP 1.1/HTTP binding is needed to indicate that additional transport level support may be provided when WS-Addressing is available. Furthermore, this extension MUST be expressible within WSDL 1.1 documents to indicate the support for asynchronous SOAP 1.1/HTTP binding. 

2. Requirements:

We have considered the following requirements in writing this proposal: 

SOAP level requirement:

  1. Ability to transfer/transport a SOAP request over an HTTP request
  2. Ability to get back a SOAP response over an HTTP response
  3. Ability to get back a 202 HTTP response empty HTTP entity body (and get the eventual response on a different HTTP connection).

 

WSDL level requirement:

  1. Ability to express that the response will be sent over a different  HTTP connection (replyTo must be non-anon).
  2. Ability to express that the response will be sent over the same HTTP connection (in the HTTP response) (replyTo must be anonymous).
  3. Ability to express that the client gets to choose whether the response goes over the same HTTP connection or a different one.
  4. Ability to express the asynchrony at the operation level granularity.
  5. Ability to always require asynchronous binding.
  6. Ability to express the asynchrony at the portType/abstract part of the WSDL doc (as that is what is used to generate the client side APIs only without proxies). Specifying asynchrony only at the binding level does not help with respect to client side APIs.
  7. Ability to express the acceptable bindings for the response.
  8. Specifying faults when the behavior as required by the asynchrony specified are not followed.

 

We assumed the same asynchrony for faults and replies for simplicity.

The following proposal is a replacement of the section 3.1 of the current WSDL binding document that addresses the SOAP level requirements (1-3) for SOAP1.1/HTTP binding as well as WSDL level requirements for (1-5). In addition, we propose an addendum to the WS-Addressing SOAP binding specification where we define an additional header fault to address requirement (8).

In the open issues section, we discuss possible approaches for WSDL requirement 5 and 6, but we do not necessarily have consensus where and how the problem should be addressed. Some of us feel that requirement 5 (asynchronous binding) is not a requirement at all and requiring asynchrony should be handled at the portType level  or out of scope anyway.

Please note that we are not trying to solve the problem of SOAP over different transports for response messages, but rather defining an extension to the current SOAP1.1//HTTP binding so that they could be used asynchronously with this extension. Therefore, we considered requirement (7) to be independent of enabling a WSDL request-response transmission primitive asynchronously over 2 HTTP connections and hence out of scope for our proposal since it can be addressed by means of extensibility.

3.a.  Proposal (A) WS-Addressing WSDL Binding Document Changes:

 

The following section addresses the SOAP level requirements (1-3) and WSDL level requirements for (1-5). It is a replacement of the Section 3.1 of the WS-Addressing WSDL Binding Document [2]. Note that the green section reflects the current content of the specification for readability and specification changes are reflected using the appropriate font.

3.1 UsingAddressing Extension Element

WS-Addressing defines an empty global element, wsaw:UsingAddressing, that may be used to indicate that an endpoint conforms to the WS-Addressing specification. The wsdl:required attribute MAY be used to indicate whether WS-Addressing Message Addressing Properties are required in messages received from service requesters.

A wsaw:UsingAddressing element with a wsdl:required attribute whose value is "true" indicates that messages exchanged with the endpoint MUST contain WS-Addressing Message Addressing Properties. A wsaw:UsingAddressing element with a wsdl:required attribute whose value is "false" indicates that the endpoint will accept input messages with or without WS-Addressing header blocks, and MAY generate output messages containing WS-Addressing headers. If a SOAP binding is used and WS-Addressing header blocks are not present in an input message then WS-Addressing header blocks encoded in the corresponding output message MUST NOT be required to be understood using the SOAP mustUnderstand mechanism.

The wsaw:UsingAddressing element SHOULD appear as a child of the wsdl:binding element. Alternatively, the wsaw:UsingAddressing element MAY instead be included as a child of the wsdl20:endpoint (or wsdl11:port) when an endpoint intends to indicate compliance with WS-Addressing for a specific endpoint only.

The inclusion of the wsaw:UsingAddressing element indicates that the applicable WS-Addressing specifications are supported within the constraints of the WSDL binding being used. That is, uses of the WS-Addressing specifications that may violate or are inconsistent with the semantics of the endpoint's WSDL binding are not supported unless explicitly stated by some other mechanism.

Specifically, when included in a SOAP binding, the wsaw:UsingAddressing marker identifies the use of Web Services Addressing 1.0 bound to SOAP as defined by Web Services Addressing 1.0 - SOAP Binding[WS-Addressing-SOAP].

In the case of the WSDL SOAP/HTTP synchronous binding for request-response operations, the presence of the wsaw:UsingAddressing element does not change the requirement that the response message be sent over the same HTTP channel over which the request was received. In this case, the wsa:ReplyTo header in the request MUST NOT contain an address with a value different from the anonymous URI.

(Note to reader: Up to this point, this is exactly the same text from the current editor’s draft)

However, the semantics of the binding may be further extended by using an element in conjunction with this element that is described below.

3.1.1 wsaw:Async extension element for SOAP/HTTP bindings

WS-Addressing defines an element, wsaw:Async that may be used in conjunction with wsaw:UsingAddressing element. The presence of the wsaw:Async element in conjunction with wsaw:UsingAddressing element within WSDL may extend the semantics of the SOAP1.1/HTTP binding as described below. This element MAY be used only when wsaw:UsingAddressing element is present in WSDL or WS-Addressing is in use. The wsdl:required attribute value of this element SHOULD have the same value that is specified for wsaw:UsingAddressing element. (Note: The previous  item requires some discussion)

The wsaw:Async extension element MAY appear as a child of the wsdl:binding element. Alternatively, the wsaw:UsingAddressing element MAY instead be included as a child of the or wsdl11:port when an endpoint intends to indicate compliance with the extension for a specific endpoint only or MAY be included as a child of wsdl11:binding/wsdl11:operation when the specific operation intends to comply with the extension.

The value of the element specifies how the WS-Addressing may extend the semantics of SOAP1.1/HTTP binding to allow the binding to be used asynchronously.

The wsaw:Async element may have three distinct values, “full”, “never” and “always”. If the wsaw:Async element is not present, the semantics of the wsaw:UsingAddressing for  the SOAP1.1/HTTP binding does not change. 

·         The “full” value indicates that an extension to SOAP/HTTP binding is used that allows using a separate connection when needed. The extension allows a SOAP1.1/HTTP binding to use a separate connection for sending response messages, instead of using the same HTTP connection. This extension allows SOAP 1.1/HTTP to be used asynchronously as follows.

When the value of the element is “full”, the response message MAY be sent over the same HTTP channel over which the request was received or by opening a separate connection. When the value of the [reply endpoint] in the request message contains the anonymous URI as the address, the response MUST be sent over the same HTTP channel.  However, when the value of [reply endpoint] contains an address that is different than the anonymous URI, this extension for the SOAP/HTTP binding requires the following

·         The receipt of the request message MUST be acknowledged with a status message (202) by the receiver using the HTTP connection that generated the request. The receipt message MUST contain an empty SOAP body. 

·         The actual response MUST be sent using a separate connection using the address value of the response message specified by [reply endpoint].

·         The “never” value indicates that the SOAP1.1/HTTP extension that allows multiple connections is not in use. In essence, the presence of the wsaw:Async element with “never” value is equivalent to the element  not being present since current SOAP1.1/HTTP bindings do not allow multiple HTTP connections. In this case, the presence of the element does not change the requirement that the response message be sent over the same HTTP channel over which the request was received.

When wsaw:Async element has this value, [reply endpoint]/[fault endpoint] EPRs in the request MUST NOT contain an address with a value different from the anonymous URI. If [reply endpoint]/[fault endpoint] EPRs do not contain the anonymous address value, then a predefined InvalidAddressingHeader fault defined in Section 5.4.1.7 of defined by Web Services Addressing 1.0 - SOAP Binding[WS-Addressing-SOAP] MUST be generated  (See Section 3 B for the definition of this new fault).

[Note to readers: We do not have agreement whether the functionality specified with the following bullet is required to be supported. This is an open issue for discussion. We included it here for completeness. Note that this bullet  addresses WSDL requirement (5) ]

·         The “always” value of the wsaw:Async element indicates that SOAP1.1/HTTP binding must always use a separate connection for sending response messages, instead of using the same HTTP connection. The extension requires SOAP 1.1/HTTP to be used always asynchronously as described above. When wsaw:Async element has this value, [reply endpoint]/[fault endpoint] EPR in the request MUST NOT contain an address with a value that is the same as the anonymous URI.

Example 3-1. Indicating use of WS-Addressing using wsaw:UsingAddressing in WSDL 2.0

<binding name="reservationSOAPBinding"

    interface="tns:reservationInterface"

    type="http://www.w3.org/2005/08/wsdl/soap12"

    wsoap:protocol="http://www.w3.org/2003/05/soap/bindings/HTTP">

  <wsaw:UsingAddressing wsdl:required="true" />

  <operation ref="tns:opCheckAvailability"

      wsoap:mep="http://www.w3.org/2003/05/soap/mep/request-response" />

  <fault ref="tns:invalidDataFault" wsoap:code="soap:Sender" />

</binding>

Example 3-2. Indicating use of WS-Addressing using wsaw:UsingAddressing in WSDL 1.1 (same as in the current specification)

<binding name="StockQuoteSoapBinding" type="tns:StockQuotePortType">

  <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http" />

  <wsaw:UsingAddressing wsdl:required="true" />

  <operation name="GetLastTradePrice">

    <soap:operation soapaction="http://example.com/GetLastTradePrice" />

    <input>

      <soap:body use="literal" />

    </input>

    <output>

      <soap:body use="literal" />

    </output>

  </operation>

</binding>

Example 3-3. Indicating use of WS-Addressing using wsaw:UsingAddressing that supports asynchronous responses in WSDL 1.1 (new)

<binding name="StockQuoteSoapBinding" type="tns:StockQuotePortType">

  <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http" />

  <wsaw:UsingAddressing wsdl:required="true" />

  <wsaw:Async wsdl:required=”true”/>full<wsaw:Async>

 

  <operation name="GetLastTradePrice">

    <soap:operation soapaction="http://example.com/GetLastTradePrice" />

    <input>

      <soap:body use="literal" />

    </input>

    <output>

      <soap:body use="literal" />

    </output>

  </operation>

</binding>

 

3.b. Addendum to the WS-Addressing SOAP Binding Document

We propose an additional predefined SOAP fault to be added to the WS-Addressing SOAP Binding Specification in Section 5.4.1 as a special case of Invalid Addressing Header as follows. Addition of this fault will address our requirement (8).

5.4.1.7  wsa:OnlyAnonymousSupported

Specifies that an EPR value of [reply endpoint] (or [fault endpoint]) is expected to be the anonymous address. [Details] MUST contain a <wsa:ProblemHeaderQName> element that specifies the actual wsa Header that did not contain the anonymous address.

Note: If requirement (5) is addressed as proposed, another Invalid Addressing Header fault needs to be added.

 

4. SOAP 1.2/HTTP and WSDL 2.0

We believe that our proposal is general enough to also cover SOAP 1.2/HTTP, if Marc Hadley’s proposed changes to SOAP 1.2/HTTP binding that has been sent to the working group [Marc Hadley Proposal] was assumed.  Since our proposal only addresses request/response MEPs within the context of WSDL 1.1 and SOAP 1.1, the same semantics may be applied for WSDL 2.0 and SOAP 1.2/HTTP binding. 

5. Open Issues:

As illustrated above, our proposal addresses all the requirements we have envisioned, except WSDL requirement (5) and (6). We have already covered Requirement (5) above which is related to (6).

Essentially, the requirement (6) indicates that it is important to correlate two messages at the portType level that will always be used in a long running fashion. Typically, business applications will require long running interactions that involve at least two correlated messages. An example of this may be sending of an expense report and receipt of an electronic transfer of funds statement. Modeling of such interactions in WSDL may affect both the application “programming” model and the binding that may be generated. While it is possible to model such interactions with other languages, just as BPEL, labeling a request/response interaction as a long running exchange has the benefit of not requiring a heavy weight solution to a small problem.

Demarcating a WSDL request/response operation as a long running correlated exchange has the following implications:

·         Application Programming Model will need to always consider programming with asynchronous interactions. As an example, a callback will need to be modeled specifically to deal with a response if the response is expected to arrive hours, days, later.

·         Bindings/Proxies that support clients for such applications will utilize asynchronous bindings for optimal interaction.

This is an old problem and traditionally vendor specific tools correlate two one way messages together to model such interactions product specific manner.  The question is whether port level asynchrony support should be indicated to enable tools to interpret a set of WSDL portType/operations to be always asynchronous regardless of the binding. WSDL port Type/interface operation definition currently  is at the abstract level and does not indicate in any way whether programmers may assume whether they may assume long running interactions based on just the abstract layer defined by WSDL.

When tools generate client programs (i.e. the java class that corresponds to the client program, NOT proxies), they need the full definition of WSDL (abstract and concrete binding) in order to be able generate the code of the client program or skeleton as well as binding specific proxies.

Although the solution that was introduced in the proposal (Section 3 and Section 4) above affects only binding, some of us think that an additional marker at the WSDL portType/interface operation level may also assist the

·         programmer who writes the code directly to generate the client program from the WSDL port Type/interface alone

·         tools which generate client programs that model the interaction expected by the service more appropriately without needing presence of the WSDL binding.

·         allow proxies to be filled in later in the development independent of the client program itself. Today, language bindings assume different programming models to model the client program.

In order to assist with these use cases, another optional extensibility element wsaw:correlatedExchange element may be introduced. The wsaw:correlatedExchange element is Boolean. When it does not appear in a WSDL portType/operation, it does not have a default value. This element provides an optional hint for tool developers that generate client programs or programmers to write code that assume asynchronous interaction without the presence of WSDL binding. 

The wsaw:correlatedExchange element may appear within a WSDL portType/operation element to indicate that the input and output messages are correlated together but require long running exchanges that are always asynchronous. When coupled by the binding extension defined in this proposal, it is envisioned that wsaw:Async element must always appear with a value of “always” in the WSDL binding to support such portType/operations.

This approach is in essence akin to adding rpc style marker in WSDL 2.0 with the added requirement that bindings that support such operations must always be asynchronous.  

The authors of this specification wanted to bring this open issue to the attention of the working group.

References:

[Marc Hadley Proposal] http://lists.w3.org/Archives/Public/public-ws-addressing/2005Sep/0022.html

[WS-Addressing SOAP] http://dev.w3.org/cvsweb/~checkout~/2004/ws/addressing/ws-addr-soap.html?content-type=text/html;%20charset=utf-8