Web Services Architecture and Its Specifications [Electronic resources] : Essentials for Understanding WS-* نسخه متنی

SOAP

Every Web services message is a SOAP message represented using the XML Information Set. A fragment of the simplest SOAP message, with no header blocks and only a SOAP Body element containing our sample PurchaseOrder, is shown below.

The business content of the PurchaseOrder has been omitted for brevity. This SOAP message fragment does not yet include enough information for the message to actually be routed and processed. Moreover, the entire topic of message security is deferred until later in this chapter. This example is provided only to illustrate the basics of the SOAP message format, serving as a foundation for each of the later message examples.

SOAP Envelope
(01) <env:Envelope
(02)   xmlns:env="http://www.w3.org/2003/05/soap-envelope">
(03) <env:Header>
(04)   ...
(05) </env:Header>
(06) <env:Body>
(07)  <po:PurchaseOrder>
(08)   ...
(09)  </po:PurchaseOrder>
(10) </env:Body>
(11) </env:Envelope>

Lines 0102 The SOAP Envelope element is the root element for all SOAP messages.

Lines 0305 The SOAP Header element is the first of two possible child elements of Envelope. While it has no content in this example, the Header element is used to encapsulate the information headers defined by the Web services protocols. The Header element is central in providing the ability to compose the various Web services protocols into combined behaviors.

Line 06 The SOAP Body element is the second child element of the SOAP Envelope. It encapsulates the message payloadin this case, the PurchaseOrder. Note that the PurchaseOrder element is defined in its own XML namespace.

SOAP and Attachments

In our example scenario, customized art books are provided in an electronic format. When a book is available, the school is notified and the procurement system requests it from the distribution Web service. We assume that each electronic customized book is transmitted in separate files. Because these files are typically very large, each book is sent as a binary ZIP file attachment to a SOAP message using the MTOM and XOP specifications.

The example shown next is of a MIME-formatted message with both a SOAP payload and a ZIP file attachment:

Attachments using MTOM and XOP
(01) MIME-Version: 1.0
(02) Content-type:Multipart/Related;boundary=MIME_boundary;
(03)   type="application/xop+xml"
(04)   start="<message@ex.mspress.microsoft.com>";
(05)   startinfo="application/soap+xml; action=\"ProcessData\"
(06) Content-description: SOAP response to eBook request
(07) --MIME_boundary
(08) Content-type:application/xop+xml;
(09)   charset="UTF-8";
(10)   type="application/soap+xml; action=\"ProcessData\"
(11) Content-Transfer-Encoding: 8bit
(12) Content-ID: <message@ex.mspress.microsoft.com>
(13) <env:Envelope
(14)   xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
(15)   xmlns:xmlmime="http://www.w3.org/2004/06/xmlmime"
(16)   xmlns:xop="http://www.w3.org/2004/08/xop/include">
(17) <env:Header>
(18)  <wsa:To>http://fineartschool.net/orders</wsa:To>
(19) </env:Header>
(20) <env:Body>
(21)  <b:EBookResponse xmlns:b="ex.mspress.microsoft.com/ebook">
(22)  <b:content xmlmime:contentType="application/octet-stream">
(23)   <xop:Include
(24)     href="cid:ex.mspress.microsoft.com/ebook.zip"/>
(25)  </b:content>
(26)  </b:EBookResponse>
(27) </env:Body>
(28) </env:Envelope>
(29) --MIME_boundary
(30) Content-Type: application/octet-stream
(31) Content-Transfer-Encoding: binary
(32) Content-ID: <ex.mspress.microsoft.com/ebook.zip>
(33) // binary octets for zip file
(34) --MIME_boundary--

Lines 0106 SOAP messages with attachments using XOP and MTOM are encoded using Multipart MIME. These lines are the MIME protocol headers in the message.

Line 02 This line tells the message processor what types of content are included in the message and what unique text string (in this case, MIME_boundary) is used to identify the boundaries between message parts.

Line 07 This is the boundary between the MIME message headers and the headers for the first MIME part, the SOAP message.

Lines 0812 The MIME headers for the SOAP message explicitly indicate to the message processor that this part is formatted according to the MTOM/XOP specification.

Lines 1516 The namespaces for MIME and XOP information in the SOAP header blocks are included here.

Lines 1719 The destination address of the message is carried in the SOAP Header. Message addressing is discussed later in this chapter.

Lines 2325 The principles of the XML Information Set are used to logically incorporate the binary attachment at this location in the SOAP message. The xop:Include element references the binary attachment and indicates that it should be logically carried at this location in the SOAP message payload.

Lines 2934 The binary payload of the message is attached as the last MIME part. The value of its Content-ID must match the identifier referenced on Line 21.

SOAP and mustUnderstand

The SOAP mustUnderstand attribute is an instruction that the message processor must fail (or reject the message) if the elements marked as such are not understood. For our EBookResponse message, the recipient endpoint must know how to properly process the attachments for the solution to work. Some SOAP processors might not understand MTOM/XOP. If this is the case, processing must fail and no action can be taken on any part of the message.

This message fragment shows how the SOAP mustUnderstand attribute can be added to the xop:Include element:

The mustUnderstand Attribute
(01) <soap:Body env:mustUnderstand="1">
(02)  <b:EBookResponse>
(03)  <b:content xmlmime:contentType="application/octet-stream">
(04)  <xop:Include
(05)    href="cid:ex.mspress.microsoft.com/ebook.zip"/>
(06)  </b:content>
(07)  </b:EBookResponse>
(08) </soap:Body>

Line 01 The soap:mustUnderstand attribute is added to the message. When the value of this attribute is set to 1, the SOAP processor must understand how to process the element or processing must fail.