9.2. Annotating Data Types to use MTOM
Overview
In WSDL, when defining a data type for passing along a block of binary data, such as an image file or a sound file, you define the element for the data to be of type xsd:base64Binary. By default, any element of type xsd:base64Binary results in the generation of a byte[] which can be serialized using MTOM. However, the default behavior of the code generators does not take full advantage of the serialization.
In order to fully take advantage of MTOM you must add annotations to either your service's WSDL document or the JAXB class that implements the binary data structure. Adding the annotations to the WSDL document forces the code generators to generate streaming data handlers for the binary data. Annotating the JAXB class involves specifying the proper content types and might also involve changing the type specification of the field containing the binary data.
WSDL first
Example 9.1, “Message for MTOM” shows a WSDL document for a Web service that uses a message which contains one string field, one integer field, and a binary field. The binary field is intended to carry a large image file, so it is not appropriate to send it as part of a normal SOAP message.
Example 9.1. Message for MTOM
<?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:soap12="http://schemas.xmlsoap.org/wsdl/soap12/"
xmlns:xsd1="http://mediStor.org/types/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<types>
<schema targetNamespace="http://mediStor.org/types/"
xmlns="http://www.w3.org/2001/XMLSchema">
<complexType name="xRayType">
<sequence>
<element name="patientName" type="xsd:string" />
<element name="patientNumber" type="xsd:int" />
<element name="imageData" type="xsd:base64Binary" />
</sequence>
</complexType>
<element name="xRay" type="xsd1:xRayType" />
</schema>
</types>
<message name="storRequest">
<part name="record" element="xsd1:xRay"/>
</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="xRayStorageSOAPBinding" type="tns:xRayStorage">
<soap12:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
<operation name="store">
<soap12:operation soapAction="" style="document"/>
<input name="storRequest">
<soap12:body use="literal"/>
</input>
<output name="storResponse">
<soap12:body use="literal"/>
</output>
</operation>
</binding>
...
</definitions>
If you want to use MTOM to send the binary part of the message as an optimized attachment you must add the
xmime:expectedContentTypes attribute to the element containing the binary data. This attribute is defined in the http://www.w3.org/2005/05/xmlmime namespace and specifies the MIME types that the element is expected to contain. You can specify a comma separated list of MIME types. The setting of this attribute changes how the code generators create the JAXB class for the data. For most MIME types, the code generator creates a DataHandler. Some MIME types, such as those for images, have defined mappings.
Note
The MIME types are maintained by the Internet Assigned Numbers Authority(IANA) and are 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.
Tip
For most uses you specify
application/octet-stream.
Example 9.2, “Binary Data for MTOM” shows how you can modify xRayType from Example 9.1, “Message for MTOM” for using MTOM.
Example 9.2. Binary Data for MTOM
...
<types>
<schema targetNamespace="http://mediStor.org/types/"
xmlns="http://www.w3.org/2001/XMLSchema"
xmlns:xmime="http://www.w3.org/2005/05/xmlmime">
<complexType name="xRayType">
<sequence>
<element name="patientName" type="xsd:string" />
<element name="patientNumber" type="xsd:int" />
<element name="imageData" type="xsd:base64Binary"
xmime:expectedContentTypes="application/octet-stream"/>
</sequence>
</complexType>
<element name="xRay" type="xsd1:xRayType" />
</schema>
</types>
...
The generated JAXB class generated for xRayType no longer contains a byte[]. Instead the code generator sees the
xmime:expectedContentTypes attribute and generates a DataHandler for the imageData field.
Note
You do not need to change the
binding element to use MTOM. The runtime makes the appropriate changes when the data is sent.
Java first
If you are doing Java first development you can make your JAXB class MTOM ready by doing the following:
- Make sure the field holding the binary data is a
DataHandler. - Add the
@XmlMimeType()annotation to the field containing the data you want to stream as an MTOM attachment.
Example 9.3, “JAXB Class for MTOM” shows a JAXB class annotated for using MTOM.
Example 9.3. JAXB Class for MTOM
@XmlType
public class XRayType {
protected String patientName;
protected int patientNumber;
@XmlMimeType("application/octet-stream")
protected DataHandler imageData;
...
}