Creating MTOM Enabled JAX-WS Web Services Using RAD/WID/Integration Designer

Summary:

Learn how to develop MTOM enabled JAX-WS web services using Rational Application Developer (RAD) or WebSphere Integration Developer (WID) or IBM Integration Designer. A detailed development process for both Top-Down and Bottom-Up approaches is presented.

MTOM (Message Transmission Optimization Mechanism) is a W3C standard that uses XOP (XML Binary Optimized Packaging) to transmit binary data. For more information on MTOM or XOP, please refer to [1] and [2] in the references section.

Scenario: Create a web service using Java API for XML-Based Web Services (JAX-WS) with an operation called “getFileAsMTOM” that will accept a file name as input and will return a response message with the file content as attachment using MTOM/XOP. The operation will also return the file name provided in the input, as part of the output. The implementation of the operation could include logic to read the file in a particular folder on the local drive and return it as part of the response.

A detailed development process for both Top-Down and Bottom-Up approaches is presented.

Bottom-Up Approach

There are two different service endpoint implementation types that you could use to develop web services using JAX-WS. (Refer to [4] in the References section for more information.)

1. JavaBeans Service Endpoint Interface and
2. Provider Interface

This article follows the first method to creating the web service using the Bottom-Up approach.

Steps:

• Create the Request JavaBean  ( SampleRequest.java - input object for the operation to be exposed on the web service interface). 

Input POJO - SampleRequest.java

• Create the Response JavaBean (output object for the operation to be exposed on the web service interface).

Output POJO - SampleResponse.java

• Create the Service Endpoint Interface.

TestMTOMIntf.java - Interface (SEI)

• Create the Implementation class that implements the Service Endpoint Interface.

TestMTOM.java - Implementation Class

• Add JAX-WS annotations as necessary. On both S.E.Interface and the Implementation classes add the annotations as necessary. In the above pictures named "TestMTOMIntf.java - Interface (SEI)" and "TestMTOM.java - Implementation Class", find the annotations that were added for this example. Refer to [3] in the References section for more information on JAX-WS annotations.

• Add                                                                                                                "@javax.xml.ws.BindingType (value=javax.xml.ws.soap.SOAPBinding.SOAP11HTTP_MTOM_BINDING)"  or              "@javax.xml.ws.BindingType (value=javax.xml.ws.soap.SOAPBinding.SOAP11HTTP_MTOM_BINDING)" based on whether you are using SOAP 1.1 or SOAP 1.2 binding. Add the annotation on the Implementation class to enable MTOM as shown above in the picture named "TestMTOM.java - Implementation Class".

• Generate the necessary artifacts.

Generate WSDL and Other artifacts

Generate Artifacts 2 (select JAX-WS)

Generate Artifacts 3 ("Enable MTOM Support" should show selected)

BottomUp - Web Project Showing Generated Artifacts

• Deploy to WAS/WESB/WPS and Test. In this example i used soapUI to test the operation. You can see in the picture that <xop:Include> tag has been added and you can see an attachment. From the soapUI tool, you can download the attachment, name the file appropriate and view the same to make sure you got back what you were expecting.

soapUI - TestCase - BottomUp

Top-Down Approach

In the Top-Down approach, we start with creating a WSDL file. We then generate the necessary Java Beans and then code the logic in the generated implementation class.

Steps:

• Create the WSDL file.

                                                    MTOMInterface.WSDL

