Sample Chapter: Early Adopter Hailstorm (.NET My Services) - SOAP
(Page 4 of 10 )
The choice of SOAP as the communication protocol between HailStorm endpoints and servers is not a surprise. Microsoft's open access strategy and HailStorm's web service-centric nature matches SOAP's language and platform neutrality. However, SOAP never figures in HailStorm as an RPC medium (its original function), carrying objects and serialized structured data across the web. Instead, it uses SOAP's ability to route XML messages over the web to a server ? via zero or more intermediaries, synchronously or asynchronously ? and receive them back the same way. Indeed, a lot more information goes into the header of a SOAP envelope than in its message payload.
Deconstructing a HailStorm Request Message Let's take an example and briefly look at each part of a request message before we go into the real detail. Say a friend has just got married and might need to update her last name in the contacts list stored in your digital safe deposit box by the myContacts service. The message you'd need to send HailStorm would look like this:
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:srp="http://schemas.xmlsoap.org/rp/"
xmlns:m="http://schemas.microsoft.com/hs/2001/10/myContacts/"
xmlns:hs="http://schemas.microsoft.com/hs/2001/10/core"
xmlns:ss="http://schemas.xmlsoap.org/soap/security/2000-12">First, we have the definition of the namespaces at work inside this SOAP envelope/message. These are all pretty standard except number three which changes depending on the service you're addressing.
<s:Header>
<srp:path>
<srp:action>
http://schemas.microsoft.com/hs/2001/10/core#request
</srp:action>
<srp:to>
http://this.cluster.myContacts.msn.com/danm@wrox.com/
</srp:to>
<srp:fwd>
<srp:via/>
</srp:fwd>
<srp:rev>
<srp:via/>
</srp:rev>
<srp:id>
uuid:764CBFB8-A9FF-46D0-BAEC-3D11F9AA44A8
</srp:id>
</srp:path>At the top of the header is the routing information describing what type of message this is, its ultimate destination, and any intermediate points it will need to take on its trip there or on its trip back. Finally, there is the unique identifier for the message that the response will quote back for reference.
<ss:licenses>
<hs:identity>
<hs:kerberos>0123456789ABCDEF</hs:kerberos>
</hs:identity>
</ss:licenses>Second in the list is the Kerberos ticket used for talking with HailStorm. Later in the conversation, you may also include here the role the server has assigned to you as this expedites the carrying out of your instructions.
<hs:request service="myContacts" document="content" method="replace"
genResponse="always">
<hs:key puid="4D36E96A-E325-11CE-BFC1-08002BE10318"
instance="danm@wrox.com" cluster="this.cluster"/>
</hs:request>
</s:Header>Last in the message header is information about the request itself; its destination, purpose, notes for the response, and so on.
We could have included two further elements in the header ? and ? but the former is specific to sending SOAP message asynchronously which we can't at the moment and the latter, which replaces the standard request, wasn't working as we went to press. The XMI manual contains full details of what they should do.
As noted before, the body of the message contains the actual instructions to HailStorm ? in this case, a request to replace your friend's maiden name with her married name.
<s:Body>
<hs:replaceRequest
select="/hs:/myContacts/contact[@id='33']/lastName">
<m:lastName>Simon</m:lastName>
</hs:replaceRequest>
</s:Body>
</s:Envelope>In overview, the construction of the SOAP message remains simple, just as Don Box and company intended when they designed it (SOAP that is). The usually optional element has become mandatory, but that's about it as far as rudimentary SOAP is concerned. To grasp the HailStorm specific pieces, we'll need to start from the top again and look at each message segment in detail.<Envelope>
Setting the Namespaces One of the main reasons that SOAP will become at least the basis for XML web service communications (if it isn't already anyway) is its extensibility. In this particular case, we need to make use of four other namespaces in our message besides the standard one to cover the elements we need to get everything working.
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:srp="http://schemas.xmlsoap.org/rp/"
xmlns:m="http://schemas.microsoft.com/hs/2001/10/myContacts/"
xmlns:hs="http://schemas.microsoft.com/hs/2001/10/core"
xmlns:ss="http://schemas.xmlsoap.org/soap/security/2000-12">In order of declaration, the schemas that define these namespaces represent:
- srp - The SOAP Routing Protocol or SOAP-RP for short. This Microsoft protocol lets us define very precisely the route our message will take to and from the HailStorm server.
- m - The 'Content' document for the myContacts web service containing all the contacts information. Each my* service contains its own unique set of data elements as defined in a schema created specifically for that service. If you were querying the myAlerts service, you would specify the myAlerts schema here instead of that for myContacts. These schemas are covered in full in the XMI manual that accompanies the HailStorm SDK and to a lesser extent in Chapters 4 and 5 of this book.
- hs - The core, non-service-specific elements that HailStorm needs to interject into the message.
- ss - The security extensions to SOAP 1.1 ('SOAP-SEC') that allows a SOAP header entry to carry digital signatures ? in this case the Kerberos ticket for talking with HailStorm. You can find the specification for SOAP-SEC at http://www.w3c.org/TR/SOAP-dsig/
The <envelope> element also omits the declaration of the SOAP serialization namespace that is usually present in SOAP messages. HailStorm messages will only ever be raw XML and won't need to hold any objects, so the reference is redundant.
Note that the URIs for these namespaces change quite often between releases of HailStorm and it's worth keeping an eye on them when a new one arrives. A change here will signify a change in the way the contents of the SOAP messages are structured.
Next: Header >>
More ASP.NET Articles
More By Tim Pabst
