12 Optimizing Binary Data Transmission Using MTOM/XOP

Annotating the Data Types

Depending on your programming model, you can annotate your Java class or WSDL to define the MIME content types that are used for sending binary data. This step is optional.

The following table defines the mapping of MIME content types to Java types. In some cases, a default MIME type-to-Java type mapping exists. If no default exists, the MIME content types are mapped to DataHandler.

image/gif

java.awt.Image

image/jpeg

java.awt.Image

text/plain

java.lang.String

text/xml or application/xml

javax.xml.transform.Source

*/*

javax.activation.DataHandler

The following sections describe how to annotate the data types based on whether you are starting from Java or WSDL.

• Annotating the Data Types: Start From Java

• Annotating the Data Types: Start From WSDL

@WebMethod
@Oneway
public void dataUpload(
    @XmlMimeType("application/octet-stream") DataHandler data) 
{
}

<element name="image" type="base64Binary"
xmime:expectedContentTypes="image/gif"
xmlns:xmime="http://www.w3.org/2005/05/xmlmime"/>

Enabling MTOM on the Web Service

You can enable MTOM on the Web service using an annotation or WS-Policy file, as described in the following sections:

• Enabling MTOM on the Web Service Using Annotation

• Enabling MTOM on the Web Services Using WS-Policy File

package examples.webservices.mtom;

import javax.jws.WebMethod;
import javax.jws.WebService;
import javax.xml.ws.soap.MTOM; 

@MTOM
@WebService(name="MtomPortType",
            serviceName="MtomService",
            targetNamespace="http://example.org")
public class MTOMImpl { 
  @WebMethod
  public String echoBinaryAsString(byte[] bytes) {
    return new String(bytes);

  }
}

<wsp:Policy wsu:Id="myService_policy">
     <wsp:ExactlyOne>
         <wsp:All>
             <wsoma:OptimizedMimeSerialization 
                    xmlns:wsoma="http://schemas.xmlsoap.org/ws/2004/09/policy/optimizedmimeserialization" /> 
         </wsp:All>
     </wsp:ExactlyOne>
 </wsp:Policy>

<wsdl:binding name="BasicHttpBinding_IMtomTest" 
                       type="i0:IMtomTest">
     <wsp:PolicyReference URI="#myService_policy" /> 
     <soap:binding transport="http://schemas.xmlsoap.org/soap/http" />

package examples.webservices.mtom;
import javax.jws.WebMethod;
import javax.jws.WebService;
 import weblogic.jws.Policy;
@WebService(name="MtomPortType",
             serviceName="MtomService",
             targetNamespace="http://example.org")
@Policy(uri="policy:Mtom.xml", attachToWsdl=true)
public class MtomImpl {
  @WebMethod
   public String echoBinaryAsString(byte[] bytes) {
     return new String(bytes);
   }
 

Enabling MTOM on the Client

To enable MTOM on the client of the Web service, pass an instance of the javax.xml.ws.soap.MTOMFeature as a parameter when creating the Web service proxy or dispatch, as illustrated in the following example. Relevant code is shown in bold.

package examples.webservices.mtom.client;

import javax.xml.ws.soap.MTOMFeature;

public class Main {
  public static void main(String[] args) {
    String FOO = "FOO";
    MtomService service = new MtomService()
    MtomPortType port = service.getMtomPortTypePort(new MTOMFeature()); 
    String result = null;
    result = port.echoBinaryAsString(FOO.getBytes());
    System.out.println( "Got result: " + result );
  }
}

Setting the Attachment Threshold

You can set the attachment threshold to specify when the xs:binary64 data is sent inline or as an attachment. By default, the attachment threshold is 0 bytes. All xs:binary64 data is sent as an attachment.

To set the attachment threshold:

• On the Web service, pass the threshold attribute to the @java.xml.ws.soap.MTOM annotation. For example:

  @MTOM(threshold=3072)
  

• On the client of the Web service, pass the threshold value to javax.xml.ws.soap.MTOMFeature. For example:

  MtomPortType port = service.getMtomPortTypePort(new MTOMFeature(3072));
  

In each of the examples above, if a message is greater than or equal to 3 KB, it will be sent as an attachment. Otherwise, the content will be sent inline, as part of the SOAP message body.

Client Side Example

The following provides an example that employs streaming SOAP attachments on the client side.

package examples.webservices.mtomstreaming.client;

import java.util.Map;
import java.io.InputStream;
import javax.xml.ws.soap.MTOMFeature;
import javax.activation.DataHandler;
import javax.xml.ws.BindingProvider;
import com.sun.xml.ws.developer.JAXWSProperties;
import com.sun.xml.ws.developer.StreamingDataHandler;

public class Main {
   public static void main(String[] args) {
      MtomStreamingService service = new MtomStreamingService();
      MTOMFeature feature = new MTOMFeature();
      MtomStreamingPortType port = service.getMtomStreamingPortTypePort(
         feature);
      Map<String, Object> ctxt=((BindingProvider)port).getRequestContext();
      ctxt.put(JAXWSProperties.HTTP_CLIENT_STREAMING_CHUNK_SIZE, 8192);
      DataHandler dh = new DataHandler(new
                  FileDataSource("/tmp/example.jar"));
      port.fileUpload("/tmp/tmp.jar",dh);

      DataHandler dhn = port.fileDownload("/tmp/tmp.jar");
      StreamingDataHandler sdh = {StreamingDataHandler)dh;
      try{
         File file = new File("/tmp/tmp.jar");
         sdh.moveTo(file);    
         sdh.close();
       }
       catch(Exception e){
          e.printStackTrace();
       }
  }
}

The preceding example demonstrates the following:

• To enable MTOM on the client of the Web service, pass an instance of the javax.xml.ws.soap.MTOMFeature as a parameter when creating the Web service proxy or dispatch.

• Configure HTTP streaming support by enabling HTTP chunking on the MTOM streaming client.

  Map<String, Object> ctxt = ((BindingProvider)port).getRequestContext();
     ctxt.put(JAXWSProperties.HTTP_CLIENT_STREAMING_CHUNK_SIZE, 8192);
  

• Call the port.fileUpload method.

• Cast the DataHandler to StreamingDataHandler and use the StreamingDataHandler.readOnce() method to read the attachment.

Server Side Example

The following provides an example that employs streaming SOAP attachments on the server side.

package examples.webservices.mtomstreaming;

import java.io.File;
import java.jws.Oneway;
import javax.jws.WebMethod;
import java.io.InputStream;
import javax.jws.WebService;
import javax.xml.bind.annotation.XmlMimeType;
import javax.xml.ws.WebServiceException;
import javax.xml.ws.soap.MTOM;
import javax.activation.DataHandler;
import javax.activation.FileDataSource;
import com.sun.xml.ws.developer.StreamingAttachment;
import com.sun.xml.ws.developer.StreamingDataHandler;

@StreamingAttachment(parseEagerly=true, memoryThreshold=40000L)
@MTOM
@WebService(name="MtomStreaming", 
            serviceName="MtomStreamingService",
            targetNamespace="http://example.org",
            wsdlLocation="StreamingImplService.wsdl")
@Oneway
@WebMethod
public class StreamingImpl {

   // Use @XmlMimeType to map to DataHandler on the client side
   public void fileUpload(String fileName,
                          @XmlMimeType("application/octet-stream") 
                          DataHandler data) {
      try {
            StreamingDataHandler dh = (StreamingDataHandler) data;
            File file = new File(fileName);
            dh.moveTo(file);
            dh.close();
      } catch (Exception e) {
            throw new WebServiceException(e);
   }

  @XmlMimeType("application/octet-stream")
  @WebMethod
  public DataHandler fileDownload(String filename)
  {
    return  new DataHandler(new FileDataSource(filename));
  }
}

The preceding example demonstrates the following:

• The @StreamingAttachement annotation is used to configure the streaming SOAP attachment. For more information, see "Configuring Streaming SOAP Attachments".

• The @XmlMimeType annotation is used to map the DataHandler, as follows:

  • If starting from WSDL, it is used to map the xmime:expectedContentTypes="application/octet-stream" to DataHandler in the generated SEI.

  • If starting from Java, it is used to generate an appropriate schema type in the generated WSDL.

• Cast the DataHandler to StreamingDataHandler and use the StreamingDataHandler.moveTo(File) method to store the contents of the attachment to a file.

Configuring Streaming SOAP Attachments

You can configure streaming SOAP attachments on the client and server sides to specify the following:

• Directory in which large attachments are stored.

• Whether to parse eagerly the streaming attachments.

• Maximum attachment size (bytes) that can be stored in memory. Attachments that exceed the specified number of bytes are written to a file.

... 
import com.sun.xml.ws.developer.StreamingAttachment; 
import javax.jws.WebService;

@StreamingAttachment(parseEagerly=true, memoryThreshold=4000000L) 
@WebService(name="HelloWorldPortType", serviceName="HelloWorldService")
public class StreamingImpl {
}

... 
import com.sun.xml.ws.developer.StreamingAttachmentFeature; 
...
MTOMFeature mtom = new MTOMFeature();
StreamingAttachmentFeature stf = new StreamingAttachmentFeature("/tmp", true, 4000000L); 
MtomStreamingService service = new MtomStreamingService();
MtomStreamingPortType port = service.getMtomStreamingPortTypePort(
         mtom, stf); 
...