<?xml version="1.0" encoding="UTF-8"?><wsdl:definitions name="MTOMInterface" targetNamespace="http://Sample/MTOMInterface" xmlns:bons1="http://Sample" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:tns="http://Sample/MTOMInterface" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <wsdl:types>
    <xsd:schema targetNamespace="http://Sample/MTOMInterface">
      <xsd:import namespace="http://Sample"/>
      <xsd:element name="getFileAsMTOM">
        <xsd:complexType>
          <xsd:sequence>
            <xsd:element name="input1" nillable="true" type="bons1:SampleRequest"/>
          </xsd:sequence>
        </xsd:complexType>
      </xsd:element>
      <xsd:element name="getFileAsMTOMResponse">
        <xsd:complexType>
          <xsd:sequence>
            <xsd:element name="output1" nillable="true" type="bons1:SampleResponse"/>
          </xsd:sequence>
        </xsd:complexType>
      </xsd:element>
    </xsd:schema>
        <xsd:schema attributeFormDefault="unqualified" elementFormDefault="unqualified" targetNamespace="http://Sample">
      <xsd:complexType name="SampleResponse">
  <xsd:sequence>
   <xsd:element minOccurs="0" name="FileContent" type="xsd:base64Binary">
   </xsd:element>
   <xsd:element minOccurs="0" name="FileName" type="xsd:string">
   </xsd:element>
  </xsd:sequence>
 </xsd:complexType>
      <xsd:complexType name="SampleRequest">
  <xsd:sequence>
   <xsd:element minOccurs="0" name="FileName" type="xsd:string">
   </xsd:element>
  </xsd:sequence>
 </xsd:complexType>
    </xsd:schema>
    </wsdl:types>
    <wsdl:message name="getFileAsMTOMRequestMsg">
    <wsdl:part element="tns:getFileAsMTOM" name="getFileAsMTOMParameters"/>
  </wsdl:message>
    <wsdl:message name="getFileAsMTOMResponseMsg">
    <wsdl:part element="tns:getFileAsMTOMResponse" name="getFileAsMTOMResult"/>
  </wsdl:message>
    <wsdl:portType name="MTOMInterface">
    <wsdl:operation name="getFileAsMTOM">
      <wsdl:input message="tns:getFileAsMTOMRequestMsg" name="getFileAsMTOMRequest"/>
      <wsdl:output message="tns:getFileAsMTOMResponseMsg" name="getFileAsMTOMResponse"/>
    </wsdl:operation>
  </wsdl:portType>
  
  <wsdl:binding name="MTOMInterfaceHttpBinding" type="tns:MTOMInterface">
    <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
    <wsdl:operation name="getFileAsMTOM">
      <soap:operation soapAction=""/>
      <wsdl:input name="getFileAsMTOMRequest">
        <soap:body use="literal"/>
      </wsdl:input>
      <wsdl:output name="getFileAsMTOMResponse">
        <soap:body use="literal"/>
      </wsdl:output>
    </wsdl:operation>
  </wsdl:binding>
  <wsdl:service name="FetchFileService">
    <wsdl:port binding="tns:MTOMInterfaceHttpBinding" name="MTOMInterfaceHttpPort">
      <soap:address location="http://localhost:9080/TEST/FetchFileService"/>
    </wsdl:port>
  </wsdl:service> 
</wsdl:definitions>

• Generate the JavaBean Skeleton by enabling MTOM support.

Generate Java Bean Skeleton - TopDown

Generate Java Bean Skeleton (select JAX-WS) - TopDown

Generate Java Bean Skeleton (Enable MTOM) - TopDown

• Implement the logic for the operation that is to be exposed.

MTOMInterfaceHttpBindingImpl - Implementation Class

MTOMInterfaceHttpBindingImpl - Implementation Class

• Deploy to WAS/WESB/WPS and Test. In this example i used soapUI to test the operation. You can see in the picture that <xop:Include> tag has been added and you can see an attachment. From the soapUI tool, you can download the attachment, name the file appropriate and view the same to make sure you got back what you were expecting.

soapUI - Test MTOM - Top Down

For information on how to enable MTOM on Web Services in DataPower, Please Check my post – DataPower: Encoding base64Binary Inline Data into MTOM.

References:

[1] SOAP Message Transmission Optimization Mechanism

[2] XML-binary Optimized Packaging

[3] IBM InfoCenter: JAX-WS Annotations

[4] IBM InfoCenter: Developing Web services application from JavaBeans

[5] IBM InfoCenter: Developing Web services applications from existing WSDL files with JavaBeans

Unable to Create Profile: Installation Issue with IBM Integration Designer V 7.5

Summary:
Getting errors when you are trying to reinstall IBM Integration Designer V 7.5? See what you can do to resolve the issue.


IBM Integration Designer V 7.5 (previously called WebSphere Integration Developer) comes with IBM DB2 Express. Embedded Derby database was used with WebSphere Integration Developer.

DB2 Express Package with IBM Integration Designer V 7.5

