Defining SOAP Headers

SOAP headers are defined by the Web service provider application. The steps to follow when defining these headers are as follows.

Create a subclass of the JadeWebServiceSoapHeader class.
Add properties to this class that you want to send in the SOAP header.
Add a property reference to this class in your Web service provider class.
Select the methods for which you want to generate the SOAP header.

The following simple example demonstrates how to create and use a SOAP header in JADE. The example uses the Erewhon Investments example system.

Step 1: Create a subclass of the JadeWebServiceSoapHeader class

Call this class ErewhonHeader. The class can be defined as shown in the following image.

We will define the options for the header on the Web Services sheet, as shown in the following image.

We have defined the SOAP header direction as I-O (the default value is Input). The following meanings apply to this setting.

Input – This means that the SOAP header is provided by the Web service client and input to the Web service. The Web service itself does not send a SOAP header.
I-O – Both the Web service client and the Web service send this header.
Output – Only the Web service sends this header. The Web service client receives this header but does not send it back.

The Must Understand attribute is set to true. (Its usage was explained in the previous section.)

Step 2: Add properties to the class

Add the following single String property to this class.

Name: priority, type: String, length: 30, access: public

Step 3: Add a property reference to this class in your Web service provider class

Add the following property reference to the SOAP header class created in step 1 to the ErewhonInvestmentsService class.

Name: erewhonHeader, type: ErewhonHeader, access: public

Step 4: Select the methods for which you want to generate the SOAP header

Add the header to the ErewhonInvestmentsService class getClient method. To do this, right‑click on this method and then select the Web Services Options menu item. This displays the dialog shown in the following image.

Select the ErewhonHeader entry and then click OK.

That’s it for defining the header.

When the WSDL is generated, all of the required information for the SOAP header is generated. Importing this Web service into a client now creates a subclass of the JadeWebServiceSoapHeader class on the client, as shown in the following image.

You can now create an instance of this class and set its priority property to send to the Web service, as follows.

vars
    wsc    : WSD_ErewhonInvestmentsService;
    was    : GetClient;
    wasr   : GetClientResponse;
    header : ErewhonHeader;
begin
    create wsc;
    create was;
    // create the header and assign this to the property
    create header;
    header.priority := 'HIGH';
    wsc.erewhonHeader := header;
    was.clientName := "Brian Olsen";
    wasr := wsc.getClient(was);
epilog
    delete was;
    delete wsc;
end;

The SOAP message that is generated from this call includes the SOAP header, as follows.

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tns="urn:JadeWebServices/WebServiceOverHttpApp/" xmlns:s1="urn:JadeWebServices/WebServiceOverHttpApp/">
    <soap:Header>
        <s1:erewhonHeader>
            <s1:priority>HIGH</s1:priority>
        </s1:erewhonHeader>
    </soap:Header>
    <soap:Body>
        <s1:getClient>
            <s1:clientName>Brian Olsen</s1:clientName>
        </s1:getClient>
    </soap:Body>
</soap:Envelope>

The Web service can now check the header and decide whether to give this request a HIGH priority or not. If it does not, it can then set the priority value to MEDIUM, for example, and when the Web service client gets this header back, it knows that it’s request for HIGH priority was rejected.

If you had several of these methods where the header is applicable, you need only to hook up these methods with the header. If you did not have this header, this value would need to be passed as a parameter on each applicable method. If you then wanted to send additional parameters, you would need to add this to all affected methods. This can become cumbersome and error‑prone. Another way of looking at this is that SOAP headers provide you with ‘parameter refactoring’ for Web services.