XTech 2005: XML, the Web and beyond.

The messaging framework for Web services: SOAP 1.2, MTOM and Web Services Addressing 1.0

Discuss this paper on the XTech wiki
View XML source for this paper

Keywords

Abstract

Web services provide a standard means of interoperating between different software applications, running on a variety of platforms and/or frameworks.

In order to do so, Web services agents exchange XML messages across the World Wide Web, using a variety of protocols (HTTP/1.1, SMTP, …). This paper presents the messaging infrastructure of Web services, built on top of the SOAP Version 1.2 XML-based messaging framework, providing addressing capabilities as well as the possibility of carrying arbitrary non-XML data.

An XML-based extensible messaging framework: SOAP 1.2

SOAP 1.2 offers the basis for the Web services messaging framework. It was published as a W3C Recommendation SOAP 1.2 in June 2003.

SOAP messages are XML documents, representing one-way messages sent from a sender to an ultimate recipient, possibly via some intermediaries. Those messages are composed of a body and a set, possibly empty, of header blocks. The body carries information for the ultimate recipient, while the header blocks may be be targeted at any node along the message path.

SOAP 1.2's core functionality is concerned with providing extensibility. The extensibility mechanisms described below can be used to add capabilities found in richer messaging environments described.

This is this SOAP extensibility model that Web Services Addressing 1.0 WS-Addressing 1.0 - Core and SOAP Message Transmission Optimization Mechanism MTOM use to provide the core Web services messaging framework.

SOAP processing model

The SOAP 1.2 specification SOAP 1.2 defines the processing rules when receiving a SOAP message.

SOAP modules are extensions of the SOAP processing model. They define the syntax and semantics of one or more SOAP header blocks that are transported in a SOAP message.

The processing of those header blocks defined by such an extension allows to add extra functionality to messaging architecture, such as guaranteed message delivery, message integrity, etc.

Web Services Addressing 1.0 presented in is an example of a SOAP module.

It is worth noting that a SOAP header block may be marked with a mustUnderstand attribute whose value is true: in this case, the receiving SOAP processor, if this header is targeted at it, will process the message only if it understands this SOAP header block, i.e. only if can process it according to its defined semantics; otherwise, the processor will fault. This type of extensibility is useful in order to force a SOAP receiver to process a header block which has important semantics, e.g. which sets the order in which other header blocks must be processed.

SOAP protocol binding framework

SOAP enables exchange of SOAP messages using a variety of underlying protocols. The formal set of rules for carrying a SOAP message within or on top of another protocol (underlying protocol) for the purpose of exchange is called a binding.

As SOAP 1.2 messages are defined as an XML Infoset Infoset, the responsibility of a binding is to carry the SOAP message using the underlying protocol so that it can be communicated to the receiving node. In other words, an XML 1.0 serialization is not required on the wire, and optimizations can be used (see for an example).

Addressing messages and Web services: Web Services Addressing 1.0

In wanting to stay a very generic message framework, SOAP 1.2 does not describe the message path in its envelope. Web Services Addressing 1.0 (WS-Addressing 1.0 - Core and WS-Addressing 1.0 - SOAP) defines a SOAP module which provides in a SOAP envelope information to address messages and Web services.

WS-Addressing 1.0 defines message addressing properties which are included in a SOAP message to specify, among other things, its destination and the endpoint which will be the recipient of subsequent replies.

WS-Addressing enables asynchronous scenarios such as a request over a particular channel, indicating that the reply should be sent using another channel.

Endpoint references (EPR)

Web Services Addressing 1.0 defines a construct to refer to endpoints for the purpose of addressing them messages. This construct has three properties:

Example of an EPR

Below is a reference to an endpoint whose address is http://example.com/fabrikam/acct; the EPR mentions that the fabrikam:Inventory WSDL WSDL Version 2.0: Core interface is implemented at this endpoint. 

<wsa:EndpointReference
    xmlns:wsa="http://www.w3.org/2005/03/addressing"
    xmlns:fabrikam="http://example.com/fabrikam">
  <wsa:Address>http://example.com/fabrikam/acct</wsa:Address>
  <wsa:Metadata
      xmlns:wsdli="http://www.w3.org/2004/08/wsdl-instance"
      wsdli:wsdlLocation="http://example.com/fabrikam http://example.com/fabrikam.wsdl">
    <wsaw:InterfaceName>fabrikam:Inventory</wsaw:InterfaceName>
  </wsa:Metadata>
</wsa:EndpointReference>

Message addressing properties

Message addressing properties are information included in a message that provide references for the endpoints involved in an interaction.

The reference to endpoints are EPRs as introduced in .

