Start of Content Area

Background documentation SOAP Message Transmission Optimization Mechanism (MTOM)  Locate the document in its SAP Library structure

General

One advantage of modeling the payload of a message with XML schema is that the message contents can be converted later into a structured and comprehensible format. The payload format is string-based: Depending on the code page used, only a limited number of characters can be distinguished.

The format of binary data (pictures, audio files, signatures, and so on) is more compact that the string-based format of the payload; however, because the value range of the binary-data format is larger it cannot be displayed with string-based code pages.

Consequently, there are two ways of sending binary data with a message:

      The binary data is sent in compact binary-data format as an MIME message attachment. The advantage here is that the data is displayed compactly. The disadvantage is that you cannot clearly see from the payload that the message has an attachment.

      When the payload is created at the sender, the binary data is converted to a string-based format and is sent as the content of an element in the payload. The advantage here is that the data is clearly modeled in the payload. The disadvantage is that a lot of system resources are required to display this data even though this is not usually necessary during the transfer or during a mapping.

SOAP Message Transmission Optimization Mechanism (MTOM) optimizes system performance when transferring binary data by using the SOAP protocol; MTOM combines the advantages of both approaches. Instead of including the binary data in the payload, the <xop:include>statement in the payload uses a GUID to reference the MIME attachment that is sent with the message in compact binary data format.

The MTOM standard, which is recommended by the World Wide Web Consortium, assumes that the binary data in the payload is the content of an element of type xsd:base64Binary.

More information about MTOM: http://www.w3.org/TR/soap12-mtom/.

Applying MTOM in the Web Services Runtime

When you configure the Web Services runtime, you have the option of activating or deactivating MTOM optimization for both point-to-point connections and for enhanced communication by using the Integration Server. You can activate or deactivate MTOM optimization for the following transport options:

      Direction connections (point-to-point). You can define whether MTOM optimization is required for the sender.

      Transferring a message from a sender to the Integration Server by using the Web Service adapter.

      Transferring a message from the Integration Server to a receiver by using the Web Service adapter. In this case the Integration Server is the sender where the base64Binary binary data is extracted as a message attachment in accordance with MTOM before the message is sent.

More information: Configuring the WS Adapter in the Integration Directory

What now needs to be done at the sender so that the binary data can be sent using MTOM? Nothing. If MTOM optimization is activated, the application developer only needs to assign the binary data encoded in base64Binary to the field that was modeled as an element of type xsd:base64Binary in the ES Repository. When the message is created, the Web Service runtime automatically recognizes from the element type that the data can be extracted as an attachment. Whether the data is extracted or not depends on the size of the data (if the binary data is not very big - as is the case for signatures, for example - it may be more appropriate not to do so).

Using MTOM in Mapping Programs

When the base64Binary-encoded binary data is extracted from the payload, the binary content of the element in the message structure is replaced by an <xop:include> statement. Since this is not how it was modeled in the XML Schema Definition for the message payload, the mapping program terminates when the mapping program attempts to access the binary content.

You can stop MTOM optimization from causing the mapping program to terminate as follows:

      Change your mapping program so that <xop:include> statements no longer cause it to terminate in future.

      Deselect the Do Not Resolve XOP Includes checkbox in the basic settings of the operation mapping. This setting means that before those mapping programs that were preconfigured with the operation mapping are executed, all previously extracted binary data is reinserted in the payload as base64Binary-encoded. The size of an attachment determines how long this process will take and what the strain on system resources will be.

XSLT Example

The following example illustrates how you can modify an XSLT mapping program so that it is not terminated when binary data is extracted as an attachment as part of MTOM optimization. For reasons of simplicity, the example has the following payload:

Example Payload Before and After MTOM Optimization

(1) Before MTOM Optimization

(2) After MTOM Optimization

<?xml version="1.0"
   encoding="utf-8"?>

<ROOT>xxxbinxxxbase64xxx</ROOT>

<?xml version="1.0"
   encoding="utf-8"?>

<ROOT>
 <xop:include
  xmlns:xop="http://www.w3.org/2004/08/xop/include"
  href="cid:00132120D4961DDBB695E429DA7E583C@sap.com">
</ROOT>

The following XSLT program accesses the content of the <ROOT> element directly by using the <xsl:value-of> XSLT element. Since this content is replaced by the <xop:include> element as part of MTOM optimization, <xsl:value-of> results in an error:

<xsl:transform version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
    <xsl:output method="xml" indent="no" />

    <xsl:template match="/">
       <ROOT><xsl:value-of select="/ROOT"/></ROOT>
    </xsl:template>

</xsl:transform>

To stop this error occurring, instead of accessing the content of <ROOT>, copy <ROOT> and its contents as illustrated in the following XSLT program:

<xsl:transform version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
    <xsl:output method="xml" indent="no" />

    <xsl:template match="/">
       <xsl:copy-of select="/ROOT"/>
    </xsl:template>

</xsl:transform>

If the source structure does not have any elements of type xsd:base64Binary at all, no errors occur if MTOM optimization is activated.

Accessing Attachments in Mapping Programs

Mapping programs are executed in the Java part of SAP NetWeaver AS. Consequently, the mapping runtime transfers the message payload from the ABAP part of the SAP NetWeaver Application Server to the Java part before the mapping program is executed. Since mapping programs do not usually access any MIME attachments in a message, the default setting is for the mapping runtime to transfer the payload only and not the attachments. This applies for both attachments that are removed as part of MTOM optimization in the Web services runtime, as well as for attachments that a sender sends together with a payload by using proxy methods in the XI runtime.

If you want to access an attachment from a mapping program, it must have been transferred from the ABAP part to the Java part prior to execution. You can configure this in the basic settings of the operation mapping in which you reference the mapping program (select the Read Attachments checkbox).

To be able to access attachments in a mapping program, the mapping API provides classes and methods. In detail, access works in the following way:

      Accessing attachments in message mappings

You have the following options if you need to access an attachment that is modeled in the source structure in a message mapping:

       Define a user-defined function and access the attachment by using methods of the mapping API. Access the attachment as a byte array (by using the getContent() method of the Attachment interface) or as a base64Binary-encoded string (by using the getBase64EncodedContent() method of the Attachment interface).

       Access the attachment by using a function in the message mapping. This is the case if you model the content of an element of type xsd:base64Binary as the inbound parameter for a function in the dataflow editor. The mapping runtime transfers the attachment to the inbound queue of the function as a base64Binary-encoded string; this also applies even if the attachment has been extracted as part of MTOM optimization.

      Accessing attachments in Java mappings

In Java mapping programs you can use the mapping API classes and methods directly for access to attachments.

      Accessing attachments in XSLT mappings

In XSLT mapping you can generally call Java methods (more information: XSLT Mapping with Java Enhancement), you can use the same mapping API methods from here for accessing attachments..

In the mapping API you access outbound message attachments with methods of the InputAttachments interface and attach the changed attachments to the target message using methods of the OutputAttachments interface.  For more information about the mapping API, see SAP Developer Network at https://www.sdn.sap.com/irj/sdn/javadocs (SDN user required).

More Information

Modeling Binary Data (CCTS/User-Defined)

Basic Settings for Operation Mappings

 

 

 

 

 

End of Content Area