Configure MTOM Support in the SOAP Adapter
This use case describes how to configure Message Transmission Optimization Mechanism (MTOM) support in the SOAP Adapter.
SOAP Message Examples and Structure
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>
<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.
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).
-
Specify the base64Binary element-based WSDL in the Connections page when configuring the SOAP Adapter.
-
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.
If you are integrating with ErpIntegrationService, ErpObjectAttachmentService, or GenericSOAPService, the appropriate MTOM attachment options are automatically selected based on the chosen operation and cannot be deselected because MTOM is used by default for these services.
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.
<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
-
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.
-
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 the illustration oic3_attachmentref2.pngIf integrating with ErpIntegrationService, ErpObjectAttachmentService, or GenericSOAPService, the response is received as an attachment reference instead of base64Binary content. To process the response, the attachment reference can be directly used by a stage file action to read. This eliminates the need for using mapper functions or writing to a stage file action explicitly to get the reference from base64. This behavior speeds up the development and execution of integrations.
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.