They also provide information to facilitate an interaction, about the semantics of the message, and data for correlation purposes:

Below is an example of use of the message addressing properties in a SOAP 1.2 message:

Example of a SOAP 1.2 message using WS-Addressing 1.0

The SOAP message below is addressed to the endpoint whose address in http://example.com/fabrikam/Purchasing. The semantics of the message is identified by http://example.com/fabrikam/SubmitPO. The message identifier is http://example.com/6B29FC40-CA47-1067-B31D-00DD010662DB, and it's a response to message http://example.com/fabrikam/mid/1234. Replies to this message will be sent to mailto:client1@example.com. 

<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope"      
                xmlns:wsa="http://www.w3.org/2005/03/addressing">
  <S:Header>
    <wsa:MessageID>
      http://example.com/6B29FC40-CA47-1067-B31D-00DD010662DB
    </wsa:MessageID>
    <wsa:ReplyTo>
      <wsa:Address>mailto:client1@example.com</wsa:Address>
    </wsa:ReplyTo>
    <wsa:To>http://example.com/fabrikam/Purchasing</wsa:To>
    <wsa:Action>http://example.com/fabrikam/SubmitPO</wsa:Action>
    <wsa:RelatesTo
         RelationshipType="http://www.w3.org/2005/03/addressing/reply">
      http://example.com/fabrikam/mid/1234
    </wsa:RelatesTo>
  </S:Header>
  <S:Body>
    …
  </S:Body>
</S:Envelope>

Remaining issues regarding asynchronous use cases

Web Services Addressing 1.0 (WS-Addressing 1.0 - Core and WS-Addressing 1.0 - SOAP) was published as a W3C Last Call Working Draft on 31 March 2005, inviting the community to send technical comments on the drafts before the Working Group starts testing the implementability of the specifications.

It is expected that one common use of WS-Addressing 1.0 will be in a request-response interaction, with the request going over an HTTP request and the response going over a different HTTP interaction, or another protocol, as shown in . Work in underway to determine the appropriate SOAP binding to achieve such interactions to use as the SOAP 1.2 HTTP binding defined in SOAP 1.2 Adjuncts appears to warrant the reply to be carried in the HTTP response returned as a result of the HTTP request used to send the first SOAP message.

Carrying binary data along with SOAP messages

SOAP messages are meant to carry data of an arbitrary complexity. In particular, users will want to carry data which will be in non-XML formats, such as images (e.g. PNG) or documents in binary formats (e.g. PDF).

In order to be able to apply SOAP extensions (e.g. as integrity checks) to those items part of the logical message easily, those items need to be part of the SOAP envelope. However, embedding those non-XML formats in an XML documents forces one to include them as Base64-encoded data, whose overhead significantly impacts performance.

MTOM, the SOAP Message Transmission Optimization Mechanism, builds on top of XOP, the XML-binary Optimized Packaging introduced in , to allow optimized transmission of SOAP messages containing Base64-encoded representations of those items.

The Resource Representation SOAP Header Block, described in , allows to use this mechanism to carry representations of Web resources.

XOP, the XML-binary Optimized Packaging

XOP allows the serialization of an XML Infoset Infoset containing Base64-encoded data as a package: the root of the package contains the XML document itself, with selected portions of its content that are Base64-encoded binary data extracted and re-encoded (i.e., the data is decoded from Base64) and placed into the package. The locations of those selected portions are marked in the XML with a special element that links to the packaged data using URIs.

In particular, XOP XOP defines how to use MIME Multipart/Related as the underlying packaging system for a XOP package.

Serialization and deserialization of a XOP package

Note that XOP only targets character information item children of an element information item, and not attribute information items.

XOP packaging using MIME Multipart/Related

The following XML document contains two binary pieces of data, a photo and a signature: 

<m:data xmlns:m='http://example.org/stuff'>
  <m:photo>/aWKKapGGyQ=</m:photo>
  <m:sig>Faa7vROi2VQ=</m:sig>
</m:data>

Using XOP, the document will be packaged as a MIME Multipart/Related package, with both the photo and signature extracted, as follows: 

MIME-Version: 1.0
Content-Type: Multipart/Related;boundary=MIME_boundary;
    type="application/xop+xml";
    start="<mymessage.xml@example.org>";
    start-info="text/xml"
Content-Description: An XML document with my pic and sig in it

--MIME_boundary
Content-Type: application/xop+xml; 
    charset=UTF-8; 
    type="text/xml"
Content-Transfer-Encoding: 8bit
Content-ID: <mymessage.xml@example.org>

