Web Services Architecture and Its Specifications [Electronic resources] : Essentials for Understanding WS-* نسخه متنی

Addressing: Reference Parameters and Reference Properties

The reference parameter and reference property features of WS-Addressing support communicating additional information in requests. In our Purchase Order example, both reference parameters and reference properties are used.

A reference property can be added to the Endpoint Reference to indicate which order management system should process the message, thereby impacting the service contract. So, if the publisher has systems dedicated to different groups of customers with multiple service levels or underlying processes, a reference property can be added to represent each customer group. In our case, we add an example reference property for educational customers.

A reference parameter can also be added to the Endpoint Reference to carry the customer contract information in the SOAP header. In our example scenario, we assume that this information is used by the order management system to help with message auditing and reporting. This reference parameter does not change the service contract.

Important

Information carried in a reference parameter does not change the service contract with the Web service. Information carried in a reference property does change the service contract.

Reference Properties and Parameters
(01) <msp:OrderServiceInfo>
(02)   xmlns:msp="http://ex.mspress.microsoft.com">
(03)  <wsa:Address>http://ex.mspress/microsoft.com/orders</wsa:Address>
(04)  <wsa:ReferenceProperties>
(05)  <msp:CustomerType>Education</msp:CustomerType>
(06)  </wsa:ReferenceProperties>
(07)  <wsa:ReferenceParameters>
(08)  <msp:InternalAccount>sfa0704</msp:InternalAccount>
(09)  </wsa:ReferenceParameters>
(10) </msp:OrderServiceInfo>

Line 02 The definitions of reference property and reference parameter values are determined by the receiving application.

Lines 0406 The required reference properties are included in the Endpoint Reference. In this case, the application-specific CustomerType element is used to help address and route requests.

Lines 0709 The required reference parameters are included in the Endpoint Reference. In this case, the application-specific InternalAccount element is used to help with message auditing and reporting once it is routed to the correct service.

We note that while the reference property CustomerType could be the same for all educational establishments, the InternalAccount reference parameter will be specific to each school. So, in our example scenario, the sending systems at each school must have an Endpoint Reference with the appropriate InternalAccount reference parameter information to use when communicating with the order management system.

When the PurchaseOrder request is sent to the endpoint, the contents of the reference properties and reference parameters are included as children of the SOAP header.

Reference Properties and Parameters in Headers
(01) <env:Header>
(02)  <wsa:To:>http://ex.mspress.microsoft.com/orders</wsa:To>
(03)  <msp:CustomerType>Education</msp:CustomerType>
(04)  <msp:InternalAccount>sfa0704</msp:InternalAccount>
(05)  <wsa:From>http://fineartschool.net/orders</wsa:From>
(06)  <wsa:ReplyTo>http://fineartschool.net/orders</wsa:ReplyTo>
(07)  <wsa:FaultTo>http://fineartschool.net/status</wsa:FaultTo>
(08)  <wsa:Action>http://ex.mspress.microsoft.com/PO</wsa:Action>
(09) </env:Header>