First Class Headers - B

Asir S Vedamuthu, webMethods - Monday February 07, 2005

Lets begin with a simple 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. I added four statements to turn on WS-Security header support - import schema statement, complex type definition that describes a subset of headers, headers in input message reference component and headers in output message reference component.

<?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">
      
      <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" 
               wsdl:mustUnderstand="true"/>
         <xs:element name="isGoldClubMember" 
               type="xs:boolean" wsdl: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"
        headerDescription="tns:myHeaders"/>
      <wsdl:output element="tns:GetLastTradePriceOutput"
        headerDescription="tns:myHeaders"/>
    </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: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>

Proposed solution has eight parts:

(1) Hook Headers into the Interface Fault Component

Add the property {headers}

Add the property {headers} to the Interface Fault Component: {headers} OPTIONAL, a complex type definition that describes a subset of header data. 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 wsdl:mustUnderstand attribute information item.

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

Alternate property names are {header description}, {header type}, {header wrapper type}, {header blocks}, etc.

Modify the XML Representation of Interface Fault Component

<description>
  <interface>
    <fault
          name="xs:NCName" 
          element="xs:QName"?
          headerDescription="xs:QName"? >
      <documentation />?
      [ <feature /> | <property /> ]*
    </fault>
  </interface>
</description>

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

Modify the Mapping of Interface Fault's XML Representation to Component Properties

Addition to Table 2-3:

{headers} = The complex type definition from the {type definitions} property of the Description component resolved to by the value of the headerDescription attribute information item, if present. It is an error for the 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.

(2) Hook Headers into the Message Reference Component

Add the property {headers}

Add the property {headers} to the Message Reference Component: {headers} OPTIONAL, a complex type definition that describes a subset of header data. 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 wsdl:mustUnderstand attribute information item.

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

Alternate property names are {header description}, {header type}, {header wrapper type}, {header blocks}, etc.

Modify the XML Representation of Message Reference Component

<description>
  <interface>
    <operation>
      <input
            messageLabel="xs:NCName"?
            element="union of xs:QName, xs:Token"? 
            headerDescription="xs:QName"? > 
        <documentation />?
        [ <feature /> | <property /> ]*
      </input>
      <output
            messageLabel="xs:NCName"?
            element="union of xs:QName, xs:Token"? 
            headerDescription="xs:QName"? >
        <documentation />?
        [ <feature /> | <property /> ]*
      </output>
    </operation>
  </interface>
</description>

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

Modify the Mapping of Message Reference's XML Representation to Component Properties

Addition to Table 2-6:

{headers} = The complex type definition from the {type definitions} property of the Description component resolved to by the value of the headerDescription attribute information item, if present. It is an error for the 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.

(3) Syntax Level Default Mechanism to Disable Header Construction

Modify the XML Representation of Binding Component

<description>
  <binding
        name="xs:NCName" 
        interface="xs:QName"?
        type="xs:anyURI"
        disableHeadersDefault="xs:boolean"? >
    <documentation />?
    [ <fault /> | <operation /> | <feature /> | <property /> ]*
  </binding>
</description>
The disableHeadersDefault attribute information item allows users to specify a default value for the {disable headers} property of all the Binding Fault and Binding Message Reference Components in a Binding Component. This is a syntactic convenience and does not affect the underlying component model.

(4) Mechanism to Disable Header Construction for the Binding Fault Component

Add the property {disable headers} to Binding Fault Component

{disable headers} OPTIONAL. An xs:boolean. If this property exists and is true, then headers MUST NOT be constructed for this Binding Fault Component. Scope of {disable headers} is limited to the WSDL {headers} property defined for the Interface Fault Component in {fault reference}. This property does not interact with any other WSDL feature, Bindings, Extensions or Feature and Properties framework.

Modify the XML Representation of Binding Fault Component

<description>
  <binding>
    <fault
          ref="xs:QName" disableHeaders="xs:boolean"? >
      <documentation />?
      [ <feature /> | <property /> ]*
    </fault>
  </binding>
</description>

Modify the Mapping of Binding Fault's XML Representation to Component Properties

Addition to Table 2-11:

{disable headers} = The actual value of the disableHeaders attribute information item, if present. If not, the actual value of the disableHeadersDefault attribute information item of the parent wsdl:binding element information item, if present. If not the value as defined by the concrete binding, if applicable.

(5) Mechanism to Disable Header Construction for the Binding Message Reference Component

Add the property {disable headers} to Binding Message Reference Component

{disable headers} OPTIONAL. An xs:boolean. If this property exists and is true, then headers MUST NOT be constructed for this Binding Message Reference Component. Scope of {disable headers} is limited to the WSDL {headers} defined for the Message Reference component being bound by this Binding Message Reference component. This property does not interact with any other WSDL feature, Bindings, Extensions or Feature and Properties framework.

Modify the XML Representation of Binding Message Reference Component

<description>
  <binding>
    <operation>
      <input
            messageLabel="xs:NCName"? disableHeaders="xs:boolean"? >
        <documentation />?
        [ <feature /> | <property /> ]*
      </input>
      <output
            messageLabel="xs:NCName"? disableHeaders="xs:boolean"? >
        <documentation />?
        [ <feature /> | <property /> ]*
      </output>
    </operation>
  </binding>
</description>

Modify the Mapping of Binding Fault's XML Representation to Component Properties

Addition to Table 2-11:

{disable headers} = The actual value of the disableHeaders attribute information item, if present. If not, the actual value of the disableHeadersDefault attribute information item of the ancestor wsdl:binding element information item, if present. If not the value as defined by the concrete binding, if applicable.

(6) Add to SOAP Binding's Default Binding Rules

SOAP Header block construction

Default value of the Binding element's disableHeadersDefault attribute information item is false. Default value of the Binding Fault Component's {disable headers} property and Binding Message Reference Component's {disable headers} property is false.

In the Binding Message Reference or Binding Fault component, if the {disable headers} property is false and if the {headers} property of the bound Message Reference or Interface Fault component exists and non empty, element information items conforming to the complex type definition, in the bound Message Reference or Interface Fault component's {headers} property, MUST be turned into SOAP Header Blocks.

These elements are serialized according to their schemas, and if the wsdl: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.

(7) Add to HTTP Binding's Default Binding Rules

HTTP Header construction

Default value of the Binding element's disableHeadersDefault attribute information item is false. Default value of the Binding Fault Component's {disable headers} property and Binding Message Reference Component's {disable headers} property is false.

In the Binding Message Reference or Binding Fault component, if the {disable headers} property is false and if the {headers} property of the bound Message Reference or Interface Fault component exists and non empty, element information items conforming to the complex type definition, in the bound Message Reference or Interface Fault component's {headers} property, MUST be turned into HTTP headers, if possible.

Only element information items of type "xs:string" or "xs:anyURI" may be serialized. All complex data types are ignored. Attributes on data elements are ignored.

Each such element information item is serialized as follows:

The HTTP header name used is the element information item local name. The element information item local name MUST follow the field-name production rules as specified in section 4.2 of [IETF RFC 2616]; if not, the element information item MUST be ignored. If an HTTP header corresponding to the element information item local name is set by a different mechanism other than the HTTP Binding, such as the HTTP stack or another feature, then an error MUST be raised.

The HTTP header content is serialized from the corresponding element information item value in UTF-8. If this serialization is NOT possible, then the element information item MUST be ignored.

(8) Changes to XML Schema for WSDL 2.0

PENDING