2007-09-04 diff-marked version: Web Services Addressing 1.0 - Metadata

3.1.1 Addressing Assertion

The wsam:Addressing policy assertion is a nested policy container assertion. The meaning of this assertion, when present in a policy alternative, is that WS-Addressing is required to communicate with the subject. The wsam:Addressing assertion indicates that there are no restrictions on the use of WS-Addressing unless otherwise qualified by assertions in its nested policy expression. In order to indicate that the subject supports WS-Addressing but does not require its use, an additional policy alternative should be provided which does not contain this assertion; the compact authoring style for an optional policy assertion provided by WS-Policy V1.5 [ WS Policy 1.5 ] may be used. The wsp:Optional attribute, as a syntactic shortcut, can be used with the wsam:Addressing assertion. This indicates two policy alternatives, one which contains the policy assertion, and another which does not.

The inclusion of this assertion implies support for the Web Services Addressing 1.0 - Core [ WS-Addressing Core ] and Web Services Addressing 1.0 - SOAP Binding [ WS-Addressing SOAP Binding ].

3.1.2 AnonymousResponses Assertion

The wsam:AnonymousResponses element MAY be used as a policy assertion nested within the wsam:Addressing assertion in accordance with the rules laid down by policy assertion nesting ([ WS Policy 1.5 ], section 4.3.2).

The appearance of this element within the wsam:Addressing policy assertion indicates that the endpoint requires request messages to use response endpoint EPRs that contain the anonymous URI (" http://www.w3.org/2005/08/addressing/anonymous ") as the value of [address]. In other words, the endpoint requires the use of anonymous responses.

The None URI (" http://www.w3.org/2005/08/addressing/none ") may appear as the value of [address] in place of the anonymous URI; this value MUST be accepted.

3.1.3 NonAnonymousResponses Assertion

The wsam:NonAnonymousResponses element MAY be used as a policy assertion nested within the Addressing assertion in accordance with the rules laid down by policy assertion nesting ([ WS Policy 1.5 ], section 4.3.2). The wsam:NonAnonymousResponses policy assertion MUST NOT be used in the same policy alternative as the wsam:AnonymousResponses policy assertion.

The appearance of this element within the wsam:Addressing assertion indicates that the endpoint expresses requires request messages to use response endpoint EPRs that contain something other than the anonymous URI as the value of [address]. In other words, the endpoint requires the use of non-anonymous responses. This assertion is deliberately vague; its presence indicates that some non-anonymous addresses will be accepted but doesn't constrain what such an address might look like. A receiver can still reject a request that contains an address that it doesn't understand or that requires a binding it doesn't support.

The None URI (" http://www.w3.org/2005/08/addressing/none ") may appear as the value of [address] in place of a non-anonymous address; this value MUST be accepted.

3.1.4 Examples (Compact Form)

<wsp:Policy>
    <wsam:Addressing wsp:Optional="true">
        <wsp:Policy/>
    </wsam:Addressing>
</wsp:Policy>

<wsp:Policy>
    <wsam:Addressing>
        <wsp:Policy/>
    </wsam:Addressing>
</wsp:Policy>

<wsp:Policy>
    <wsam:Addressing>
        <wsp:Policy>
            <wsam:NonAnonymousResponses/>
        </wsp:Policy>
    </wsam:Addressing>
</wsp:Policy>

3.1.5 Examples (Normal Form)

<wsp:Policy>
    <wsp:ExactlyOne>
        <wsp:All/>
        <wsp:All>
            <wsam:Addressing>
                <wsp:Policy>
                    <wsp:ExactlyOne>
                        <wsp:All/>
                    </wsp:ExactlyOne>
                </wsp:Policy>
            </wsam:Addressing>
        </wsp:All>
    </wsp:ExactlyOne>
</wsp:Policy>

<wsp:Policy>
    <wsp:ExactlyOne>
        <wsp:All>
            <wsam:Addressing>
                <wsp:Policy>
                    <wsp:ExactlyOne>
                        <wsp:All/>
                    </wsp:ExactlyOne>
                </wsp:Policy>
            </wsam:Addressing>
        </wsp:All>
    </wsp:ExactlyOne>
</wsp:Policy>

<wsp:Policy>
    <wsp:ExactlyOne>
        <wsp:All>
            <wsam:Addressing>
                <wsp:Policy>
                    <wsp:ExactlyOne>
                        <wsp:All>
                            <wsam:NonAnonymousResponses/>
                        </wsp:All>
                    </wsp:ExactlyOne>
                </wsp:Policy>
            </wsam:Addressing>
        </wsp:All>
    </wsp:ExactlyOne>