<m:data xmlns:m='http://example.org/stuff'>
  <m:photo><xop:Include 
  xmlns:xop='http://www.w3.org/2004/08/xop/include' 
  href='cid:http://example.org/me.jpg'/></m:photo>
  <m:sig><xop:Include 
  xmlns:xop='http://www.w3.org/2004/08/xop/include' 
  href='cid:http://example.org/my.hsh'/></m:sig>
</m:data>

--MIME_boundary
Content-Type: image/jpeg
Content-Transfer-Encoding: binary
Content-ID: <http://example.org/me.jpg>

// binary octets for JPEG image

--MIME_boundary
Content-Type: application/pkcs7-signature
Content-Transfer-Encoding: binary
Content-ID: <http://example.org/my.hsh>

// binary octets for signature

--MIME_boundary--

It is important to note that, in a number of XOP applications, binary data need never be encoded in Base64 form. If the data to be included is already available as a binary octet stream, then either an application or other software acting on its behalf can directly copy that data into a XOP package, at the same time preparing suitable linking elements for use in the root part; when parsing a XOP package, the binary data can be made available directly to applications, or, if appropriate, the Base64 binary character representation can be computed from the binary data.

MTOM, the SOAP Message Transmission Optimization Mechanism

MTOM defines a SOAP feature, i.e. an abstract piece of functionality extending the SOAP messaging framework, that may be implemented by bindings to take advantage of the XOP optimizations for SOAP messages.

The HTTP SOAP Transmission Optimization Feature it defines enhances the SOAP 1.2 HTTP binding defined in SOAP 1.2 Adjuncts by carrying the SOAP message on the wire as a XOP package.

SOAP message sent as a XOP package with MTOM

The following SOAP envelope is similar to the XML document described in : 

<soap:Envelope
    xmlns:soap='http://www.w3.org/2003/05/soap-envelope' 
    xmlns:xmlmime='http://www.w3.org/2004/11/xmlmime'>
  <soap:Body>
    <m:data xmlns:m='http://example.org/stuff'>
      <m:photo>/aWKKapGGyQ=</m:photo>
      <m:sig>Faa7vROi2VQ=</m:sig>
    </m:data>
  </soap:Body>
</soap:Envelope>

When sent with MTOM, the root of the XOP package will be the SOAP message, with the photo and the signature attached in the other parts of the MIME package: 

MIME-Version: 1.0
Content-Type: Multipart/Related;boundary=MIME_boundary;
    type="application/xop+xml";
    start="<mymessage.xml@example.org>";
    startinfo="application/soap+xml; action=\"ProcessData\""
Content-Description: A SOAP message with my pic and sig in it

--MIME_boundary
Content-Type: application/xop+xml; 
    charset=UTF-8; 
    type="application/soap+xml; action=\"ProcessData\""
Content-Transfer-Encoding: 8bit
Content-ID: <mymessage.xml@example.org>

<soap:Envelope
    xmlns:soap='http://www.w3.org/2003/05/soap-envelope'
    xmlns:xmlmime='http://www.w3.org/2004/11/xmlmime'>
  <soap:Body>
    <m:data xmlns:m='http://example.org/stuff'>
      <m:photo><xop:Include 
    xmlns:xop='http://www.w3.org/2004/08/xop/include' 
    href='cid:http://example.org/me.jpeg'/></m:photo>
      <m:sig><xop:Include 
    xmlns:xop='http://www.w3.org/2004/08/xop/include' 
    href='cid:http://example.org/my.hsh'/></m:sig>
    </m:data>
  </soap:Body>
</soap:Envelope>

--MIME_boundary
Content-Type: image/jpeg
Content-Transfer-Encoding: binary
Content-ID: <http://example.org/me.jpg>

// binary octets for JPEG image

--MIME_boundary
Content-Type: application/pkcs7-signature
Content-Transfer-Encoding: binary
Content-ID: <http://example.org/my.hsh>

// binary octets for signature

--MIME_boundary--

The Resource Representation SOAP Header Block

In some cases, an application may want to send a representation of an external resource that is pointed to in a SOAP message along with the SOAP message, e.g. because the receiver has limited ability to get the representation using other means, because of access restrictions or because the overhead would be unacceptable.

The Resource Representation SOAP Header Block allows applications to include such representations as Base64-encoded data, whose transmission can then be optimized by MTOM as described is . Their media type can be specified using the xmlmime:contentType attribute defined in XML-MT.

