3.1 UsingAddressing Extension Element

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.

                                                                                                                        

Table 3-1. MAPs Present in output message

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>