</wsp:Policy>

3.1.6 Finding Compatible Policies

When a client is looking for an endpoint with compatible policy, one common method used is to take the policy intersection between the policy which the client is looking for, and the policy asserted in the WSDL document; a non-empty intersection is sought. The policy used by the client must be written carefully to avoid unexpected results. This is most obvious when the client is not looking for explicit support of a particular kind of response; failing to take care could mean missing a compatible policy.

<wsp:Policy>
    <wsp:ExactlyOne>
        <wsp:All>
            <wsam:Addressing>
                <wsp:Policy>
                    <wsp:ExactlyOne>
                        <wsp:All>
                            <AnonymousResponses Optional=”true”/>
                        </wsp:All>
                    </wsp:ExactlyOne>
                </wsp:Policy>
            </wsam:Addressing>
        </wsp:All>
    </wsp:ExactlyOne>
</wsp:Policy>

<wsp:Policy>
    <wsp:ExactlyOne>
        <wsp:All>
            <wsam:Addressing> <-- supports all response types -->
                <wsp:Policy>
                </wsp:Policy>
            </wsam:Addressing>
        </wsp:All>
        <wsp:All>
            <wsam:Addressing> <-- requires Anonymous responses -->
                <wsp:Policy>
                    <wsp:ExactlyOne>
                        <wsp:All>
                            <AnonymousResponses />
                        </wsp:All>
                    </wsp:ExactlyOne>
                </wsp:Policy>
            </wsam:Addressing>
        </wsp:All>
        <wsp:All>
            <wsam:Addressing> <-  requires nonAnonymous responses -->
                <wsp:Policy>
                    <wsp:ExactlyOne>
                        <wsp:All>
                            <NonAnonymousResponses />
                        </wsp:All>
                    </wsp:ExactlyOne>
                </wsp:Policy>
            </wsam:Addressing>
        </wsp:All>
    </wsp:ExactlyOne>
</wsp:Policy>

For more detailed descriptions of the use of wsp:Optional, wsp:Ignorable, and strict and lax intersection, please refer to the WS-Policy Primer [ WS Policy 1.5 - Primer ].

4.1.1 WSDL 2.0 Component Model Changes

Use of WS-Addressing adds the following OPTIONAL properties to the WSDL 2.0 component model:

• A property of the Endpoint component, named {endpoint reference}. This property is of type wsa:EndpointReference, with a cardinality of 1. The property has the value of the wsa:EndpointReference element used as a child of wsdl20:endpoint, if any. If no such extension exists, this property is absent.

4.4.1 Explicit Association

WS-Addressing defines a global attribute, wsam:Action, that can be used to explicitly define the value of the [action] property for messages in a WSDL description. The type of the attribute is xs:anyURI and it is used as an extension on the WSDL input, output and fault elements. A SOAP binding can specify SOAPAction values for the input messages of operations. In the absence of a wsam:Action attribute on a WSDL input element where a non-empty SOAPAction value is specified, the value of the [action] property for the input message is the value of the SOAPAction specified. If the wsam:Action attribute is absent, and SOAPAction is not specified, or is empty, then the default pattern is used. Note that the SOAPAction value is not required to be an absolute IRI, but the [action] property is required to be an absolute IRI; if WS-Addressing is required (the wsam:Addressing assertion is present), wsam:Action is not specified, and the SOAPAction value is not empty or an absolute IRI, then the document MUST be considered invalid. Web Services Addressing 1.0 - SOAP Binding[ WS-Addressing SOAP Binding ] specifies restrictions on the relationship between the values of [action] and SOAPAction for SOAP 1.1 and SOAP 1.2.

The inclusion of wsam:Action without the inclusion of the wsam:Addressing assertion has no normative intent and is only informational. In other words, the inclusion of wsam:Action attributes in WSDL alone does not imply a requirement on clients to use Message Addressing Properties in messages it sends to the service. A client, however, MAY include Message Addressing Properties in the messages it sends, either on its own initiative or as described by other elements of the service contract, regardless of the presence or absence of the wsam:Addressing assertion. Other specifications defining the value of [action] are under no constraint to be consistent with wsam:Action.

For example consider the following WSDL excerpt:

