Prev Up Next
17.1.15.PL Procedures and UDT Methods Syntax Affecting WSDL & SOAP Processing Home 17.1.17.Exposing & Processing SOAP Fault Messages

17.1.16.Exposing & Processing SOAP Header Messages

The Virtuoso SOAP server can be used to process the SOAP Header messages as described in the W3C recommendation (http://www.w3c.org/TR/SOAP , SOAP Header section). They can also be exposed in the WSDL file (services.wsdl) as per W3C WSDL recommendation, using the RPC style encoding.

To bind a message to a SOAP header the special keyword __soap_header is reserved for input and output parameters. The __soap_header followed by the SOAP datatype can be specified for any input or output parameter after normal datatype declarations. This will expose parameters as input or output messages separately. Header binding will also be added to an appropriate section of the WSDL description file for the SOAP message.

Example17.13.Processing of the SOAP Header element

Consider the following simple SOAP request message with Header element:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
       xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
       xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
       xmlns:xsd="http://www.w3.org/2001/XMLSchema"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
    <SOAP-ENV:Header>
      <h:echoMeStringRequest
         xmlns:h="http://soapinterop.org/echoheader/"
         SOAP-ENV:actor="http://schemas.xmlsoap.org/soap/actor/next"
         mustUnderstand="1">hello world</h:echoMeStringRequest>
    </SOAP-ENV:Header>
    <SOAP-ENV:Body>
      <m:echoVoid xmlns:m="http://soapinterop.org/"></m:echoVoid>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

This request will be processed by the Virtuoso SOAP server in the following way:

  1. Check whether the echoVoid operation is defined for the given web directory mapping (see: exposing a PL procedure as a SOAP operation)

  2. Test whether there is an in-parameter echoMeStringRequest defined for header processing (see below exposing a header parameters)

  3. Test the mustUnderstand attribute:

    • If mustUnderstand is 0 or is undefined the request will continue without an error.

    • If mustUnderstand is 1 and the actor attribute is not empty or defined with the http://schemas.xmlsoap.org/soap/actor/next special URI, the request will continue without an error.

    • If the two conditions about fail then the request will be rejected with a SOAP MustUnderstand error.

  4. The value of the echoMeStringRequest will be passed as a parameter to the echoVoid procedure.

  5. If the call to the echoVoid succeeds, and the corresponding out parameter is supplied for the SOAP response header then it will be sent to the SOAP client.

The following procedure, which represents a part from echoHeaderBindings iterop test (round C), for the demonstration purposes is designed to process the above SOAP message.

create procedure
Interop.INTEROP.echoVoid
   (in echoMeStringRequest nvarchar := NULL __soap_header 'http://www.w3.org/2001/XMLSchema:string',
    out echoMeStringResponse nvarchar := NULL __soap_header 'http://www.w3.org/2001/XMLSchema:string')
   __soap_type '__VOID__'
{
  if (echoMeStringRequest is not null)
    echoMeStringResponse := echoMeStringRequest;
};
[Note] Note:

The __soap_header keyword that instructs the SOAP server to process this parameter via a SOAP Header with datatype string. Also, the condition in the procedure is needed to return the value in SOAP header only if it is supplied. In some other cases it can be returned always, but in this particular example it will be echoed only if the appropriate header is sent.

Prev Up Next
17.1.15.PL Procedures and UDT Methods Syntax Affecting WSDL & SOAP Processing Home 17.1.17.Exposing & Processing SOAP Fault Messages