Chapter 4. Sending Binary Data Using SOAP with Attachments

Attribute	Description
`part`	Specifies the name of the WSDL message `part`, from the parent message definition, that is used as the content of this part of the MIME multipart message being placed on the wire.
`type`	The MIME type of the data in this message part. MIME types are defined as a type and a subtype using the syntax `type``/``subtype`. There are a number of predefined MIME types such as `image/jpeg` and `text/plain`. The MIME types are maintained by the Internet Assigned Numbers Authority (IANA) and described in detail in Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies and Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types.

SOAP attachments provide a mechanism for sending binary data as part of a SOAP message. Using SOAP with attachments requires that you define your SOAP messages as MIME multipart messages.

Overview

SOAP messages generally do not carry binary data. However, the W3C SOAP 1.1 specification allows for using MIME multipart/related messages to send binary data in SOAP messages. This technique is called using SOAP with attachments. SOAP attachments are defined in the W3C's SOAP Messages with Attachments Note.

Namespace

The WSDL extensions used to define the MIME multipart/related messages are defined in the namespace http://schemas.xmlsoap.org/wsdl/mime/.

In the discussion that follows, it is assumed that this namespace is prefixed with mime. The entry in the WSDL definitions element to set this up is shown in Example 4.1.

Example 4.1. MIME Namespace Specification in a Contract

xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/"

In a default SOAP binding, the first child element of the input, output, and fault elements is a soap:body element describing the body of the SOAP message representing the data. When using SOAP with attachments, the soap:body element is replaced with a mime:multipartRelated element.

	Note
	WSDL does not support using `mime:multipartRelated` for `fault` messages.

The mime:multipartRelated element tells FUSE Services Framework that the message body is a multipart message that potentially contains binary data. The contents of the element define the parts of the message and their contents. mime:multipartRelated elements contain one or more mime:part elements that describe the individual parts of the message.

The first mime:part element must contain the soap:body element that would normally appear in a default SOAP binding. The remaining mime:part elements define the attachments that are being sent in the message.

Describing a MIME multipart message

MIME multipart messages are described using a mime:multipartRelated element that contains a number of mime:part elements. To fully describe a MIME multipart message you must do the following:

Inside the input or output message you are sending as a MIME multipart message, add a mime:mulipartRelated element as the first child element of the enclosing message.

Add a mime:part child element to the mime:multipartRelated element and set its name attribute to a unique string.

Add a soap:body element as the child of the mime:part element and set its attributes appropriately.

	Tip
	If the contract had a default SOAP binding, you can copy the `soap:body` element from the corresponding message from the default binding into the MIME multipart message.

Add another mime:part child element to the mime:multipartReleated element and set its name attribute to a unique string.

Add a mime:content child element to the mime:part element to describe the contents of this part of the message.

To fully describe the contents of a MIME message part the mime:content element has the following attributes:

Table 4.1. mime:content Attributes

Attribute Description

part Specifies the name of the WSDL message part, from the parent message definition, that is used as the content of this part of the MIME multipart message being placed on the wire.

type

The MIME type of the data in this message part. MIME types are defined as a type and a subtype using the syntax type/subtype.

There are a number of predefined MIME types such as image/jpeg and text/plain. The MIME types are maintained by the Internet Assigned Numbers Authority (IANA) and described in detail in Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies and Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types.

For each additional MIME part, repeat steps Step 4 and Step 5.

Example

Example 4.2 shows a WSDL fragment defining a service that stores X-rays in JPEG format. The image data, xRay, is stored as an xsd:base64binary and is packed into the MIME multipart message's second part, imageData. The remaining two parts of the input message, patientName and patientNumber, are sent in the first part of the MIME multipart image as part of the SOAP body.

Example 4.2. Contract using SOAP with Attachments

<?xml version="1.0" encoding="UTF-8"?>
<definitions name="XrayStorage"
    targetNamespace="http://mediStor.org/x-rays"
    xmlns="http://schemas.xmlsoap.org/wsdl/"
    xmlns:tns="http://mediStor.org/x-rays"
    xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/"
    xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema">

  <message name="storRequest">
    <part name="patientName" type="xsd:string"/>
    <part name="patientNumber" type="xsd:int"/>
    <part name="xRay" type="xsd:base64Binary"/>
  </message>
  <message name="storResponse">
    <part name="success" type="xsd:boolean"/>
  </message>

  <portType name="xRayStorage">
    <operation name="store">
      <input message="tns:storRequest" name="storRequest"/>
      <output message="tns:storResponse" name="storResponse"/>
    </operation>
  </portType>

  <binding name="xRayStorageBinding" type="tns:xRayStorage">
    <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
      <operation name="store">
      <soap:operation soapAction="" style="document"/>
      <input name="storRequest">
        <mime:multipartRelated>
          <mime:part name="bodyPart">
            <soap:body use="literal"/>
          </mime:part>
          <mime:part name="imageData">
            <mime:content part="xRay" type="image/jpeg"/>
          </mime:part>
        </mime:multipartRelated>
      </input>
      <output name="storResponse">
        <soap:body use="literal"/>
      </output>
    </operation>
  </binding>

  <service name="xRayStorageService">
    <port binding="tns:xRayStorageBinding" name="xRayStoragePort">
      <soap:address location="http://localhost:9000"/>
    </port>
  </service>
</definitions>