<description targetNamespace="http://greath.example.com/2004/schemas/resSvc" ...>
  ...
  <interface name="reservationInterface">
    <operation name="opCheckAvailability" pattern="http://www.w3.org/ns/wsdl/in-out">
      <input element="tns:checkAvailability" messageLabel="In"
            wsam:Action="http://greath.example.com/2004/wsdl/resSvc/opCheckAvailability"/>
      <output element="tns:checkAvailabilityResponse" messageLabel="Out"
            wsam:Action="http://greath.example.com/2004/wsdl/resSvc/opCheckAvailabilityResponse"/>
    </operation>
  </interface>
  ...
</description>

The action for the input of the opCheckAvailability operation within the reservationInterface is explicitly defined to be http://greath.example.com/2004/wsdl/resSvc/opCheckAvailability. The action for the output of this same operation is http://greath.example.com/2004/wsdl/resSvc/opCheckAvailabilityResponse.

<definitions targetNamespace="http://greath.example.com/2004/schemas/resSvc" ...>
  ...
  <portType name="reservationInterface">
    <operation name="opCheckAvailability">
      <input message="tns:checkAvailability"
            wsam:Action="http://greath.example.com/2004/wsdl/resSvc/opCheckAvailability"/>
      <output message="tns:checkAvailabilityResponse"
            wsam:Action="http://greath.example.com/2004/wsdl/resSvc/opCheckAvailabilityResponse"/>
    </operation>
  </portType>
  ...
</definitions>
      

The action for the input of the opCheckAvailability operation within the reservationInterface port type is explicitly defined to be http://greath.example.com/2004/wsdl/resSvc/opCheckAvailability. The action for the output of this same operation is http://greath.example.com/2004/wsdl/resSvc/opCheckAvailabilityResponse.

4.4.2 Default Action Pattern for WSDL 2.0

In the absence of an explicitly specified value for the [action] property (see section 4.4.1 Explicit Association ), the following pattern is used in WSDL 2.0 documents to construct a default action for inputs and outputs. The general form of an action URI is as follows:

[target namespace][delimiter][interface name][delimiter][operation name][direction token]

For fault messages, the general form of an action IRI is as follows:

[target namespace][delimiter][interface name][delimiter][operation name][direction token][delimiter][fault name]

Where:

[delimiter]

is ":" when the [target namespace] is a URN, otherwise "/". Note that for IRI schemes other than URNs which aren't path-based (i.e. those that outlaw the "/" character), the default action value might not conform to the rules of the IRI scheme. Authors are advised to specify explicit values in the WSDL in this case.

[target namespace]

is the {target namespace} of the interface. If [target namespace] ends with a "/" an additional "/" is not added.

[interface name]

is the {name} of the interface.

[operation name]

is the {name} of the operation.

[fault name]

is the {name} of the fault.

[direction token]

• Empty ("") where the operation's {message exchange pattern} is "http://www.w3.org/ns/wsdl/in-only", "http://www.w3.org/ns/wsdl/robust-in-only", "http://www.w3.org/ns/wsdl/out-only", or "http://www.w3.org/ns/wsdl/robust-out-only".

• "Request" where the operation's {message exchange pattern} is "http://www.w3.org/ns/wsdl/in-out" or "http://www.w3.org/ns/wsdl/in-opt-out" and the message reference's {message label} = 'In'.

• "Solicit" where the operation's {message exchange pattern} is "http://www.w3.org/ns/wsdl/out-in" or "http://www.w3.org/ns/wsdl/out-opt-in" and the message reference's {message label} = 'Out'.

• "Response" where the operation's {message exchange pattern} is "http://www.w3.org/ns/wsdl/in-out" or "http://www.w3.org/ns/wsdl/in-opt-out" and the message reference's {message label} = 'Out'.

• "Response" where the operation's {message exchange pattern} is "http://www.w3.org/ns/wsdl/out-in", or "http://www.w3.org/ns/wsdl/out-opt-in" and the message reference's {message label} = 'In'.

• {message label} where the {message exchange pattern} is not one of the MEP IRIs defined in WSDL 2.0 Part 2.

For example consider the following WSDL excerpt:

<description targetNamespace="http://greath.example.com/2004/wsdl/resSvc" ...>
  ...
  <interface name="reservationInterface">
    <operation name="opCheckAvailability" pattern="http://www.w3.org/ns/wsdl/in-out">
      <input element="tns:checkAvailability" messageLabel="In"/>
      <output element="tns:checkAvailabilityResponse" messageLabel="Out"/>
    </operation>
  </interface>
  ...
</definitions>
      

4.4.3 WSDL 2.0 Component Model Changes

Use of WS-Addressing adds the following REQUIRED properties to the WSDL 2.0 component model:

