soap:header extensibility with mU primer example

A proposed section for the Primer if people accept the example and
motivation.

 

Additional 5.2.5.4.  Additional mandatory elements in header.

 

A primary motivation for soap:mustUnderstand is to enable a client to
ensure that a service understands a soap header block that the client
sends.  Imagine that the reservation interface is controlled by a 3rd
party such as a travel consortium.  The travel consortia decides to make
the NumberOfGuests a soap header block rather than part of the body,
perhaps on the initial version or a subsequent version.  There are a
variety of reasons for this.  The extension could be handled in a well
factored design at the service by a specialized piece of software.   A
3rd party specifying the header blocks is why Web Service specifications
will often require that the mustUnderstand flag is set to true. 

 

The binding using mustUnderstand is:

 

<operation ref="tns:opCheckAvailability">

       <input>

         <wsoap:header wsoap:mustUnderstand="true"
element="tns:NumberOfGuests"/>

       </input>

    </operation>

 

Any client that uses the new interface will set the soap:mustUnderstand
attribute in the message.  If the service receiving the messages does
not understand the extension, it will fault.

 

Cheers,

Dave