Extensions for Asynchronous Message Exchange
1
Overview
This proposal outlines a means of supporting asynchronous
use of the WSDL in-only, robust in-only and in-out MEPs
over transport bindings that support the synchronous SOAP request-response
MEP. In this context, asynchronous
means that response messages (i.e., replies and faults) may be sent by means
other than the response portion of the SOAP request-response MEP.
The central idea of this proposal is that a SOAP request
over a binding supporting the SOAP request-response MEP will always produce a
response. Depending on the WSDL MEP in
effect and the exact values of the WS-Addressing [reply endpoint] and [fault
endpoint] properties, additional message exchanges may also take place. In particular:
- A WSDL
in-only MEP will always produce a SOAP request-response MEP.
- A WSDL
robust in-only or in-out MEP will always produce a SOAP request-response
MEP, and may also produce a one-way message exchange (which may itself be
realized as a SOAP request-response MEP).
The following sections define normative SOAP extensions,
WSDL extensions, and rules for interpreting WS-Addressing message addressing
properties in light of these. These are
followed by a non-normative set of rules for senders and receivers, and
non-normative example wire traces.
2
SOAP Extensions
2.1
Acknowledgement message
An endpoint receiving a SOAP message (other than an
anonymous response) using a binding which supports the SOAP request-response
MEP MUST produce a SOAP response to the sender.
If the endpoint does not respond with a fault or an application-level
response, it MUST indicate that no further response will be sent on the
anonymous response channel, by sending a message with an [action] property of http://www.w3.org/@@@@/@@/addressing/ack.
This message MAY also have any other content, as appropriate.
Bindings MAY provide optimized means of transferring
particular forms of messages with this [action].
3
WSDL Extensions
3.1
Response Binding element
WSDL binding elements MAY include zero or more [response
binding] child elements. The value of
such an element MUST be an IRI denoting a SOAP underlying transport
binding. This infoset
item is represented as an element with QName wsaw:ResponseBinding.
3.2
Using Addressing element
WSDL binding elements MAY include zero or one [using
addressing] child elements. If this
element is present, the operation MUST follow the rules specified in the
WS-Addressing Core, SOAP Binding and WSDL Binding specifications. This infoset item
is represented as an element with QName wsaw:UsingAddressing.
4
Interaction with WS-Addressing
The following uses the WSDL 2.0 names for MEPs, with the understanding that the same considerations
apply in the context of WSDL 1.1. This
section applies only to the in-only, robust in-only and in-out MEPs.
4.1
Supported Response Bindings
For any given operation, the set of supported response bindings contains all, and exactly all, of the
following IRIs:
- The
IRI
http://www.w3.org/@@@@/@@/addressing/anonymous,
if the transport binding for the operation supports the SOAP
request-response MEP
- The
values of all [response endpoint] children of the binding element
4.2
Compatibility of endpoints and supported
response bindings
For a given in message
in a WSDL MEP the set of response
endpoints is
- The
empty set in an in-only MEP
- The
set {[fault endpoint]} in a robust in-only MEP.
- The
set {[fault endpoint], [response endpoint]} in an in-out MEP.
All response endpoints for a message MUST be compatible with
exactly one of the supported response binding IRIs
for the operation. Note that this is
automatically true for an in-only operation.
An endpoint is compatible with a binding IRI if
- The
[address] of the endpoint and the binding IRI are both
http://www.w3.org/@@@@/@@/addressing/anonymous
- The
binding specified by the binding IRI provides a means of sending a message
to the [address] of the endpoint.
An endpoint receiving a message with incompatibly specified
response endpoints SHOULD attempt to fault if an anonymous response channel is
available, as per section 4.3 below.
4.3
Faults and the anonymous response channel
An endpoint supporting the anonymous response channel may
encounter errors at various stages in processing the message.
- If
such an error occurs before the [fault endpoint] property is found to be
valid, or the [fault endpoint] property is valid and has the [address]
http://www.w3.org/@@@@/@@/addressing/anonymous, the endpoint SHOULD attempt to send an appropriate
fault on the anonymous response channel.
- Otherwise
(i.e., the [fault endpoint] is valid and is not directed to the anonymous
response channel)
- If
the error occurs while the responding endpoint is in the receiving state (i.e., it has not
yet begun to send a response, and no failure has occurred), the endpoint
MAY attempt to send a fault on either the anonymous response channel, or
to the [fault endpoint], but SHOULD attempt to send a fault.
- If
the error occurs while the responding endpoint is in the sending, fail or success state, the endpoint SHOULD
attempt to send a fault to the [fault endpoint].
5
Existing bindings
Authors of new underlying transport bindings are encouraged
to specify any optimizations for acknowledgement messages. The following supplements the existing
SOAP/HTTP binding by supplying this information for it.
5.1
SOAP/HTTP
An HTTP response with status code 202 (Accepted) and no SOAP
body is equivalent to a SOAP response with an [action] property of http://www.w3.org/@@@@/@@/addressing/ack,
no other headers and no body.
The practical consequence of this is that a WSDL binding
with transport="http://schemas.xmlsoap.org/soap/http"
and a <wsaw:UsingAddressing> element
present will follow the rules given in sections 1-3 above, as illustrated in
the non-normative examples in section 7 below.
6
Non-normative rules for senders and receivers
using the SOAP request-response MEP
These rules essentially restate the normative rules above
from the point of view of message senders and receivers. In the following, an endpoint is anonymous if its [address] is http://www.w3.org/@@@@/@@/addressing/anonymous.
6.1
Rules for Receivers
Receivers of in
messages should
- Determine
what response is required, via the normal application logic. Depending on the MEP and the result of
the application processing, this will be a reply, a fault, or none at all.
- If no
response at all is required (in-only, or robust in-only with no fault), send
an acknowledgement message as the SOAP response.
- If a
response is required (in-out, or robust in-only with fault), select the
appropriate response endpoint as detailed by WS-Addressing.
- If
the response endpoint is anonymous, send the response as the SOAP
response message.
- Otherwise,
send an acknowledgement message as the SOAP response message and send the
actual response as a one-way message to the response endpoint.
6.1
Rules for Senders
- Senders
should ensure that all response endpoints required by the WSDL MEP in
effect are compatible with the response channels supported by the binding
for the operation in effect.
- If no
response endpoints are anonymous, the sender may wait for the response
message, which will be an acknowledgement message.
- If at
least one response endpoint is anonymous, the sender should wait for the
response message, which may be a reply, a fault or (in cases 2 and 3b
above) an acknowledgement message.
7
Non-normative examples
7.1
WSDL Fragments
These examples illustrate three operations: An in-only Ping operation,
a robust in-only RobustPing
operation, and an in-out EchoString operation.
They are defined abstractly by:
<operation name="Ping">
<input message="s0:PingMessageIn"/>
</operation>
<operation name="RobustPing">
<input message="s0:RobustPingMessageIn"/>
</operation>
<operation name="EchoString">
<input message="s0:EchoStringMessageIn"/>
<output message="s0:EchoStringMessageOut"/>
</operation>
For the purposes of this illustration, they are bound by:
<binding name="operation name">
<wsaw:UsingAddressing required=true/>
<wsaw:ResponseBinding>http://www.w3.org/2003/05/soap/bindings/HTTP/<wsaw:ResponseBinding>
</binding>
This binding indicates that the rules specified by
WS-Addressing are in effect, and that responses may be sent via an HTTP
connection separate from the one carrying the request.
7.2
Sample HTTP wire traces
7.2.1
In-only
HTTP request:
POST /wsaService/service.ashx HTTP/1.1
<soap:Envelope>
<soap:Header>
<wsa:Action>http://tempuri.org/ServicePortType/Ping</wsa:Action>
</soap:Header>
<soap:Body/>
</soap:Envelope>
HTTP response:
HTTP/1.1 202 Accepted
7.2.2
Robust in-only with anonymous [fault endpoint]
HTTP request:
POST /wsaService/service.ashx HTTP/1.1
<soap:Envelope>
<soap:Header>
<wsa:Action>http://tempuri.org/ServicePortType/RobustPing</wsa:Action>
<wsa:FaultTo>
<wsa:Address>http://www.w3.org/@@@@/@@/addressing/anonymous</wsa:Address>
</wsa:FaultTo>
</soap:Header>
<soap:Body/>
</soap:Envelope>
HTTP response (if no fault occurred):
HTTP/1.1 202 Accepted
HTTP response (if a fault occurred):
HTTP/1.1 500 Internal Server Error
<soap:Envelope>
<soap:Header>
<wsa:Action>http://www.w3.org/@@@@/@@/addressing/fault</wsa:Action>
</soap:Header>
<soap:Body>
</soap:Body>
<soap:Envelope>
7.2.3
Robust in-only with non-anonymous [fault
endpoint]
HTTP request:
POST /wsaService/service.ashx HTTP/1.1
<soap:Envelope>
<soap:Header>
<wsa:Action>http://tempuri.org/ServicePortType/RobustPing</wsa:Action>
<wsa:FaultTo>
<wsa:Address>http://www.example.org/fault</wsa:Address>
</wsa:FaultTo>
<wsa:MessageId>uid:SomethingUnique</wsa:MessageId>
</soap:Header>
<soap:Body/>
</soap:Envelope>
HTTP response (in all cases):
HTTP/1.1 202 Accepted
Outgoing HTTP fault message (if a fault occurred):
POST fault HTTP/1.1
<soap:Envelope>
<soap:Header>
<wsa:Action>http://www.w3.org/@@@@/@@/addressing/fault</wsa:Action>
<wsa:RelatesTo>uid:SomethingUnique</wsa:RelatesTo>
</soap:Header>
<soap:Body>
</soap:Body>
<soap:Envelope>
HTTP response to outgoing HTTP fault message (if a fault
occurred):
HTTP/1.1 202 Accepted
7.2.4
In-out with anonymous [reply endpoint] and
[fault endpoint]
HTTP request:
POST /wsaService/service.ashx HTTP/1.1
<soap:Envelope>
<soap:Header>
<wsa:Action>http://tempuri.org/ServicePortType/EchoStringRequest</wsa:Action>
<wsa:ReplyTo>
<wsa:Address>http://www.w3.org/@@@@/@@/addressing/anonymous</wsa:Address>
</wsa:ReplyTo>
<wsa:MessageId>uid:SomethingUnique</wsa:MessageId>
</soap:Header>
<soap:Body>EchoMe</soap:Body>
</soap:Envelope>
HTTP response (if no fault occurred):
HTTP/1.1 200 OK
<soap:Envelope>
<soap:Header>
<wsa:Action>http://tempuri.org/ServicePortType/EchoStringResponse</wsa:Action>
<wsa:RelatesTo>uid:SomethingUnique</wsa:RelatesTo>
</soap:Header>
<soap:Body>EchoMe</soap:Body>
<soap:Envelope>
HTTP response (if a fault occurred):
HTTP/1.1 500 Internal Server Error
<soap:Envelope>
<soap:Header>
<wsa:Action>http://www.w3.org/@@@@/@@/addressing/fault</wsa:Action>
</soap:Header>
<soap:Body>
</soap:Body>
<soap:Envelope>
7.2.5
In-out with non-anonymous [reply endpoint] and
anonymous [fault endpoint]
HTTP request:
POST /wsaService/service.ashx HTTP/1.1
<soap:Envelope>
<soap:Header>
<wsa:Action>http://tempuri.org/ServicePortType/EchoStringRequest</wsa:Action>
<wsa:ReplyTo>
<wsa:Address> http://www.example.org/reply</wsa:Address>
</wsa:ReplyTo>
<wsa:FaultTo>
<wsa:Address>http://www.w3.org/@@@@/@@/addressing/anonymous</wsa:Address>
</wsa:FaultTo>
<wsa:MessageId>uid:SomethingUnique</wsa:MessageId>
</soap:Header>
<soap:Body>EchoMe</soap:Body>
</soap:Envelope>
HTTP response (if no fault occurred):
HTTP/1.1 202 Accepted
Outgoing HTTP reply message (if no fault occurred):
POST /reply HTTP 1.1
<soap:Envelope>
<soap:Header>
<wsa:Action>http://tempuri.org/ServicePortType/EchoStringResponse</wsa:Action>
<wsa:RelatesTo>uid:SomethingUnique</wsa:RelatesTo>
</soap:Header>
<soap:Body>EchoMe</soap:Body>
<soap:Envelope>
HTTP response to outgoing reply message (if no fault
occurred):
HTTP/1.1 202 Accepted
HTTP response to request message (if a fault occurred):
HTTP/1.1 500 Internal Server Error
<soap:Envelope>
<soap:Header>
<wsa:Action>http://www.w3.org/@@@@/@@/addressing/fault</wsa:Action>
</soap:Header>
<soap:Body>
</soap:Body>
<soap:Envelope>
7.2.6
In-out with non-anonymous [reply endpoint] and
[fault endpoint]
HTTP request:
POST /wsaService/service.ashx HTTP/1.1
<soap:Envelope>
<soap:Header>
<wsa:Action>http://tempuri.org/ServicePortType/EchoStringRequest</wsa:Action>
<wsa:ReplyTo>
<wsa:Address>http://www.example.org/reply</wsa:Address>
</wsa:ReplyTo>
<wsa:FaultTo>
<wsa:Address> http://www.example.org/fault</wsa:Address>
</wsa:FaultTo>
<wsa:MessageId>uid:SomethingUnique</wsa:MessageId>
</soap:Header>
<soap:Body>EchoMe</soap:Body>
</soap:Envelope>
HTTP response to request message (in all cases):
HTTP/1.1 202 Accepted
Outgoing HTTP reply message (if no fault occurred):
POST /reply HTTP/1.1
<soap:Envelope>
<soap:Header>
<wsa:Action>http://tempuri.org/ServicePortType/EchoStringResponse</wsa:Action>
<wsa:RelatesTo>uid:SomethingUnique</wsa:RelatesTo>
</soap:Header>
<soap:Body>EchoMe</soap:Body>
<soap:Envelope>
HTTP response to outgoing reply message (if no fault
occurred):
HTTP/1.1 202 Accepted
Outgoing HTTP fault message (if a fault occurred):
POST /fault HTTP/1.1
<soap:Envelope>
<soap:Header>
<wsa:Action>http://www.w3.org/@@@@/@@/addressing/fault</wsa:Action>
</soap:Header>
<soap:Body>
</soap:Body>
<soap:Envelope>
HTTP response to outgoing fault message (if a fault
occurred):
HTTP/1.1 202 Accepted
7.2.7
In-only, headers needed in marker message
For various reasons, a SOAP marker message response may need
to contain SOAP headers beyond the <wsa:Action>
header. In this case, the response
should be a non-optimized SOAP message, as shown here:
HTTP request:
POST /wsaService/service.ashx HTTP/1.1
<soap:Envelope>
<soap:Header>
<wsa:Action>http://tempuri.org/ServicePortType/Ping</wsa:Action>
</soap:Header>
<soap:Body/>
</soap:Envelope>
HTTP response:
HTTP/1.1 200 OK
<soap:Envelope>
<soap:Header>
<wsa:Action>http://www.w3.org/@@@@/@@/addressing/marker</wsa:action>
<myns:SomeHeader>
</myns:SomeHeader>
</soap:Header>
<soap:Body/>
</soap:Envelope>