• A property of the Interface Message Reference and Interface Operation InFault/OutFault components named {action}. The property is of type xs:anyURI. The property value is either explicitly specified, as described in section 4.4.1 Explicit Association , or the default value computed following the rules from section 4.4.2 Default Action Pattern for WSDL 2.0 .

4.4.4 Default Action Pattern for WSDL 1.1

A default pattern is also defined for backwards compatibility with WSDL 1.1. In the absence of an explicitly specified value for the [action] property (see section 4.4.1 Explicit Association ), the following pattern is used to construct a default action for inputs and outputs. The general form of an action IRI is as follows:

[target namespace][delimiter][port type name][delimiter][input|output name]

For fault messages, the general form of an action IRI is as follows:

[target namespace][delimiter][port type name][delimiter][operation name][delimiter]Fault[delimiter][fault name]

Where:

[delimiter]

is ":" when the [target namespace] is a URN, otherwise "/". Note that for IRI schemes other than URNs which aren't path-based (i.e. those that outlaw the "/" character), the default action value might not conform to the rules of the IRI scheme. Authors are advised to specify explicit values in the WSDL in this case.

"Fault"

is a literal character string to be included in the action.

[target namespace]

is the target namespace (/definition/@targetNamespace). If [target namespace] ends with a "/" an additional "/" is not added.

[port type name]

is the name of the port type (/definition/portType/@name).

[operation name]

is the {name} of the operation.

[input|output name]

is the name of the element as defined in Section 2.4.5 of WSDL 1.1.

[fault name]

is the name of the fault (/definition/porttype/operation/fault/@name).

For example consider the following WSDL excerpt:

<definitions targetNamespace="http://greath.example.com/2004/wsdl/resSvc" ...>
  ...
  <portType name="reservationInterface">
    <operation name="opCheckAvailability">
      <input message="tns:checkAvailability" name="CheckAvailability"/>
      <output message="tns:checkAvailabilityResponse" name="Availability"/>
          <fault message="tns:InvalidDate" name="InvalidDate"/>
    </operation>
  </portType>
  ...
</definitions>
      

WSDL defines rules for a default input or output name if the name attribute is not present. Consider the following example:

<definitions targetNamespace="http://greath.example.com/2004/wsdl/resSvc" ...>
  ...
  <portType name="reservationInterface">
    <operation name="opCheckAvailability">
      <input message="tns:checkAvailability"/>
      <output message="tns:checkAvailabilityResponse"/>
    </operation>
  </portType>
  ...
</definitions>
      

5.1.1 One-way

This is a straightforward one-way message. No responses are expected but related messages could be sent as part of other message exchanges.

5.1.2 Request-Response

This is request-response. A reply is expected hence mandating [reply endpoint] in the request message. The response message might be a fault.

5.1.3 Notification

From the WS-Addressing perspective this MEP is the same as One-way. The properties defined in 5.1.1 One-way apply to this MEP also.

5.1.4 Solicit-response

From the WS-Addressing perspective this MEP is the same as Request-response. The properties defined in 5.1.2 Request-Response apply to this MEP also.

5.2.1 In-only

This is a straightforward one-way message. No responses are expected but related messages could be sent as part of other message exchanges.

5.2.2 Robust In-only

This one-way MEP allows fault messages. The [message id] property is needed in the initial message in order to be able to correlate any fault with that message.

* Note that at least one of [fault endpoint] or [reply endpoint] is required for this MEP, so that a fault can be sent if necessary.

5.2.3 In-out

This is a two-way MEP. A reply is expected hence mandating [reply endpoint] in the request message. The response message might be a fault.

5.2.4 In-optional-out

This MEP differs from the In-out MEP in that the subsequent message is optional. This difference doesn't affect the message properties so the properties defined in 5.2.3 In-out apply to this MEP also

5.2.5 Out-only

From the WS-Addressing perspective this MEP is the same as In-only. The properties defined in 5.2.1 In-only apply to this MEP also.

5.2.6 Robust Out-only

From the WS-Addressing perspective this MEP is the same as Robust In-only. The properties defined in 5.2.2 Robust In-only apply to this MEP also.

5.2.7 Out-in

From the WS-Addressing perspective this MEP is the same as In-out. The properties defined in 5.2.3 In-out apply to this MEP also.

5.2.8 Out-optional-in

This MEP differs from the Out-in MEP in that the subsequent message is optional. This difference doesn't affect the message properties so the properties defined in 5.2.3 In-out apply to this MEP also