Sending MTOM-Encoded Binary Data

This section discusses how to send MTOM-encoded binary data and discusses how to:

  • Set target connector properties to send MTOM-encoded binary data.

  • Develop messages to send MTOM-encoded binary data.

Setting Target Connector Properties to Send MTOM-Encoded Binary Data

When sending MTOM-encoded binary data, you must use the HTTP target connector. The HTTP target connector features an MTOM property that you must set to Y for MTOM encoding to occur. When you set the MTOM property to Y, the HTTP target connector attempts to convert all outgoing message to the MTOM wire format.

See Integration Broker Administration: Using the HTTP Target Connector.

Developing Messages to Send MTOM-Encoded Binary Data

An outgoing MTOM message is composed of a SOAP message and one or more sets of binary data. Segments are used to add the binary data to the outgoing request.

For each chunk of data, use a single segment as follows:

  1. Create the segment.

  2. Copy the data to the segment.

  3. Add the MIME type that is to appear for the MIME part containing the binary in the outgoing MTOM wire message.

  4. Set the content transfer encoding to binary.

In PeopleCode this appears as:

 &theMessage.CreateNextSegment();

  If (&theMessage.SetContentString(&dataString)) Then
     &theMessage.SegmentContentType = "image/jpeg";
     &theMessage.SegmentContentTransfer = %ContentTransfer_Binary;
  End-If;

The SetContentString method requires character data, and is not capable of passing binary data. For MTOM, pass in a Base64-encoded string that contains the binary data. The File object method GetBase64StringFromBinary allows a binary file to be read in and captured as a string; use this string to set the data for the newly created segment.

See PeopleCode API Reference: SetContentString method: Message class, PeopleCode API Reference: GetBase64StringFromBinary method: File class.

When seen on the wire, the SOAP XML in the MIME multipart message contains xop:Include references. These references point to the MIME parts that contain the binary data. In order to be able to construct these references, Integration Broker requires that a specific XML element, PsftXopInclude, is present in the outgoing message.

Each PsftXopInclude element corresponds directly to an xop:include in the outgoing wire message, and therefore each PsftXopInclude element logically corresponds to an instance of binary data. Placement of the PsftXopInclude element in the XML is application-specific; Integration Broker does not require any particular location.

In the following example the first instance of the PsftXopInclude element corresponds to the logical point to include an image and the second PsftXopInclude element corresponds to the logical point to include a binary document:

<?xml version='1.0'?>
<JobApplication>
  <Photo name='JohnSmith'>
    <PsftXopInclude SegmentNumber='1'/>
  </Photo>
  <Resume name='JohnSmithCV'>
    <PsftXopInclude SegmentNumber='2'/>
  </Resume>
</JobApplication>

The value of the SegmentNumber attribute is used by Integration Broker to link the PsftXopInclude entry to a specific segment used to add the data. For the purposes of MTOM, the first segment used to add binary data is considered to be number 1, the second segment, number 2, and so on. Care should be taken when setting these values as Integration Broker does not check to ensure that they are correct; they are used as-is to build the xop:include references in the wire message.

In the previous example, the message data is not SOAP-wrapped. You can choose to build your own SOAP wrapper or elect to have Integration Broker SOAP-wrap the message. If Integration Broker is to SOAP wrap the message, you must set the HTTP target connector property SOAPUpContent to Y.

See Integration Broker Administration: Using the HTTP Target Connector.

An example of XML to use this feature is as follows: 

<?xml version="1.0"?>
<flt:process xmlns:flt=" http://xmlns.oracle.com/Enterprise/ 
  Tools/schemas/flightdata.v1">
  <PsftXopInclude/>
  <flt:input1>515</flt:input1>
  <PsftXopInclude/>
  <flt:input2>664</flt:input2>
 </flt:process>

You would include the previous XML in the XmlDoc object and add it to the first segment of the message.

The additional segments include the binary data associated with each declaration. For example: 

&MSG = CreateMessage(Message.FLIGHTDATA);

&MSG.SetXmlDoc(&xmldoc);

&MSG.CreateNextSegment();
&MSG.SetContentString("your encoded image data");
&MSG.SegmentContentType = "image/gif";
&MSG.SegmentContentTransfer = %ContentTransfer_Binary;

&MSG.CreateNextSegment();
&MSG.SetContentString("your encoded video here")
&MSG.SegmentContentType = "video/mp4";
&MSG.SegmentContentTransfer = %ContentTransfer_Binary;

%IntBroker.Publish(&MSG);

The following code example provides another XML example that demonstrates using this feature:

Local File &theFile;
Local XmlDoc &theXmlDoc;
Local Message &theMessage;
Local string &theBase64encodedString;

/* note: this example does not have any error handling, in */
/* order to keep the code relatively short and concise.    */

/* create the message, and add the basic XML message data */
/* ------------------------------------------------------ */

&theMessage = CreateMessage(Operation.QE_FLIGHTPLAN_UNSTRUCT);
Local string &xml;

/* this example requires the SOAPUPContent HTTP Target */
/* connector property to be set to "Y", so that the    */
/* outbound XML will be SOAP wrapped.                  */

&xml = &xml | "<?xml version='1.0'?>";
&xml = &xml | "<JobApplication>";
&xml = &xml | "<Photo name='JohnSmith'>";
&xml = &xml | "<PsftXopInclude SegmentNumber='1'/>";
&xml = &xml | "</Photo>";
&xml = &xml | "<Resume name='JohnSmithCV'>";
&xml = &xml | "<PsftXopInclude SegmentNumber='2'/>";
&xml = &xml | "</Resume>";
&xml = &xml | "</JobApplication>";
&theXmlDoc = CreateXmlDoc(&xml);
&theMessage.SetXmlDoc(&theXmlDoc);

/* add an image to the outgoing message */
/* ------------------------------------ */

&theFile = GetFile("D:\output\smallPicture.jpg", "R", %FilePath_Absolute);
If &theFile.IsOpen Then
   &theBase64encodedString = &theFile.GetBase64StringFromBinary();
   &theFile.Close();
End-If;

&theMessage.CreateNextSegment();
If (&theMessage.SetContentString(&theBase64encodedString)) Then
   &theMessage.SegmentContentType = "image/jpeg";
   &theMessage.SegmentContentTransfer = %ContentTransfer_Binary;
End-If;
/* add a PDF file to the outgoing message */
/* -------------------------------------- */

&theFile = GetFile("D:\output\smallDocument.pdf", "R", %FilePath_Absolute);
If &theFile.IsOpen Then
   &theBase64encodedString = &theFile.GetBase64StringFromBinary();
   &theFile.Close();
End-If;

&theMessage.CreateNextSegment();
If (&theMessage.SetContentString(&theBase64encodedString)) Then
   &theMessage.SegmentContentType = "application/pdf";
   &theMessage.SegmentContentTransfer = %ContentTransfer_Binary;
End-If;
/* send the message */
/* ---------------- */

%IntBroker.Publish(&theMessage);

Note:

PeopleSoft currently supports MTOM for asynchronous messaging only.

Related Topics