WS-Addressing defines a 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. Table
3-1 outlines the requirements on messages sent from an endpoint based on
the contents of any preceding input message and how the use of addressing is
indicated in the WSDL.
|
MAPs in Input message |
UsingAddressing Present |
UsingAddressing Not Present |
|
|
wsdl:required="true" |
wsdl:required="false" |
||
|
Yes, using
SOAP headers with a soap:mustUnderstand value of
"true" |
REQUIRED |
REQUIRED |
REQUIRED or
fault |
|
Yes, using
another protocol or using SOAP headers with a soap:mustUnderstand
value of "false" |
REQUIRED |
REQUIRED |
OPTIONAL |
|
No |
Fault |
OPTIONAL. If
using SOAP, MAP headers MUST NOT have a soap:mustUnderstand
attribute with a value of "true" |
OPTIONAL. If
using SOAP, MAP headers MUST NOT have a soap:mustUnderstand
attribute with a value of "true" |
If WS-A is engaged, use of the
message addressing properties MUST be fully compliant with this specification;
in particular, senders MUST use all message addressing properties mandated by
the Web Services Addressing 1.0 - Core[WS-Addressing-Core],
applicable WS-Addressing protocol bindings (e.g. Web Services Addressing 1.0 -
SOAP Binding[WS-Addressing-SOAP]),
and this specification, and MUST follow all applicable WS-Addressing normative
requirements.
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. This
inclusion allows the usage of both anonymous or
non-anonymous URIs as addresses in an EPR. 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]. The element may extend the semantics of the endpoint's
WSDL binding. The semantics of the extension for SOAP1.1/HTTP is defined in
this document in Section 3.1.2.
3.1.1 wsaw:Anonymous element:
WS-Addressing defines a wsaw:Anonymous element that may be
only be used in conjunction with wsaw:UsingAddressing
element. This usage of this element is associated with the usage constraints specified
for wsaw:UsingAddressing
element. Hence, it MUST NOT contain the wsdl:required attribute.
The wsaw:Anonymous element MAY have three distinct values
that indicate three different levels of support for handling anonymous
addresses in EPRs:
·
“optional”: This value indicates that [reply endpoint] or
[fault endpoint] EPR in a request message MAY contain an anonymous URI as an
address.
·
“required”: This value indicates that [reply endpoint] and
[fault endpoint] EPRs in a request message MUST
always use anonymous URI as an address.
If
[reply endpoint] or [fault endpoint] EPR does not contain the anonymous URI as
an address value, then a predefined InvalidAddressingHeader
fault defined in Section 5.4.x.x of Web Services Addressing 1.0 - SOAP Binding[WS-Addressing-SOAP] MUST be
generated (I already raised a CR issue about this)
·
“prohibited” This value indicates that [reply endpoint] and
[fault endpoint] EPRs in a request message MUST NOT
use anonymous URI as an address.
If
[reply endpoint] or [fault endpoint] EPR contains the anonymous URI as an
address value, then a predefined InvalidAddressingHeader
fault defined in Section 5.4.x.x of Web Services Addressing 1.0 - SOAP Binding[WS-Addressing-SOAP] MUST be
generated.
This element MAY appear as a
child of operation element in a binding element in WSDL 1.1, or as a binding
operation extension element in WSDL 2.0.
3.1.2 SOAP 1.1/HTTP
Extension Semantics by using wsaw:UsingAddressing
element:
The presence of the wsaw:UsingAddressing element in
the binding or endpoint (port) components of the endpoint description extends
the semantics of the SOAP 1.1/HTTP binding. In the case of the WSDL SOAP/HTTP
synchronous binding for request-response operations, the presence of the wsaw:UsingAddressing element changes
the requirement that the response message be sent over the same HTTP channel
over which the request was received. Further, the presence of the wsaw:Anonymous element may specify
how anonymous addresses are treated specific to an operation defined in a
binding. Therefore, the wsa:replyTo header in the request
MAY contain an address with a value different from the anonymous URI when wsaw:UsingAddressing marker is used by extending the semantics
of SOAP1.1/HTTP binding.
Usage of wsaw:UsingAddressing element indicates that SOAP1.1/HTTP
binding is allowed 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. Hence, the response message MAY be sent over the
same HTTP channel over which the request was received or by opening a separate
connection, depending on the following conditions:
·
When
the value of the [reply endpoint] in the request message contains the anonymous
URI as its address, the response MUST be sent over the same HTTP channel.
·
When
the value of [reply endpoint] contains an address that is different than the
anonymous URI, this extension requires that
o 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 envelope. (Lets discuss
this further)
o The actual response MUST be sent using a
separate connection using the address value of the response message specified
by [reply endpoint].
The wsaw:Anonymous element specifies the following semantics for
a specific operation in SOAP1.1/HTTP:
·
“optional” value indicates the same semantics that is defined
for wsaw:UsingAddressing above, namely anonymous URIs are allowed, but not required.
·
“required” value indicates that the response message be sent
over the same HTTP channel over which the request was received. In essence, it
indicates requirement for always using synchronous responses.
·
“prohibited” value indicates that SOAP1.1/HTTP binding must
always use a separate connection for sending response messages, instead of
using the same HTTP connection. In essence, it indicates requirement for always
using asynchronous responses.
Note: We may consider including a paragraph here as a note to
indicate that SOAP processing rules dictate how responses/errors are generated
and sent to appropriate destinations depending on when the extensions are
processed and engaged following the discussion in the wg.
3.1.3 Examples:
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
<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 allows asynchronous responses
in WSDL 1.1 and with a specific operation that requires synchronous responses
<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>
<wsaw:Anonymous>required</wsaw:Anonymous>
</operation>
<operation name=”OtherOp”>…</operation>…
</binding>