Chapter 8. Sending Binary Data Using SOAP with Attachments
Abstract
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 8.1, “MIME Namespace Specification in a Contract”.
Example 8.1. MIME Namespace Specification in a Contract
xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/"
Changing the message binding
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 Apache CXF 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
inputoroutputmessage you are sending as a MIME multipart message, add amime:mulipartRelatedelement as the first child element of the enclosing message. - Add a
mime:partchild element to themime:multipartRelatedelement and set itsnameattribute to a unique string. - Add a
soap:bodyelement as the child of themime:partelement and set its attributes appropriately.NoteIf the contract had a default SOAP binding, you can copy thesoap:bodyelement from the corresponding message from the default binding into the MIME multipart message. - Add another
mime:partchild element to themime:multipartReleatedelement and set itsnameattribute to a unique string. - Add a
mime:contentchild element to themime:partelement to describe the contents of this part of the message.To fully describe the contents of a MIME message part themime:contentelement has the following attributes:Table 8.1. mime:content Attributes Attribute Description partSpecifies 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.typeThe 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 asimage/jpegandtext/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.
Example
Example 8.2, “Contract using SOAP with Attachments” 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 8.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>