MTOM is the W3C Message Transmission Optimization Mechanism, a method for efficiently sending binary data to and from web services. It uses XOP (XML-binary Optimized Packaging) to transmit binary data. XOP is the W3C XML-binary Optimized Packaging, a method of efficiently embedding binary data in XML.

The Web Service Component in USoft allows you to send binary data along with your SOAP message using the MTOM format. However, if you create a Web Service Component using the New Web Service Component wizard this does not create the correct method definition for sending MTOM. You must create a web service component from scratch if you want to send and/or receive MTOM messages.

To send binary data using MTOM format with USoft the binary data must be in files (not in the database). USoft reads the files and send them as an MTOM encoded message to the web service provider.

USoft can also receive MTOM encoded messages. Binary data sent in the message will be saved in a file in an specified output directory.

How to create

1. From the menu bar, select Define, RDMI, Web Service Components.

Supply a name for your web service.

2. Create a constructor method with the following Physical Method:

this=new com.usoft.WebServiceClient.WSClient()

this.setEndpointURL((U):0)

this.setInputFolder((U):1)

this.setOutputFolder((U):2)

The constructor method must have the same name as the component.

3. Add the following parameters to this method:

where:

• url represents the access point of the web service (SOAP address location in the WSDL file).
• input_folder represents the folder where the input files are located.
• output_folder represents the path to the location where the binary data received from the web service will be saved as files. The output folder can be omitted if the files are saved in the current directory. To omit the output folder, remove this.setOutputFolder((U):2) from the physical path

this.setEndpointURL((U):0)

this.setInputFolder((U):1)

and remove the output_folder input parameter.

4. On the Constructor tab, select the Active checkbox and specify using a select statement in the constructor SQL the values for the constructor parameters. Check the constructor SQL.

Example of constructor SQL:

SELECT 'http://www.test.com/TestingMtom', 'C:/Input/', 'C:/Output'

5. Create another method that will send the MTOM message, with the following physical method:

this.sendSOAPMessage((U) :0, (U) :1, (U) :2)

6. Add the following parameters to this method:

where:

• body represents the body of your SOAP message. The element that contains binary data must have as a subelement a USoft processing instruction that will specify that that element contains binary data in MTOM format:
• <?usoft-mtom path="path to the file that will be sent as binary with the message"?>.
• If there is a input_folder specified in constructor than the path can be only the file name, otherwize the path should be the absolute path of the file.

Example

<MTOMM-essage xmlns="http://www.test.com/TestMtom/v1">

       <request>

        <BinaryData><?usoft-mtom path="TestMTOM.doc"?></BinaryData>

      </request>

• header represents the header of the soap message
• SoapAction represents the SOAPAction HTTP header.

You can now execute a call to this service in your application:

INVOKE <web service component name>.<method name>

WITH

SELECT

'<MTOMMessage xmlns="http://www.test.com/TestMtom/v1">

        <request>

        <BinaryData><?usoft-mtom path="TestMTOM.doc"?></BinaryData>

        </request>

</ MTOMMessage >',

null,

'http://www.test.com/TestMtom/action1'

If the response has binary data in MTOM encoding, that data will be saved into files. The files are saved in the location specified by the output folder in the constructor method. The (unique) file names are generated by USoft without extensions and they will be returned in a USoft processing instruction in the element where the binary data should be.

Example of response

<soap:Envelope xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xop="http://www.w3.org/2004/08/xop/include" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" >

<soap:Body>

<MTOMResponse xmlns="http://www.test.com/TestMtom/v1">

<result>

<BinaryData>

<?usoft-mtom  path="C:\Output\2d33366539343139613a31313161333034366335373a2d37666666_20070330152414114"?>

</BinaryData>

</result>

</ MTOMResponse>

</soap:Body>

</soap:Envelope>

How to change the name  of the received files

When receiving a message that contains MTOM encoded binary data, USoft creates a unique file name by default and saves the binary data with that name.

If the response when calling an MTOM web service contains binary data in the SOAP message (base64 encoded) then USoft cannot automatically tell where the binary data is, to save it using a uniquely generated file name. In this case the user must create a transformation that will generate custom file names. Using this transformation, binary data in the response message will be saved regardless of the encoding (base64 in the SOAP message or MTOM attachments).

You can overrule the unique file name(s) created by USoft with a user-defined file name(s) based on the data in the received XML message by specifying a transformation (XSL). The transformation will be automatically applied by USoft to the received XML message.The transformation must produce the same result as the received message, except that for the binary element it must add a usoft-mtom processing instruction containing the path to the file:

<?usoft-mtom path="path to the file"?>

For example, if the received message is:

