Enabling MTOM for JAX-WS web services
With Java™ API for XML-Based Web Services (JAX-WS), you can send binary attachments such as images or files along with web services requests. JAX-WS adds support for optimized transmission of binary data as specified by the SOAP Message Transmission Optimization Mechanism (MTOM) specification.
About this task
JAX-WS supports the use of SOAP Message Transmission Optimized Mechanism (MTOM) for sending binary attachment data. By enabling MTOM, you can send and receive binary data optimally without incurring the cost of data encoding needed to embed the binary data in an XML document.
The application server supports sending attachments using MTOM only for JAX-WS applications. This product also provides the ability to provide attachments with Web Services Security SOAP messages by using the new MTOM and XOP standards.
JAX-WS applications can send binary data as base64 or hexBinary encoded data contained within the XML document. However, to take advantage of the optimizations provided by MTOM, enable MTOM to send binary base64 data as attachments contained outside the XML document. MTOM optimization is not enabled by default. JAX-WS applications require separate configuration of both the client and the server artifacts to enable MTOM support.
Procedure
Results
You have developed a JAX-WS web services server and client application that optimally sends and receives binary data using MTOM.
Example
The following example illustrates enabling MTOM support on both the web services client and server endpoint when starting with an WSDL file.
- Locate the WSDL file containing an
xsd:base64Binary
element. The following example is a portion of a WSDL file that contains anxsd:base64Binary
element.<types> ........ <xs:complexType name="ImageDepot"> <xs:sequence> <xs:element name="imageData" type="xs:base64Binary" xmime:expectedContentTypes="image/jpeg"/> </xs:sequence> </xs:complexType> ........ </types>
- Run the wsimport command from the app_server_root\bin\
directory against the WSDL file to generate a set of JAX-WS portable
artifacts.
app_server_root\bin\wsimport.bat <wsdl_url>
app_server_root/bin/wsimport.sh <wsdl_url>
Depending on theexpectedContentTypes
value contained in the WSDL file, the JAXB artifacts generated are in the Java type as described in the following table:Table 1. Mapping of MIME type and Java type. Describes the mapping between MIME types and Java types. MIME Type Java Type image/gif java.awt.Image image/jpeg java.awt.Image text/plain java.lang.String text/xml javax.xml.transform.Source application/xml javax.xml.transform.Source */* javax.activation.DataHandler - Use the JAXB artifacts in the same manner as in any other JAX-WS application. Use these beans to send binary data from both the Dispatch and the Dynamic Proxy client APIs.
- Enable MTOM on a Dispatch client.
//Create the Dispatch instance. JAXBContext jbc = JAXBContext.newInstance("org.apache.axis2.jaxws.sample.mtom"); Dispatch<Object> dispatch = svc.createDispatch(portName, jbc, Service.Mode.PAYLOAD); //Enable MTOM. SOAPBinding binding = (SOAPBinding) dispatch.getBinding(); binding.setMTOMEnabled(true);
- Enable MTOM on a Dynamic Proxy
client.
Now that you have enabled the JAX-WS client for MTOM, messages sent to the server have MTOM enabled. However, for the server to respond back to the client using MTOM, you must enable MTOM on the endpoint.//Create the Dynamic Proxy instance. Service svc = Service.create(serviceName); MtomSample proxy = svc.getPort(portName, MtomSample.class); //Enable MTOM. BindingProvider bp = (BindingProvider) proxy; SOAPBinding binding = (SOAPBinding) bp.getBinding(); binding.setMTOMEnabled(true);
- Enable MTOM on the endpoint implementation class.
The@MTOM(enabled, threshold=4096) @WebService (endpointInterface="org.apache.axis2.jaxws.sample.mtom.MtomSample") public class MtomSampleService implements MtomSample { .... }
jaxax.xml.ws.SOAPBinding
class has a static member for each of the supported binding types. Include either theSOAP11HTTP_MTOM_BINDING
or theSOAP12HTTP_MTOM_BINDING
as the value for the@BindingType
annotation. This value enables all server responses to have MTOM enabled.
When you enable MTOM on the server and the client, the binary data that represents the attachment is included as a Multipurpose Internet Mail Extensions (MIME) attachment to the SOAP message. Without MTOM, the same data is encoded in the format that describes the XML schema, either base64 or hexadecimal encoding, and included inline in the XML document.
type
and content-type
attributes both have the value,
application/xop+xml
, which indicates that the message was successfully optimized
using XML-binary Optimized packaging (XOP) when MTOM was enabled. This example demonstrates how the
optimized message looks on the wire with MTOM enabled.
... other transport headers ...
Content-Type: multipart/related; boundary=MIMEBoundaryurn_uuid_0FE43E4D025F0BF3DC11582467646812;
type="application/xop+xml"; start="
<0.urn:uuid:0FE43E4D025F0BF3DC11582467646813@apache.org>"; start-info="text/xml"; charset=UTF-8
--MIMEBoundaryurn_uuid_0FE43E4D025F0BF3DC11582467646812
content-type: application/xop+xml; charset=UTF-8; type="text/xml";
content-transfer-encoding: binary
content-id:
<0.urn:uuid:0FE43E4D025F0BF3DC11582467646813@apache.org>
<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Header/>
<soapenv:Body>
<sendImage xmlns="http://org/apache/axis2/jaxws/sample/mtom">
<input>
<imageData>
<xop:Include xmlns:xop="https://www.w3.org/2004/08/xop/include"
href="cid:1.urn:uuid:0FE43E4D025F0BF3DC11582467646811@apache.org"/>
</imageData>
</input>
</sendImage>
</soapenv:Body>
</soapenv:Envelope>
--MIMEBoundaryurn_uuid_0FE43E4D025F0BF3DC11582467646812
content-type: text/plain
content-transfer-encoding: binary
content-id:
<1.urn:uuid:0FE43E4D025F0BF3DC11582467646811@apache.org>
… binary data goes here …
--MIMEBoundaryurn_uuid_0FE43E4D025F0BF3DC11582467646812--
... other transport headers ...
Content-Type: text/xml; charset=UTF-8
<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Header/>
<soapenv:Body>
<sendImage xmlns="http://org/apache/axis2/jaxws/sample/mtom">
<input>
<imageData>R0lGADl ... more base64 encoded data ... KTJk8giAAA7</imageData>
</input>
</sendImage>
</soapenv:Body>
</soapenv:Envelope>
For additional information, refer to the Samples documentation, which includes a sample that demonstrates the use of MTOM with JAX-WS web services.