1. Using the SOAP Adapter with Oracle Integration Generation 2
  2. Implement Common Patterns Using the SOAP Adapter
  3. Configure MTOM Support in the SOAP Adapter

Configure MTOM Support in the SOAP Adapter

This use case describes how to configure Message Transmission Optimization Mechanism (MTOM) support in the SOAP Adapter.

See SOAP Adapter Capabilities for conceptual information.

SOAP Message Examples and Structure

The following example shows a SOAP message with inline binary content:
MIME-Version: 1.0
Content-Type: Multipart/Related; boundary=MIME_boundary;
type="application/soap+xml"; start="<claim@insurance.com>" 

--MIME_boundary
Content-Type: application/soap+xml; charset=UTF-8
Content-Transfer-Encoding: 8bit
Content-ID: <claim@insurance.com>

<Envelope>
  <Body>
    <ReceiveImage> 
     <filename>abc.jpg</filename>
      <image>.... JPEG image base64 .....</image>    
    </ReceiveImage>
  </Body>
</Envelope>
The following example shows a SOAP message with MTOM/XOP:
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" 
xmlns:xop='http://www.w3.org/2004/08/xop/include' 
xmlns:xop-mime='http://www.w3.org/2005/05/xmlmime'>
 <soap:Body>
   <Order>
     <orderNumber>ABC</orderNumber> 
     <orderType>backorder</orderType>
     <image xop-mime:content-type='image/jpeg'>
       <image xop-mime:content-type='image/jpeg'>
     </image>
   </Order>
 </soap:Body>
</soap:Envelope>


--MIME_boundary

 
Content-Type: image/jpeg
Content-Transfer-Encoding: binary
Content-ID: <image@insurance.com> 4

...binary JPG image...


--MIME_boundary--

The  MTOM message structure is as follows:

  • The start parameter indicates which part of the MIME message is the root XOP document.

  • The Content-ID value identifies a part of the MIME message. In this case, it is the root XOP document.

  • The <xop:Include> element references the JPEG binary attachment.

  • The Content-ID identifies the JPEG in the binary attachment.

application/octet-stream MIME attachment

A MIME attachment with the content type application/octet-stream is a binary file. It is typically an application or document that must be opened in an application, such as a spreadsheet or word processor. If the attachment has a file name extension associated with it, you may be able to identify the type of file. For example, an .exe extension indicates it is a Windows or DOS program (executable). A file ending in .doc can probably be opened in Microsoft Word. In addition to the generic application/octet-stream content type, you may also encounter attachments that have different subtypes (for example, application/postscript, application/x-macbinary, and application-msword). They are similar to application/octet-stream, but apply to specific types of files.

SOAP Message Transmission Optimization Mechanism/XML-binary Optimized Packaging (MTOM/XOP) describes a method for optimizing the transmission of XML data of type xs:base64Binary in SOAP messages. When the transport protocol is HTTP, MIME attachments carry that data while at the same time allowing both the sender and the receiver direct access to the XML data in the SOAP message without having to be aware that any MIME artifacts were used to marshal the xs:base64Binary data. The binary data optimization process involves the following:

  • Encoding the binary data

  • Removing the binary data from the SOAP envelope

  • Compressing and attaching the binary data to the MIME package

  • Adding references to that package in the SOAP envelope

When MTOM is enabled, the MTOM specification does not require that the web service runtime use XOP binary optimization when transmitting base64binary data. Instead, the specification enables runtime to choose to do so. This is because in certain cases the runtime may decide that it is more efficient to send base64binary data directly in the SOAP message (for example, when transporting small amounts of data in which the overhead of conversion and transport consumes more resources than just inlining the data as is). However, the Oracle WebLogic Server web services implementation for the MTOM for JAX-RPC service always uses MTOM/XOP when MTOM is enabled.

Design Time

When you configure the SOAP Adapter as an invoke connection in an integration, MTOM attachment options are shown in the Adapter Endpoint Configuration Wizard when a base64Binary element is present in the WSDL messages for a given operation in both request and response messages (for synchronous).

  1. Specify the base64Binary element-based WSDL in the Connections page when configuring the SOAP Adapter.

  2. Enable the appropriate Send attachments in request (for outbound request) and Accept attachments in response (for outbound response) options to enable MTOM processing for that endpoint.
    Description of soap_mime_headers.png follows
    Description of the illustration soap_mime_headers.png

MTOM support cannot be configured in a trigger connection.

If you select to enable MTOM for a request message, the XPath for that binary node is calculated and stored in the JCA file as an interaction spec property.

For example:
<property name="attachmentXpathInfo" value="/*[namespace-uri()='http://www.oracle.com/UCM' and 
local-name()='GenericRequest']/*[namespace-uri()='http://www.oracle.com/UCM' and local-name()=
'Service']/*[namespace-uri()='http://www.oracle.com/UCM' and local-name()='Document']/*[namespace-uri()
='http://www.oracle.com/UCM' and local-name()='File']/*[namespace-uri()='http://www.oracle.com/UCM' 
and local-name()='Contents']"/>

For a response message, the property attachmentXpathInfoForResponse is used in the JCA file to represent the XPath.

Mapping

  1. For an outbound request, any attachment reference from the virtual file system (VFS) can be mapped to the base64Binary element of the outbound message. As shown below, attachmentReference from the REST source is mapped to the base64Binary element of the message.


    Description of soap_mime_mapper1.png follows
    Description of the illustration soap_mime_mapper1.png

  2. For an outbound response, the attachment is saved to the VFS and the base64Binary element of the payload holds the VFS reference. The VFS reference can be further used to map it to a REST resource or an FTP Adapter:
    Description of soap_mime_mapper2.png follows
    Description of the illustration soap_mime_mapper2.png

Runtime

During runtime, MTOM processing is triggered based on the availability of the attachmentXpathInfo and attachmentXpathInfoForResponse properties in the JCA file. This information is persisted during design time.

In the outbound request, the XPath information given by attachmentXpathInfo in the JCA file creates an attachment in the cloud message and structures the SOAP message in the MTOM-specific format.

In the outbound response, the logic checks if there is any attachment received in the response of the cloud message, which is further saved in the VFS. The node represented by the property attachmentXpathInfoForResponse substitutes it with the VFS reference of the attachment in the cloud message.