<MTOMResponse xmlns="http://www.test.com/TestMtom/v1">

<result>

<FileName>SomeFileName.txt</FileName>

<BinaryData></BinaryData>

</result>

</MTOMResponse>

and you want to retrieve the file name from the <FileName> element, the transformation must look like the following:

'<?xml version="1.0" encoding="windows-1252"?>

<xsl:stylesheet   version="1.0"   xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:ns1="http://www.test.com/TestMtom/v1">

<xsl:output method="xml" encoding="windows-1252" omit-xml-declaration="no"/>

<xsl:template match="*|@*|comment()|processing-instruction()|text()">

  <xsl:copy>    

<xsl:apply-templates select="*|@*|text()|comment()|processing-instruction()"/>  

</xsl:copy>

</xsl:template>

<xsl:template match="ns1: BinaryData">

<xsl:copy>

<xsl:processing-instruction name="usoft-mtom"><xsl:text>path="</xsl:text><xsl:value-of select="../ns1:FileName"/>

<xsl:text>.txt"</xsl:text></xsl:processing-instruction>

</xsl:copy>

</xsl:template>

</xsl:stylesheet>'

The resulting XML will be

<?xml version="1.0" encoding="windows-1252"?><MTOMResponse xmlns="http://www.test.com/TestMtom/v1">

<result>

<FileName>SomeFileName.txt</FileName>

<BinaryData><?usoft-mtom path="SomeFileName.txt.txt"?></BinaryData>

</result>

</MTOMResponse>

To specify the transformation to the web service component change the constructor method as follows:

1. Change the Physical Name to

2. Add a new input parameter with name 'transformation' and type String to the parameter list.

3. Change the constructor SQL to:

How to automatically generate a file name for received files

This example generates customer specific filenames for files received  in the web service response. The example shows how to build a file path based upon information in the returned XML (1), how the user's home directory can be found from local properties (2) and how a formatted date can be retrieved (3). Using these items, a suitable file name can be made for the received file data.

The transformation is as follows:

<?xml version="1.0" encoding="windows-1252" ?>
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:ns1="MyMTOMProviderURN" xmlns:System="xalan://java.lang.System" xmlns:java="http://xml.apache.org/xalan/java">
  <xsl:output method="xml" encoding="windows-1252" omit-xml-declaration="no" />
  <xsl:variable name="date" select="java:java.util.Date.new()" />
  <xsl:variable name="sdf" select="java:java.text.SimpleDateFormat.new('---yyyy-MM-dd---HH.mm.ss.SSS')" />
<xsl:template match="*|@*|comment()|processing-instruction()|text()">
<xsl:copy>
  <xsl:apply-templates select="*|@*|text()|comment()|processing-instruction()" />
  </xsl:copy>
  </xsl:template>
<xsl:template match="ns1:FileData">
<xsl:copy>
<xsl:processing-instruction name="usoft-mtom">
  <xsl:text>path="</xsl:text>
  <xsl:value-of select="System:getProperty('user.home')" />
  <xsl:text>/</xsl:text>
  <xsl:value-of select="local-name()" />
  <xsl:value-of select="java:format($sdf, $date)" />
  <xsl:text>.txt"</xsl:text>
  </xsl:processing-instruction>
  </xsl:copy>
  </xsl:template>
</xsl:stylesheet>

The sections of this transformation associated with retrieving items for the file name are described below:

1. The sections of the transformation shown above that are concerned with building a file path based upon information in the returned XML are as follows (with comments):

<xsl:value-of select="local-name()"/>

The XML returned from the Web Service is used as part of the file name. Since we do not know the XML response format in this example we just ask for the name of the current node. In practical applications, the query might be something like select="concat(../ABCService/Filename,../ABCService/defaultExtension)"

2. The sections of the transformation concerned with extracting the user's home directory from the local properties are as follows:

xmlns:System="xalan://java.lang.System"

Makes the java.lang.System.getproperty() method available for use below.

<xsl:value-of select="System:getProperty('user.home')"/>

The System name space is used to invoke a static method of the java.lang.System object.

3. The sections of the transformation that retrieve a formatted date are as follows:

xmlns:java="http://xml.apache.org/xalan/java"

Allows java objects to be created, as below.

<xsl:variable name="date" select="java:java.util.Date.new()"/>

Creates a java Date object that holds the current date and time.

<xsl:variable name="sdf" select="java:java.text.SimpleDateFormat.new('---yyyy-MM-dd---HH.mm.ss.SSS')"/>

Creates a simple date format to format the Date object into a string.

<xsl:value-of select="java:format($sdf, $date)"/>

The formatting of the current date by the simple date format is inserted as part of the desired file name.