+

Search Tips   |   Advanced Search

Enable MTOM for JAX-WS Web services


With JAX-WS, we 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.

JAX-WS supports the use of SOAP Message Transmission Optimized Mechanism (MTOM) for sending binary attachment data. By enabling MTOM, we 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 appserver supports sending attachments using MTOM only for JAX-WS applications. This product also provides the ability to provide attachments with WS-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. For the server, we can enable MTOM on a Java Beansendpoint only and not on endpoints that implement the javax.xml.ws.Provider interface.

 

  1. Develop Java artifacts for the JAX-WS application that includes an XML schema or WSDL file that represents the Web services application data that includes a binary attachment.

    1. If starting with a WSDL file, develop Java artifacts from a WSDL file by using the wsimport command to generate the required JAX-WS portable artifacts.

    2. If starting with Java Beans components, develop Java artifacts for JAX-WS applications and optionally generate a WSDL file using the wsgen command.

      The XML schema or WSDL file includes a xsd:base64Binary or xsd:hexBinary element definition for the binary data.

    3. We can also include the xmime:expectedContentTypes attribute on the element to affect the mapping by JAXB.

  2. Enable MTOM on a Java Beans endpoint.

    To enable MTOM on an endpoint, use the @MTOM (javax.xml.ws.soap.MTOM) annotation on the endpoint. The @MTOM annotation has two parameters, enabled and threshold. The enabled parameter has a boolean value and indicates if MTOM is enabled for the JAX-WS endpoint. The threshold parameter has an integer value, and it specifies the minimum size for messages that are sent using MTOM. When the message size is less than this specified integer, the message is inlined in the XML document as base64 or hexBinary data.

    Additionally, we can use the @BindingType (javax.xml.ws.BindingType) annotation on a server endpoint implementation class to specify that the endpoint supports one of the MTOM binding types so that the response messages are MTOM-enabled. The javax.xml.ws.SOAPBinding class defines two different constants, SOAP11HTTP_MTOM_BINDING and SOAP12HTTP_MTOM_BINDING that we can use for the value of the @BindingType annotation. .

    For example:

    // for SOAP version 1.1
    @BindingType(value = SOAPBinding.SOAP11HTTP_MTOM_BINDING)
    
    // for SOAP version 1.2
    @BindingType(value = SOAPBinding.SOAP12HTTP_MTOM_BINDING)
    
    

    The presence and value of an @MTOM annotation overrides the value of the @BindingType annotation. For example, if the @BindingType indicates MTOM is enabled, but an @MTOM annotation is present with an enabled value of false, then MTOM is not enabled

  3. Enable MTOM on the client using either the javax.xml.ws.soap.SOAPBinding or the javax.xml.ws.soap.MTOMFeature APIs. Enabling MTOM on the client optimizes the binary messages that are sent to the server.

    1. Enable MTOM on a Dispatch client.

      The following example uses SOAP version 1.1:

      - First method:  Using SOAPBinding.setMTOMEnabled()
      
          SOAPBinding binding = (SOAPBinding)dispatch.getBinding();
          binding.setMTOMEnabled(true);
      
      - Second method: Using Service.addPort where you specify: 
      
          Service svc = Service.create(serviceName);
          svc.addPort(portName,SOAPBinding.SOAP11HTTP_MTOM_BINDING,endpointUrl); 
      
      - Third method: Using MTOMFeature: 
      
          MTOMFeature mtom = new MTOMFeature();
          Service svc = Service.create(serviceName);
          svc.addPort(portName, SOAPBinding.SOAP11_HTTP_BINDING, endpointUrl);
          Dispatch<Source> dsp = svc.createDispatch(portName, Source.class, Service.Mode.PAYLOAD, mtom);
      
      
      

    2. Enable MTOM on a Dynamic Proxy client.

      // Create a BindingProvider bp from a proxy port.
        Service svc = Service.create(serviceName);
        MtomSample proxy = svc.getPort(portName, MtomSample.class);
        BindingProvider bp = (BindingProvider) proxy;
        
        
      //Enable MTOM using the SOAPBinding
        MtomSample proxy = svc.getPort(portName, MtomSample.class);
        BindingProvider bp = (BindingProvider) proxy;
        SOAPBinding binding = (SOAPBinding) bp.getBinding();
        binding.setMTOMEnabled(true);
      
        
      //Or, enable MTOM with the MTOMFeature
        MTOMFeature mtom = new MTOMFeature();
        MtomSample proxy = svc.getPort(portName, MtomSample.class, mtom);
      

 

Results

we 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.

  1. Locate the WSDL file containing an xsd:base64Binary element.

    The following example is a portion of a WSDL file that contains an xsd: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>
    
    

  2. Run the wsimport command from the APP_ROOT\bin\ directory against the WSDL file to generate a set of JAX-WS portable artifacts.

    (Windows)

    APP_ROOT\bin\wsimport.bat <wsdl_url>
    

    [Linux] [AIX] [HP-UX] [Solaris]

    APP_ROOT/bin/wsimport.sh <wsdl_url>

    Depending on the expectedContentTypes 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

    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

  3. 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.

  4. 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);
    

  5. Enable MTOM on a Dynamic Proxy client.

    //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);
    
    Now that we 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, enable MTOM on the Java Beans endpoint.

  6. Enable MTOM on Java Beans endpoint.

    WebService (endpointInterface="org.apache.axis2.jaxws.sample.mtom.MtomSample")
    
    
    

    @BindingType (SOAPBinding.SOAP11HTTP_MTOM_BINDING) public class MtomSampleService implements MtomSample { .... }

    The jaxax.xml.ws.SOAPBinding class has a static member for each of the supported binding types. Include either the SOAP11HTTP_MTOM_BINDING or the SOAP12HTTP_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 hex, and included in the XML document. This example illustrates an MTOM enabled SOAP version 1.1 message with an attachment data. The 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="http://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--

In contrast, this example demonstrates a SOAP version 1.1 message on the wire without MTOM enabled. The attachment is included in the body of the SOAP message, and the SOAP message is not optimized.

… 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 Gallery which includes a Sample that demonstrates the use of MTOM with JAX-WS Web services.


XML-binary Optimized Packaging
XML information set
Message Transmission Optimization Mechanism
What is new for securing Web services

 

Related tasks


Implement Web services applications with JAX-WS
Implement Web services applications from existing WSDL files with JAX-WS
Signing and encrypting message parts using policy sets
Secure Web services applications using the WSS APIs at the message level
Encrypting the SOAP message using the WSSEncryption API
Example: Installing a Web Services Sample with the console

 

Related


JAX-WS annotations

 

Related information


Web services specifications and APIs
Java API for XML Web Services (JAX-WS) API documentation