SOAP 1.1 header and headerfault Elements (HTTP Binding Component User's Guide)

HTTP Binding Component User's Guide

SOAP 1.1 `header` and `headerfault` Elements

The header and headerfault elements enable you to define headers that are transmitted inside the header element of the SOAP Envelope. You do not have to exhaustively list all headers that appear in the SOAP Envelope using header. For example, extensions to WSDL may imply specific headers should be added to the actual payload and you do not have to list those headers here.

Table 6 SOAP 1.1 header Element Attributes


Property	Description	Required or Optional	Example
message	Indicates the WSDL message that will be used in binding to the header element	Required	part1
part	Indicates the parts from the WSDL message that will be included in the header element	Required	part1
use	Indicates how message parts will be encoded in the SOAP header	Required	literal
encodingStyle	Indicates a particular encoding style to use	Optional	http://someEncodingStyle
namespace	Indicates the namespace of the wrapper element for RPC style messages	Optional	urn:someNamespace

Table 7 SOAP 1.1 headerfault Element Attributes


Property	Description	Required or Optional	Example
name	Indicates the WSDL message that will be used in binding to the headerfault element	Required	part1
part	Indicates the parts from the WSDL message that will be included in the headerfault element	Required	part1
use	Indicates how message parts will be encoded in the SOAP headerfault	Required	literal
encodingStyle	Indicates a particular encoding style to use	Optional	http://someEncodingStyle
namespace	Indicates the namespace of the wrapper element for RPC style messages	Optional	urn:someNamespace

The following example illustrates the SOAP header and headerfault elements.

<definitions .... >
    <binding .... >
        <operation .... >
           <input>
             <soap:header message="qname" part="nmtoken" use="literal|encoded"
                          encodingStyle="uri-list"? namespace="uri"?>*
               <soap:headerfault message="qname" part="nmtoken" use="literal|encoded"
                                 encodingStyle="uri-list"? namespace="uri"?/>*
             <soap:header>                                
           </input>
           <output>
               <soap:header message="qname" part="nmtoken" use="literal|encoded"
                            encodingStyle="uri-list"? namespace="uri"?>*
                 <soap:headerfault message="qname" part="nmtoken" use="literal|encoded"
                                   encodingStyle="uri-list"? namespace="uri"?/>*
               <soap:header>                                
           </output>
        </operation>
    </binding>
</definitions>

The use, encodingStyle, and namespace attributes are all used in the same way as those used with the body element, except that style="document" is assumed because headers do not contain parameters.

Together, the message attribute (of type QName) and the part attribute (of type nmtoken) reference the message part that defines the header type.

The optional headerfault elements that appear inside the header and have the same syntax as the header, enable you to specify the header types used to transmit error information pertaining to the header, and defined by the header. The SOAP specification states that errors pertaining to headers must be returned in the headers. This mechanism enables you to specify the format of such headers.