Apache Axis2 supports binary attachment handling using both SOAP Message Transmission Optimization Mechanism (MTOM) as well as SOAP with Attachments (SwA). Users do not need to worry about any configuration in order to receive MTOM/SwA messages. Apache Axis2 Engine automatically identifies the type of the incoming message (plain SOAP/MTOM/SwA) based on the message's content type HTTP header. However, user needs to configure the enableMTOM/SwA in order to be able to send MTOM/SwA messages. This KB discusses the various attachment configuration options available with Apache Axis2.

Attachment Configurations Available With Axis2

Axis2 user is not expected to enable MTOM & SwA together. In such a situation MTOM will get priority over SwA.

• Enabling MTOM
  • Using Client Side Options

  	options.setProperty(Constants.Configuration.ENABLE_MTOM,Constants.VALUE_TRUE);

  • Server Side

  <parameter name="enableMTOM" locked="false">true</parameter>

• Enabling SwA
  • Using Client Side Options

  options.setProperty(Constants.Configuration.ENABLE_SWA, Constants.VALUE_TRUE);

  • Using Axis2.xml

  <parameter name="enableSwA" locked="false">true</parameter>

Common Attachment Configurations - File Caching

Axis2 file caching mechanism allows the user to receive very large attachments irrespective of being an Axis2 server or a client. Trying to receive large attachments without enabling file caching can result in OutOfMemory situations. Axis2 has been tested with attachments with the sizes larger than 1GB. Receiving Attachment sizes will only be limited by the free space available at the given attachment temp directory.

• Enabling File Caching for Attachments
  • Using Client Side Options

  options.setProperty(Constants.Configuration.CACHE_ATTACHMENTS,
  Constants.VALUE_TRUE);

  • Using Axis2.xml

  <parameter name="cacheAttachments" locked="false">true</parameter>

• Specifying a directory to store the cached attachments- User is expected to clean this directory regularly. Axis2 does not clean up the cached attachments. Receiving size limitation for attachments will depend on the amount of free space available at this given directory. This configuration is mandatory when file caching is switched ON.
  • Using Client Side Options

  options.setProperty(Constants.Configuration.ATTACHMENT_TEMP_DIR,TempDir);

  • Using Axis2.xml

  <parameter name="attachmentDIR" locked="false">TempDir</parameter>

• Specifying a file size threshold- Only the Attachments larger than the specified size will be cached. Smaller ones will be handled directly at memory. Size to be given in bytes.
  • Using Client Side Options

  options.setProperty(Constants.Configuration.FILE_SIZE_THRESHOLD, "4000");

  • Using Axis2.xml

  <parameter name="sizeThreshold" locked="false">4000</parameter>

Applies to

Apache Axis2/Java post 1.0 versions

More Information

MTOM Guide -Sending Binary Data with SOAP [1]

Binary with ADB [2]