Skip to main content

This is documentation for Caché & Ensemble. See the InterSystems IRIS version of this content.

For information on migrating to InterSystems IRIS, see How to Migrate to InterSystems IRIS, available on the WRC Distributions page (login required).

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:

  1. Create an instance of %SOAP.Addressing.Properties and specify its properties as needed. For details, see the class reference.

  2. Set the AddressingOut property of the web service or client equal to this instance of %SOAP.Addressing.Properties.

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.Properties. Your web service or client can then examine the details of its AddressingIn property.

For details on %SOAP.Addressing.Properties, see the class reference.

Feedback