IBM Infocenter has provided information for troubleshooting issues that you might face when installing or uninstalling IBM Integration Designer V 7.5. Check [1] in the references section.

Background: I was trying to reinstall IBM Integration Designer V 7.5 on a 64bit windows 7 system. I was able to successfully install and uninstall it for the first time. The reason for uninstalling it was to install DB2 Express with a different account which probably does not hold relevance here.

Issue: Re Installation of IBM Integration Designer V 7.5 with the test environment fails during the creation of a profile. As mentioned in [1] - “If you try to reinstall to the same location, or if you try to reinstall after a failed uninstall, the installation might fail because a new profile cannot be created.”

Resolution: IBM Infocenter [1] suggests that “If databases were created for the test environment, the databases must be dropped before you can create a new profile. If the databases are not automatically dropped during uninstall, you must drop them manually. “

Note that in my case, I had no prior DB2 installation on the system and the installation was done using the “typical installation” configuration from the Launchpad.

During the uninstallation process using the IBM Installation Manager, I had already uninstalled the DB2 Express also. How do I drop the databases manually when DB2 has already been uninstalled? Here is what I did.

• Removed the “BPMINST” folder on c:\ drive.

BPMINST Folder

• Removed the “DB2” folder under c:\ProgramData\IBM.

DB2 Folder

For Windows 32 bit systems, find the corresponding folders and try to delete them if you are facing similar issues.

NOTE: If you are having issues deleting the above two folders, try restarting the system and deleting them again. Also, make sure that you either disable the anti-virus software during the installation process or provide full access permission for this program in the anti-virus software.

Once I deleted the above two folders, I was able to install IBM Integration Designer V7.5 and the test environment without any issues.

References:

[1] IBM Integration Designer V 7.5: Troubleshooting the installation process.

DataPower: Encoding base64Binary Inline Data into MTOM

Summary:
Learn how to encode base64Binary data as MTOM/XOP using an XSLT in DataPower.


MTOM (Message Transmission Optimization Mechanism) is a W3C standard that uses XOP (XML Binary Optimized Packaging) to transmit binary data. For more information on MTOM or XOP, please refer to [1] and [2] in the references section.

Scenario:

1. Host service returning (images) base64Binary data inline.
2. DataPower to encode the base64Binary data and send the response to the client as MTOM/XOP.

Scenario

In-order to achieve this, you will need to create a ‘MTOM Policy’ object. Find MTOM Policy object under Objects/XML Processing/MTOM Policy. MTOM policy object can be used for encoding or decoding by selecting the respective MTOM Mode on the Policy Object.

The name that I used for the MTOM Policy Object is ‘MTOM ‘ and for the scenario, we are trying to encode the base64Binary to MTOM so, I selected MTOM Mode as ‘encode’.

Under the MTOM Rules tab on the object, you will need to add a rule providing the XPath expression pointing to the element that has the base64Binary Data.

MTOM Policy Rule

Once the MTOM Policy object has been created, you can use it in any of your services in DataPower. You can do this in two ways.

1. In your service response policy in DataPower, you can configure a Transform action and use the preshipped mtom.xsl with the MTOM Policy object that you have created as discussed in (References) [3].
2. For scenarios where you have a generic DataPower service / processing rule for multiple back-end services and if you have a need to use different MTOM policy objects for different services, you could call the preshipped ‘mtom-implementation’ template in your own XSLT as follows.

You can use your own logic to pick the respective MTOM Policy name based on the backend service/operation being invoked.

<xsl:include href="store:///dp/mtom.xsl"/>

  <xsl:template match="/">

      <xsl:call-template>

            <xsl:with-param select="'MTOM'"/>

      </xsl:call-template>

  </xsl:template>

WSDL: Unlike SWA (SOAP With Attachments) definitions in the WSDL bindings, MTOM does not need any specific changes in the WSDL. In the above scenario, the element ‘image’ which holds the base64Binary data coming from the backend service  can be defined as

<xsd:element name="image" type="xsd:base64Binary" />

 The same definition for image element will also work for MTOM.

References:

[1] SOAP Message Transmission Optimization Mechanism

[2] XML-binary Optimized Packaging

[3]Processing Attachments in WebSphere DataPower SOA Appliances