WSO2 Enterprise Integrator 3 min

Handling MTOM and SWA messages in WSO2 ESB

Sidharth Dash
Integration Specialist

WSO2torial_small.png MTOM/SWA message is a mechanism to attach file in an existing SOAP message. In MTOM/SWA message the soap message is divided into multiple parts which divided by using a boundary. Looking closely to the attachment SWA/MTOM the header for Content-Type is multipart/related which represents the message contains multiple parts in other words has an attachment. 



In WSO2 ESB the MTOM/SWA message can be handled in multiple ways. But before that a good knowledge of messageFormatters and messageBuilders is necessary. In axis2.xml file we can configure how to handle a particular type of message.

Configuring messageFormatters and messageBuilders in axis2.xml

  • Default case:

The MTOM/SWA messages are received and processed as a normal message.

  • Configuring BinaryRelayBuilder:

 <messageBuilder contentType="multipart/related"   class="org.wso2.carbon.relay.BinaryRelayBuilder"/>

If there is no need of mediation of the message and it is only pass-through than we can convert the entire message (SOAP Envelope and attachment) into Base-64 encoded value using this builder. Here a new SOAP message is build where the encoded value is inserted as a body.


  • Will be faster in processing
  • No issue while using ActiveMQ to store intermediately (for more details about issues related to ActiveMQ and SWA/MTOM please refer below sections)


  • Cannot handle attachment in any way.

Enable MTOM/SWA in proxy

Although MTOM/SWA can be enable in axis2.xml for the entire ESB but if there is a need of enabling it just for one proxy we can use the below property

<property name="enableMTOM" value="true" scope="axis2"/> 

<property name="enableSWA" value="true" scope="axis2"/> 

Note: In case of MTOM message if

<property name="enableMTOM" value="false" scope="axis2"/> 

and there is MTOM message is received by ESB, than ESB get confused on how to handle the attachment. In this case the  attachment is extracted , base-64 encoded and inserted into

<xop:Include xmlns_xop=”http://www.w3.org/2004/08/xop/include” href=”cid:test.txt” />


Writing custom mediator to handle MTOM/SWA message

The mediate (MessageContext context) method takes a parameter of synapse message context. But in order to get the attachment from the message we need to have Axis2MessageContext which can provide us a rich set of API to manipulate the attachment.

The best way to extract the attachment is through the cid value of the attachment. We can find the inputStream of the attachment from the DataHandler object (dataHandler). After we can use this inputStream to store the attachment as a file and further process it.

There is another method to extract the attachment which is very simple to implement which is defined below. We can get Map containing all parts for the message in other words SOAP body and attachment.


However, there is a big catch in using attachmentMap. In case of multiple attachment, the MTOM type messages works fine (all the attachment are present in the map) but the in SWA type messages only the first attachment can be extracted.

Scanning the attachment with Anti-Virus

In order to scan the attachment with a virus scanner we need to install an Anti-Virus in the machine where the ESB is running. In my case I have used ClamAV an open source Anti-Virus. ClamAV has a CLI which can be used to scan any file, if the file contains no virus than an OK response is returned.

The custom mediator use CLI provided by ClamAV to scan the attachment in the SOAP message.

  • The inputStream of the attachment from the DataHandler can be used to save the file in a temporary location.
  • The file can be scanned using command “clamscan filename”.
  • The temp file is deleted (it is always deleted no matter what).
  • If the file contains virus than the attachment can be removed from the messageContext.

If you have any questions about this blogpost contact us via the comments section of this blog. For more View also our WSO2 Tutorialswebinars or white papers for more technical information. Need support? We do deliver WSO2 Product Support, WSO2 Development SupportWSO2 Operational Support and WSO2 Training Programs.

ESB Selection Guide

esb frontback
Get it now
What's on our menu