SOAP Header Blocks in WSDL

Asir S Vedamuthu, webMethods - Sunday January 30, 2005

Example

The following example shows the WSDL definition of a simple service providing stock quotes. This service supports a single operation called GetLastTradePrice, which is deployed using the SOAP 1.2 protocol over HTTP, and uses SOAP Header Blocks.

<?xml version="1.0"?>
<wsdl:description name="StockQuote" 
  xmlns:wsdl="http://www.w3.org/@@@@/@@/wsdl"
  targetNamespace="http://example.com/stockquote"
  xmlns:tns="http://example.com/stockquote"
  xmlns:wsoap="http://www.w3.org/@@@@/@@/wsdl/soap"
  xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
     
  <wsdl:types>
    <xs:schema targetNamespace="http://example.com/stockquote"
      xmlns:xs="http://www.w3.org/2001/XMLSchema" 
      elementFormDefault="qualified">
      <xs:import
        namespace="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
        schemaLocation="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"/>
      <xs:element name="TradePriceRequest">
        <xs:complexType>
          <xs:all>
            <xs:element name="tickerSymbol" type="xs:string"/>
          </xs:all>
        </xs:complexType>
      </xs:element>
      <xs:element name="TradePrice">
        <xs:complexType>
          <xs:all>
            <xs:element name="price" type="xs:float"/>
          </xs:all>
        </xs:complexType>
      </xs:element>
      <xs:complexType name="myHeaders">
        <xs:sequence>
         <xs:element ref="wsse:Security" 
               wsoap:mustUnderstand="true"/>
         <xs:element name="isGoldClubMember" 
               type="xs:boolean" wsoap:mustUnderstand="true"/>
         <xs:element name="promotionalCode" 
               type="xs:string" minOccurs="0"/>
        </xs:sequence>
      </xs:complexType>
    </xs:schema>
  </wsdl:types>
  
  <wsdl:interface name="StockQuoteInterface">
    <wsdl:operation name="GetLastTradePrice" 
      pattern="http://www.w3.org/@@@@/@@/wsdl/in-out">
      <wsdl:input element="tns:GetLastTradePriceInput"/>
      <wsdl:output element="tns:GetLastTradePriceOutput"/>
    </wsdl:operation>
  </wsdl:interface>
  
  <wsdl:binding name="StockQuoteSoapBinding" interface="tns:StockQuoteInterface"
    type="http://www.w3.org/@@@@/@@/wsdl/soap" 
    wsoap:protocol="http://www.w3.org/2003/05/soap/bindings/HTTP/">
    <wsdl:operation ref="tns:GetLastTradePrice" 
      wsoap:action="http://example.com/GetLastTradePrice">
        <wsdl:input wsoap:headerDescription="tns:myHeaders"/>
        <wsdl:output wsoap:headerDescription="tns:myHeaders"/>
    </wsdl:operation>
  </wsdl:binding>
  
  <wsdl:service name="StockQuoteService" interface="tns:StockQuoteInterface">
    <wsdl:documentation>My first service</wsdl:documentation>
    <wsdl:endpoint name="StockQuoteEndPoint" binding="tns:StockQuoteBinding" 
    address="http://example.com/endpoint/stockquote"/>
  </wsdl:service>
  
</wsdl:description>

Binding SOAP Header Blocks

The SOAP binding allows users to declare the SOAP Header Blocks in use on a per Binding Message Reference and per Binding Fault component basis. The SOAP Header Block binding adds the {soap headers} property to Binding Message Reference and Binding Fault components.

{soap headers} - OPTIONAL, a complex type definition that describes a subset of SOAP Header Blocks. This complex type definition has an element only content model and the element declarations in this content model are global element declarations. These element declarations may be decorated using wsoap:mustUnderstand attribute information item.

SOAP Header Blocks other than the ones described in the complex type definition in {soap headers} property may be present at run-time.

Alternate property names are {soap header blocks}, etc.

XML Representation

<description >
  <binding >

    <fault ref="xs:QName"
           wsoap:code="xs:QName"
           wsoap:subcodes="list of xs:QName"? 
           wsoap:headerDesription="xs:QName"?>
    </fault>*
    
    <operation>

	<input messageLabel="xs:NCName"?
		 whttp:transferCoding="xs:string"??
		 wsoap:headerDesription="xs:QName"?>
	<documentation />?
	<wsoap:module ... />*
	[ <feature /> | <property /> ]*
	</input>*

	<output messageLabel="xs:NCName"?
		 whttp:transferCoding="xs:string"??
		 wsoap:headerDesription="xs:QName"?>
	<documentation />?
	<wsoap:module ... />*
	[ <feature /> | <property /> ]*
	</output>*

    </operation>*

  </binding>
</description>

Alternate XML attribute names are - wsoap:headers, wsoap:headerBlocks, wsoap:headerType, wsoap:headerWrapperType, etc.

Mapping XML Representation to Component Property

{soap headers} = The complex type definition from the {type definitions} property of the Description component resolved to by the value of the wsoap:headerDescription attribute information item, if present. It is an error for the wsoap:headerDescription attribute information item to have a value and that value does not resolve to a complex type definition from the {type definitions} property of the Description component.

Default Binding Rules for SOAP Binding

SOAP Header Block Construction

In the Binding Message Reference or Binding Fault component, if the {soap headers} property exists and non empty, element information items conforming to the complex type definition in the {soap headers} property MUST be turned into SOAP Header Blocks. Note: the order of element information items validated by this complex type definition is insignificant.

The element information items are serialized according to their schemas, and if the wsoap:mustUnderstand attribute exists with the value true on any given element declaration, that particular SOAP Header Block should be marked as mustUnderstand='true' or mustUnderstand='1' as per the SOAP specification.

Changes to XML Schema for SOAP Binding

PENDING