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

HTTP Binding Component User's Guide

SOAP 1.2 `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 1.2 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 13 SOAP 1.2 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

The following example illustrates the SOAP 1.2 header element.

<wsdl:definitions ... >
...
	<wsdl:binding ... >
...
		<wsdl:operation ... >
...
			<wsdl:input ... >*
				<soap12:header message="xs:QName"
						part="xs:NMTOKEN"
						use="literal|encoded"
						namespace="xs:anyURI" ?
						encodingStyle="xs:anyURI" ? ... /> *
...
			</wsdl:input>
			<wsdl:output ... >*
				<soap12:header message="xs:QName"
						part="xs:NMTOKEN"
						use="literal|encoded"
						namespace="xs:anyURI" ?
						encodingStyle="xs:anyURI" ? ... /> *
...
			</wsdl:output>
		</wsdl:operation>
...
	</wsdl:binding>
...
</wsdl:definitions>

The message attribute (of type xs:QName), together with the parts attribute, indicates which message parts are bound as children of the SOAP 1.2 header element of the message. The referenced message does not need to be the same as the message that defines the SOAP Body.

The parts attribute (of type xs:NMTOKEN), together with the message attribute, indicates which message part is bound as a child of the SOAP 1.2 header element of the message.

The namespace attribute (of type xs:anyURI), if present, defines the namespace to be assigned to the header element serialized with use="encoded". In all cases, the header is constructed as if the style attribute of the wsoap12:binding element, of the containing wsdl:binding, has a value of “document”. The value of the namespace attribute, if present, must not be a relative URI.

The use attribute indicates whether the message parts are encoded using some encoding rules, or whether the parts define the concrete schema of the message. If the value is "encoded" the message parts are encoded using some encoding rules as specified by the value, actual or implied, of the encodingStyle attribute. If the value is "literal" then the message parts are literally defined by the schema types referenced.

The encodingStyle attribute (of type xs:anyURI), if present, identifies the set of encoding rules used to construct the message. This attribute must not be present unless the style attribute, of the soap12:binding element, of the containing wsdl:binding, has a value of “rpc” and the use attribute, on the containing soap12:body element, has a value of "encoded". The value of the encodingStyle attribute, if present, must not be a relative URI.

/soap12:header/@{any}}} is an extensibility mechanism that enables additional attributes, that are defined in a foreign namespace, to be added to the element.

Optional soap12:headerfault elements, which appear inside wsoap12:header elements, specify the header types used to transmit error information pertaining to the header, defined by the soap12:header.

Table 14 SOAP 1.2 headerfault Element Attributes


Property	Description	Required or Optional	Example
message	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 1.2 headerfault element.

<wsdl:definitions ... >
...
	<wsdl:binding ... >
...
		<wsdl:operation ... >
...
			<wsdl:input ... >
	
				<soap12:header ... >
					<soap12:headerfault message="xs:QName"
								part="xs:NMTOKEN"
								use="literal|encoded"
								namespace="xs:anyURI" ?
								encodingStyle="xs:anyURI" ?
											... /> *
				</soap12:header> *
...
			</wsdl:input> *
			<wsdl:output ... >
				<soap12:header ... >
					<soap12:headerfault message="xs:QName"
								part="xs:NMTOKEN"
								use="literal|encoded"
								namespace="xs:anyURI" ?
								encodingStyle="xs:anyURI" ?
											... /> *
				</soap12:header> *
...
			</wsdl:output> *
		</wsdl:operation>
...
	</wsdl:binding>
...
</wsdl:definitions>

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

The message attribute (of type xs:QName), together with the parts attribute, indicates which message part is to be bound as a child of the SOAP 1.2 header element of the message, for returning faults pertaining to the enclosing soap12:header. The referenced message does not need to be the same as the message that defines the SOAP Body.

The parts attribute (of type xs:NMTOKEN), together with the message attribute, indicates which message part is to be bound as a child of the SOAP 1.2 header element of the message for returning faults pertaining to the enclosing soap12:header.

The namespace attribute (of type xs:anyURI), if present, defines the namespace to be assigned to the wrapper element for an rpc-style operation. This attribute is ignored if the style attribute of either the soap12:binding element, of the containing wsdl:binding or of the soap12:operation element of the containing wsdl:operation, is either omitted or has a value of “document”. This attribute must be present if the value of the style attribute of the soap12:binding element of the containing wsdl:binding is “rpc”. The value of the namespace attribute, must not be a relative URI.

The use attribute indicates whether the message parts are encoded using some encoding rules, or whether the parts define the concrete schema of the message. If the value is "encoded" the message parts are encoded using some encoding rules, as specified by the value, actual or implied, of the encodingStyle attribute. If the value is "literal" then the message parts are literally defined by the schema types referenced.

The encodingStyle attribute (of type xs:anyURI), if present, identifies the set of encoding rules used to construct the message. This attribute must not be present unless the style attribute, of the soap12:binding element, of the containing wsdl:binding, has a value of “rpc” and the use attribute on the containing soap12:body element has a value of "encoded". The value of the encodingStyle attribute must not be a relative URI.

/soap12:headerfault/@{any}}} is an extensibility mechanism that enables additional attributes, defined in a foreign namespace, to be added to the element.