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.Properties 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.Properties.
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.