Adding and Using WS-Addressing Header Elements

This chapter describes how to add and use WS-Addressing header elements.

For a link to details about this standard, see the section “Standards Supported by Caché” in the first chapter.

Also see the section “Adding WS-Addressing Header Elements When Faults Occur,” earlier in this book.

Overview

You can add WS-Addressing header elements to your SOAP messages, as specified by the WS-Addressing standards for SOAP 1.1 and SOAP 1.2. To do so, do one of the following:

Specify the WSADDRESSING parameter of your web service or client as "AUTO". This option adds a default set of WS-Addressing header elements, discussed in a following subsection.
Specify WSADDRESSING as "OFF" (the default) and add WS-Addressing header elements manually, as discussed in a following subsection.
Create a policy for the web service or client to include WS-Addressing header elements. To do so, you create and compile a configuration class that refers to the web service or client; in this policy, enable WS-Addressing. See Securing Caché Web Services.
If you attach such a policy, Caché uses the same set of default WS-Addressing header elements by default. You can create and add WS-Addressing header elements manually instead.
If you attach such a policy, your value for WSADDRESSING is ignored.

Effect on the WSDL

For a web service, the WSADDRESSING parameter does not affect the generated WSDL. Similarly, if you specify this for a web client, it is not necessary for the WSDL to change.

A policy statement that refers to WS-Addressing does affect the WSDL; if you add a policy statement, it is necessary to regenerate any web clients. For a Caché web client, you can simply attach a WS-Addressing policy statement to the client instead of regenerating the client classes.

Default WS-Addressing Header Elements

This section describes and shows examples of the default WS-Addressing header elements that Caché uses.

Default WS-Addressing Header Elements in Request Messages

If you enable WS-Addressing as described previously in this section, the web client includes the following WS-Addressing header elements in its request messages:

To:destination address
Action: SoapAction
MessageID: unique uuid
ReplyTo: anonymous

For example:

<?xml version="1.0" encoding="UTF-8" ?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV='http://schemas.xmlsoap.org/soap/envelope/' 
                   xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' 
                   xmlns:s='http://www.w3.org/2001/XMLSchema' 
                   xmlns:wsa='http://www.w3.org/2005/08/addressing'>
   <SOAP-ENV:Header>
      <wsa:Action>http://www.myapp.org/GSOAP.DivideAddressingWS.Divide</wsa:Action>
      <wsa:MessageID>urn:uuid:91576FE2-4533-43CB-BFA1-51D2B631453A</wsa:MessageID>
      <wsa:ReplyTo>
         <wsa:Address xsi:type="s:string">http://www.w3.org/2005/08/addressing/anonymous</wsa:Address>
      </wsa:ReplyTo>
      <wsa:To>http://localhost:8080/csp/gsop/GSOP.DivideAddressingWS.cls</wsa:To>
   </SOAP-ENV:Header>
   <SOAP-ENV:Body>
      <Divide xmlns="http://www.myapp.org">
         <arg1 xsi:type="s:decimal">1</arg1>
         <arg2 xsi:type="s:decimal">7</arg2>
      </Divide>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Default WS-Addressing Header Elements in Response Messages

If you enable WS-Addressing as described previously in this section and if the request message includes WS-Addressing header elements, the web service includes the following WS-Addressing header elements in its response messages:

To: anonymous
Action: SoapAction_"Response"
MessageID: unique uuid
RelatesTo: MessageID of request

For example:

<?xml version="1.0" encoding="UTF-8" ?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV='http://schemas.xmlsoap.org/soap/envelope/' 
                   xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' 
                   xmlns:s='http://www.w3.org/2001/XMLSchema' 
                   xmlns:wsa='http://www.w3.org/2005/08/addressing'>
   <SOAP-ENV:Header>
      <wsa:Action>http://www.myapp.org/GSOAP.DivideAddressingWS.DivideResponse</wsa:Action>
      <wsa:MessageID>urn:uuid:577B5D65-D7E3-4EF7-9BF1-E8422F5CD739</wsa:MessageID>
      <wsa:RelatesTo>urn:uuid:91576FE2-4533-43CB-BFA1-51D2B631453A</wsa:RelatesTo>
      <wsa:To>http://www.w3.org/2005/08/addressing/anonymous</wsa:To>
   </SOAP-ENV:Header>
   <SOAP-ENV:Body>
      <DivideResponse xmlns="http://www.myapp.org">
         <DivideResult>.1428571428571428571</DivideResult>
      </DivideResponse>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Adding WS-Addressing Header Elements Manually

Instead of using the default WS-Addressing header elements, you can create and add your own elements manually. To do so:

Create an instance of %SOAP.Addressing.PropertiesOpens in a new tab and specify its properties as needed. For details, see the class reference.
Set the AddressingOut property of the web service or client equal to this instance of %SOAP.Addressing.PropertiesOpens in a new tab.

Note:

If you set the AddressingOut property, the web service or web client uses the WS-Addressing header elements in this property rather than any WS-Addressing elements specified in an attached policy.

Handling WS-Addressing Header Elements

When a Caché web service or client receives a message that includes WS-Addressing header elements, the AddressingIn property of the service or client is updated to equal an instance of %SOAP.Addressing.PropertiesOpens in a new tab. Your web service or client can then examine the details of its AddressingIn property.

For details on %SOAP.Addressing.PropertiesOpens in a new tab, see the class reference.