Chapter 1 introduced the Direct Internet Message Encapsulation (DIME) protocol as a message-based encapsulation protocol and described how DIME leverages SOAP metadata in a streamlined message encapsulation process that can provide a better solution than Base64 encoding when sending attachments with SOAP messages in a Web service. This chapter offers a detailed look at how to use DIME with SOAP messages, and how Web Services Enhancement (WSE) supports both DIME and the WS-Attachments specification.
DIME was created with a SOAP and Web services “based world in mind. However, since DIME is not limited just to SOAP and Web services, there must be a protocol that defines how to use DIME with SOAP-based Web services. The mechanics of how DIME is used to encapsulate a SOAP message with attachments is described in the WS-Attachments specification. Later in this chapter, we ll look briefly at some of the non-SOAP applications for DIME, such as streaming binary data.
Proposed by IBM and Microsoft, the WS-Attachments specification leverages DIME to enable an XML-based Web service to efficiently send and receive attachments with SOAP messages. These attachments might be binary files, other SOAP messages, XML fragments, or even other DIME messages. Before WS-Attachments and without using DIME, you could still send these types of attachments encoded in the body of a SOAP message. For example, if I wanted to send a large media file in a SOAP response message back to a requesting client, I could do this by encoding the binary attachments as Base64 XML and including them in the body of the SOAP message. However, the processing on each end of the transaction gets bloated when attachments are very large, as Base64 encoding can increase the size of binary data by up to 30 percent, and even trickier if they are digitally signed. Also, if I want to send other SOAP messages, XML documents, or XML fragments that have a different character encoding than the main SOAP message, the processing can get complicated. These are a few of the instances in which a DIME-based approach makes more sense.
What WS-Attachments and DIME describe is a mechanism for sending one or more attachments external to the SOAP message. By keeping the attachments and the SOAP message separate, you save processing on both ends of the Web service interaction by not having to encode binary data to and decode it from Base64 XML. Also, given the nature of parsing a SOAP message, the entire message needs to be read into memory before it can be validated and any internally included data decoded and used ”which, for large binary files, can mean using plenty of memory. DIME, on the other hand, describes the length of a DIME record in the record header, which allows a DIME parser to quickly read through DIME records to locate a SOAP message or specific attachments. WS-Attachments allows us to look at a SOAP message and its related attachments as a single unit that can be encapsulated in a single DIME record. In this arrangement, the SOAP message and any attachments are each contained in their own DIME record, and each record can reference the other records in the message. Let s see how WS- Attachments describes this mechanism.
The WS-Attachments specification primarily defines the concept of a compound SOAP structure, which is essentially a primary SOAP message plus related attachments. While this compound SOAP structure is defined as independent of the DIME encapsulation protocol, it s clear that DIME is what really makes WS- Attachments work. After defining the compound SOAP structure, the rest of the WS-Attachments specification describes how this structure can be encapsulated in a DIME message and sent via HTTP. Now let s delve into the specification and see how it all works.
At the heart of WS-Attachments is the definition of a compound SOAP-structure model. In this model, SOAP messages and any related attachments are defined as having a primary SOAP part, which is the main SOAP request or response message, and zero or more secondary parts . In this case, the secondary part is the attachment itself; the attachment can be any kind of data or data fragment and includes XML and other SOAP or DIME messages. Although it s possible to create a compound SOAP structure made up of multiple SOAP messages, XML documents, or other compound SOAP structures, in most Web service applications these attachments are typically large binary files such as image, sound, or video files that are being sent to or returned from a server.
When defining a compound SOAP structure, you should follow these rules:
The primary SOAP message must be unambiguously defined and contained in the first DIME record.
Compound SOAP structures can be nested, so an attachment can be another structure with its own primary SOAP message and attachments.
An encapsulation mechanism must be defined, but the same mechanism need not be used for all parts (attachments) of the structure.
Each attachment in the structure must be referenced by a Uniform Resource Identifier (URI).
The bindings between the encapsulation mechanism and the message and transport protocols must be defined.
In this model, there is no requirement that the entire structure be processed or even verified. In fact, it might be more efficient to determine, based on the context of the primary SOAP message and the nature of the attachments, whether any of the attachments need to be processed or verified . If this all seems a little vague thus far, it should become much clearer as we begin to focus specifically on DIME as the encapsulation mechanism for a compound SOAP structure.
When using DIME to encapsulate a primary SOAP message and its attachments, the primary SOAP message must be contained in the first DIME record, which must have the MB (Message Begin) flag in the record header set to indicate that it is the first record in the message. The type-related fields for the first DIME record, which contains the primary SOAP message, should be specified depending on the version of SOAP, as shown in Table 3-1.
0x01 (MIME type)
Optionally, you can specify a URI identifier in the ID field of this first record if you need to be able to reference it from any of the attachments.
When a compound SOAP structure is encapsulated, each subsequent record in the DIME message represents an attachment that has a relationship to the primary SOAP message. Optionally, a single attachment can be contained in one or more record chunks , but chunking an attachment doesn t provide much of a performance benefit for DIME over HTTP because the .NET Framework implementation of HTTP buffers the entire message anyway. Each of these subsequent records must have its payload type properly defined by means of either a MIME type or a URI reference according to the DIME specification, and each record must have a URI defined in the ID field so that the attachment can be referenced from the primary SOAP message. Figure 3-1 represents the structure of a primary SOAP message and two jpeg attachment files in a DIME encapsulation. In the figure, notice that the primary SOAP message uses a manifest element to reference the ID fields of the DIME records containing the attachments.
When referencing an attachment, the WS-Attachments specification doesn t try to impose a scheme. However, it does specify the following rules for determining the base URI that must be used when converting relative URIs to absolute URIs. The following rules to determine a base URI should be tested in the order listed:
An absolute URI defined in the primary SOAP message as XML Base.
An absolute URI on the first DIME record.
A URI provided by the underlying transport protocol.
If no other absolute URI is provided, the base URI defaults to thismessage:/ .
Globally unique identifiers (GUIDs) should be used to identify attachments in a DIME message. As for a scheme for referencing the ID of a DIME record containing an attachment from the primary SOAP message, if you re writing a DIME parser, you ll need to create your own manifest in the primary SOAP message that references the ID of each attachment using the href attribute. An example of a primary SOAP message that references an attachment might look like this:
As you know, a DIME message itself is transport agnostic , which allows it to be used with a variety of underlying transport protocols, including HTTP, TCP, and UDP. The only protocol binding explicitly defined by WS-Attachments is the DIME message binding to HTTP.
Although performance benefits for streaming DIME messages can be obtained by using a lower-level protocol such as TCP, in most cases HTTP will be used as the transport for DIME messages. The WS-Attachments specification defines the DIME bindings to HTTP based on the SOAP bindings to HTTP, with the following changes:
For SOAP 1.2 “to “HTTP bindings A compound SOAP structure in a DIME message must have the value application/dime rather than application/soap+xml specified in the HTTP Content Type header field.
For SOAP 1.1 “to “HTTP bindings A compound SOAP structure in a DIME message must have the value application/dime rather than text/xml specified in the HTTP Content Type header field.
In both of these cases, the DIME message must make up the entire body of the HTTP message.
As with HTTP protocol bindings, the Web Services Description Language (WSDL) specification also needs to be extended to provide discoverability for DIME-based Web services. These extensions have been proposed in the WSDL Extension for SOAP in DIME specification found at http://www.gotdotnet.com/team/xml_wsspecs/dime/WSDL-Extension-for-DIME.htm . This specification defines additional XML elements and attributes in WSDL needed to describe DIME- consuming Web services. The major change to WSDL to support DIME involves the addition of the dime:message element in the wsdl:input or wsdl:output element of a Web services operation bindings definition. The dime:message element must include the wsdl:required attribute set to true along with a newly defined layout attribute. This new attribute is used to specify how attachments in a DIME message are referenced by the primary SOAP message. The two possible URI values for the layout attribute are:
http://schemas.xmlsoap.org/ws/2002/04/dime/closed-layout Specifies that all parts of a DIME message be referenced from the primary SOAP message and in the proper order
http://schemas.xmlsoap.org/ws/2002/04/dime/ open -layout Specifies that additional attachments can be included in a DIME message, even though they aren t referenced by the primary SOAP message, provided they come after all of the attachments in the DIME message that are referenced by the SOAP message
Besides these new element definitions, WSDL extensions for DIME also allow the addition of the following three elements in a WSDL file to further describe the nature of DIME attachments used by the service:
content:Type Specifies the value type of an attachment
content:MediaType Specifies the MIME media type of an attachment
content:DocumentType Specifies the value type of an XML document
The following is a sample WDSL file that describes a DIME-based Web service named DimeSample that exposes a SubmitMediaFile Web method that accepts a file name and binary attachment:
<?xml version="1.0" ?>
<xs:attribute ref="ref:location" use="optional"/>
<wsdl:part name="body" element="msg:SubmitMediaFile"/>
<wsdl:binding name="SoapDimeBinding" type="svc:PortType">
<soap:body parts="body" use="literal"/>
Also, this example references the following namespaces, which are introduced in WSDL Extension for SOAP in DIME specification and that are used for describing references and content types of attachments:
From a security standpoint, the WS-Attachments specification gets a little bit thin. Aside from a general warning that attachments can contain malicious code and that you should take the usual precautions , this specification simply states that when individual attachments are signed or encrypted, the information about this encryption must be contained in the primary SOAP message. The WS-Security specification (see Chapter 5 for more information about this specification) describes a method for describing encrypted attachments within the EncryptedData security element. In this way, the EncryptedData element represents the encrypted attachment in the SOAP message, and the encryption method and any key information can be specified within this element. Since the attachment is outside the SOAP message, the CypherData element doesn t contain the actual data but rather a CipherReference element whose URI attribute references the URI of the encrypted attachment.
The following illustrates the use of this element to indicate an encrypted attachment: