Headers and Hrefs
by Sam Ruby, March 29, 2002.
This document describes a few aspects of the SOAP protocol not covered by the Gentle Introduction to SOAP or the Busy Developer's Guide to SOAP 1.1, and includes some updates that occurred in the year that since the BDG was developed..
A snail-mail envelope not a mere pocket into which information can be inserted. Generally, there may be interesting data outside of the envelope that assists in the delivery... things like who the messages is from, who it is too, perhaps where it has been, or where it is going. It may also have a tracking number. In the cyber world of SOAP, these types of information are typically placed in headers. A SOAP Envelope may have an optional header preceding the body and that header may have any number of elements. Here's an example of tracking id encoded in accordance with the WS-Routing proposal.
<SOAP:Envelope
xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP:Header>
<rp:path
xmlns:rp="http://schemas.xmlsoap.org:rp/">
<rp:id>uuid:#CD459DB-BCDE-4c2a-B0E3-44F4EA60BCF0</rp:id>
</rp:path>
</SOAP:Header>
<SOAP:Body>
<m:helloWorld
xmlns:m="http://www.soapware.org/"/>
</SOAP:Body>
</SOAP:Envelope>
From datastructures 101, here is a doubly linked list of three bears, encapsulated into an array.
<soap:Envelope
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:gl="urn:goldilocks">
<soap:Body>
<gl:getBearsResponse>
<getBearsResult
soapenc:arrayType="gl:bear[3]">
<item
href="#id1"/>
<item
href="#id2"/>
<item
href="#id3"/>
</getBearsResult>
</gl:getBearsResponse>
<bear
id="id1">
<name>Poppa</name>
<next
href="#id2"/>
</doc>
<bear
id="id2">
<name>Momma</name>
<prev
href="#id1"/>
<next
href="#id3"/>
</doc>
<bear
id="id3">
<name>Baby</name>
<prev
href="#id2"/>
</doc>
</soap:Body>
</soap:Envelope>
Note: as an aide to the receiver, it is often helpful to indicate which elements are anchors (in this case getBearsResponse) by adding an attribute soapenc:root="1", and which are merely pointed to (each of the bears) with a soapenc:root="0".
In this case, there are multiple elements outside of the response. It is worth noting that there is nothing in SOAP which precludes there being multiple elements in the response. How this is handled is up to the programming language. Some languages permit multiple output parameters. Other languages achieve this same result by wrapping the results in an object or struct.
Here are three types that SOAPBuilders test for interoperability not mentioned in the BDG: boolean, decimal, hexBinary.
The XML schema recommendation went final in May 2001. Most SOAP stacks will still accept 1999 schema, but at this point you will achieve better interoperability if you use the 2001 version. The one change that affects the BDG? timeInstant became dateTime. Just the name changed, the way dates are formatted did not.
When combined with the Gentle Introduction to SOAP and the Busy Developer's Guide to SOAP 1.1 a reasonable understanding of the SOAP protocol can be achieved. With such a knowledge as a foundation, there are multiple directions one could branch out:
Semantics: What Object Does SOAP Access? and To Infinity and Beyond: the Quest for SOAP Interoperability
Definition: A Busy Developers Guide to WSDL 1.1 parts I and II.
Application: Axis/Radio Interop, Actual and Potential
Philosophy: Dealing with Diversity and Coping with Change