Representation header block in a SOAP Envelope
<soap:Envelope xmlns:soap='http://www.w3.org/2003/05/soap-envelope' 
               xmlns:rep='http://www.w3.org/2004/08/representation' 
               xmlns:xmlmime='http://www.w3.org/2004/11/xmlmime'>
  <soap:Header>
    <rep:Representation resource='http://example.org/me.jpg'>
      <rep:Data xmlmime:contentType='image/jpeg'>/aWKKapGGyQ=</rep:Data>
    </rep:Representation>
  </soap:Header>
  <soap:Body>
    <x:MyData xmlns:x='http://example.org/mystuff'>
      <x:name>John Q. Public</x:name>
      <x:img src='http://example.org/me.jpg'/>
    </x:MyData>
  </soap:Body>
</soap:Envelope>

The image can be transmitted in an efficient way using MTOM as follows: 

MIME-Version: 1.0
Content-Type: Multipart/Related;boundary=MIME_boundary;
    type="application/xop+xml";
    start="<mymessage.xml@example.org>";
    startinfo="application/soap+xml; action=\"ProcessData\""
Content-Description: A SOAP message with the representation of
    http://example.org/me.jpg in it

--MIME_boundary
Content-Type: application/xop+xml; 
    charset=UTF-8; 
    type="application/soap+xml; action=\"ProcessData\""
Content-Transfer-Encoding: 8bit
Content-ID: <mymessage.xml@example.org>

<soap:Envelope
    xmlns:soap='http://www.w3.org/2003/05/soap-envelope'
    xmlns:xmlmime='http://www.w3.org/2004/11/xmlmime'>
  <soap:Header>
    <rep:Representation resource='http://example.org/me.jpg'>
      <rep:Data xmlmime:contentType='image/jpeg'><xop:Include 
    xmlns:xop='http://www.w3.org/2004/08/xop/include' 
    href='cid:http://example.org/me.jpg'/></rep:Data>
    </rep:Representation>
  </soap:Header>
  <soap:Body>
    <x:MyData xmlns:x='http://example.org/mystuff'>
      <x:name>John Q. Public</x:name>
      <x:img src='http://example.org/me.jpg'/>
    </x:MyData>
  </soap:Body>
</soap:Envelope>

--MIME_boundary
Content-Type: image/jpeg
Content-Transfer-Encoding: binary
Content-ID: <http://example.org/me.jpg>

// binary octets for JPEG image

--MIME_boundary--

Conclusion

SOAP 1.2, WS-Addressing 1.0 and MTOM provide the basis for addressing complex and extensible messages between Web services agents.

SOAP 1.2 (SOAP 1.2 and SOAP 1.2 Adjuncts) and MTOM and its accompanying specifications (XOP, MTOM and RRSHB) have been released as W3C Recommendations.

Web Services Addressing 1.0 (WS-Addressing 1.0 - Core and WS-Addressing 1.0 - SOAP) are expected to be published as W3C Recommendations mid-2005.

Bibliography

References
[XML-MT] Assigning Media Types to Binary Data in XML
World Wide Web Consortium, 2 November 2004
[RRSHB] Resource Representation SOAP Header Block
World Wide Web Consortium, 25 January 2005
[SOAP 1.2] SOAP Version 1.2 Part 1: Messaging Framework
World Wide Web Consortium, 24 June 2003
[SOAP 1.2 Adjuncts] SOAP Version 1.2 Part 2: Adjuncts
World Wide Web Consortium, 24 June 2003
[MTOM] SOAP Message Transmission Optimization Mechanism
World Wide Web Consortium, 25 January 2005
[WS-Addressing 1.0 - Core] Web Services Addressing 1.0 - Core
World Wide Web Consortium, 31 March 2005
[WS-Addressing 1.0 - SOAP] Web Services Addressing 1.0 - SOAP Binding
World Wide Web Consortium, 31 March 2005
[WSDL Version 2.0: Core] Web Services Description Language (WSDL) Version 2.0 Part 1: Core Language
World Wide Web Consortium, 3 August 2004
[Infoset] XML Information Set (Second Edition)
World Wide Web Consortium, 4 February 2004
[XOP] XML-binary Optimized Packaging
World Wide Web Consortium, 25 January 2005

Biography

Hugo Haas

Web Services Activity Lead, World Wide Web Consortium (W3C) (http://www.w3.org/)

Hugo Haas joined W3C in June 1999.

He holds an engineering degree from the "Grande Ecole" Ecole Centrale Paris, and a Diploma in Computer Science from the University of Cambridge where he worked on resource reservation for ATM networks with devolved control (DCAN). Prior to joining the Consortium, Hugo worked as a software engineer for 3Com in England.

Hugo is Web Services Activity Lead, Team contact for the Web Services Addressing Working Group, Web Services Description Working Group, and the Web Services Coordination Group.