Sample Chapter: Early Adopter Hailstorm (.NET My Services) - DIME, not MIME?
(Page 7 of 10 )
The reasoning behind the creation of DIME (Direct Internet Message Encapsulation) as MS sees it is twofold:
- SOAP isn't very good at storing certain types of files (for instance binary image files or other XML files with different character encoding) within a message.
- The speed of processing the SOAP message: SOAP message delimiters are only found once the whole message has been parsed. This adds to the overhead incurred in processing the message. Parsing a MIME multipart message can also take long time while trying to determine the various sub-parts of the MIME message.
DIME then is a 'leaner, meaner' binary encapsulation format for multipart documents with the media type 'application/dime'. Like MIME, it doesn't worry about how it will be transported from endpoint to endpoint - just how the components of the message are put together and taken apart. It's SOAP-RP that takes care of this; using DIME is mandatory over UDP and TCP. Unlike MIME, it's very new; Microsoft only released specification document on May 23, 2001.
<Header>/<licenses> - Adding Some Authentication Returning to our original SOAP message, the next part of the <Header> to look at is the <licenses> element. Like the <path>, this too is a mandatory element for a SOAP message targeting a HailStorm service.
<ss:licenses>
<hs:identity>
<hs:kerberos>0123456789ACBDEF</hs:kerberos>
</hs:identity>
<hs:authorizedRole/>
</ss:licenses>The <licenses> element itself is defined by the SOAP-SEC schema extension to SOAP that caters for the embedding of digital signatures inside messages. In our particular case, we're using it to store two things:
- The Kerberos ticket that was generated for us when we logged into Passport. This ticket must be present inside a SOAP request to HailStorm for it to be valid, in a nested <hs:identity>/<hs:kerberos> element.
- The authorizedRole of the current client application with respect to the web service it's talking to - for example, owner, friend, or associate. Typically, this element is empty on first contact with the web service, which then grants it a role license to be used in any subsequent communication. Using this element allows the service to determine whether or not the user has the right privileges to process the request much faster than if the license was not available. Note that a role license is valid only for the duration of the session during which it was created. A new one must be created for each new session with the service.
Note that with the Kerberos authentication system not yet built into Passport, this version of HailStorm at least, must use the artificial ID generated when you provisioned the services for the user. Running the hspost -p at the command prompt, can retrieve this ID.
<hs:kerberos>Insert artificial id here</hs:kerberos>Two more elements you might find here in future releases of HailStorm are <ss:integrity> and <ss:confidentiality>. The former is used to hold any digital signatures that may need to be used and the latter to hold the <encryptedData> element specified by the XML Encryption initiative. Both also understand the SOAP mustUnderstand attribute that can be set to make sure that the recipient understands the whole message or else return an error message.
You can find out more about the SOAP Security Extension at
http://www.w3c.org/TR/SOAP-dsig/.
<Header>/<request> - The Request Header The <request> header element contains all the request information HailStorm requires bar the location of the information to be queried and the actual XMI instruction to be carried out.
<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>There are four attributes for the <request> element itself:
- The service attribute contains the name of the HailStorm service you are querying.
- The document attribute specifies which of the three documents - content, roleList, or system - associated with the service you are trying to access.
- The method attribute contains the name of the HSDL method you are attempting to call against the web service. For example, insert, delete, or update. For more information on HSDL, see Chapter 5.
- The genResponse attribute tells the service whether to create a response to the query and send it back to the address given in or implied by the <rev>/<via> element. This can have three values - always, never, and faultOnly - indicating that a response should always be generated, never be generated, or generated only if an error occurred.
The <key> element meanwhile locates the exact XML document that is carrying the information you need to access. The cluster attribute states which server cluster the document is stored on while the instance attribute distinguishes which instance of the document owned by the entity with the given puid is being addressed. It is quite possible for one user/entity to have two sets of information stored within a service. For example, you could prefer to keep separate a list of business contacts from your personal contacts. In this case, the instance attribute could be all that differentiates the two sets of data from each other.
The puid attribute meanwhile is filled automatically with the Passport id of the entity that logged on and was authenticated by Kerberos. Like the Kerberos license however, while this is what will happen when HailStorm is finally released, for now it must be filled in with the artificial ID that you can retrieve by running hspost -p at the command prompt.
<Body>/<xxxxRequest> - The Request Body Last but by no means least, the body of the SOAP message contains the actual instructions to the service.
<s:Body>
<hs:replaceRequest select="/hs:/myContacts/contact[@id='33']/lastName">
<m:lastName>Simon</m:lastName>
</hs:replaceRequest>
</s:Body>Each instruction is expressed in HailStorm's own data-manipulation language (HSDL), which we look at in Chapter 5. The top-level element represents the instruction given by the method attribute of the <request> element in the header, and its select attribute holds the route to the node in the XML document containing the data to be accessed, given as an XPath string (see Chapter 4 for more on forming these). Any XML nested inside the request is new information with which the user wishes to update or to insert into their DSDB.
Although it has taken a little while to work through it all, the individual elements of a HailStorm request message are pretty easy to take on board and as we'll see later, we won't even need to generate a great deal of the header when the HailStorm runtime libraries become available. For now though, let's take a look at the typical structure of SOAP response message we might get from HailStorm.
Next: The Response from HailStorm >>
More ASP.NET Articles
More By Tim Pabst
