How to Enable MTOM Support for JAX-WS Web Services Running on WebSphere Application Server

I’m going to keep this post short today.  This is something I ran across today and it was rather irritating that I couldn’t find any good documentation on the subject. This is a highly specific problem but it might help a few of you out there.

Here’s the scenario.  I’m working on building a web service using JAX-WS 2.1 that is being deployed to WebSphere Application Server (WAS) 7.0.  I’m using Rational Application Developer (RAD) version 7.5.5.1 as my IDE. It’s a very simple web service that has to return moderate sized binary data chunks in the SOAP response (PDF files).  My team have decided to use the Message Transmission Optimization Mechanism (MTOM) as the method for attaching the bytes of the PDF files.  This is a relatively painless process if you have all the information you need.  However, the IBM WAS 7 InfoCenter has an incomplete description of how to enable MTOM on a web service.  IBM’s documentation tells you how to annotate your web service properly, but it doesn’t tell you that you also need to make a change to the IBM-specific webservices.xml file.  webservices.xml can be found in your Web Content\WEB-INF folder in your web application.

The change you have to make to webservices.xml is simple.  You just have to find the <webservice-description> tag for the web service on which you are enabling MTOM then change the value of the <enable-mtom> tag from false to true.  An example (a fragment of the webservices.xml file) of what this should look like is given below.

<webservice-description>
   <webservice-description-name>MyWebService</webservice-description-name>
   <port-component>
     <port-component-name>MyWebService</port-component-name>
     <wsdl-service xmlns:pfx="http://www.comapny.com/MyWebService/">
       pfx:DocumentService</wsdl-service>
     <wsdl-port xmlns:pfx="http://www.company.com/MyWebService/">
       pfx:DocumentServiceSOAP</wsdl-port>
     <enable-mtom>true</enable-mtom>
     <service-endpoint-interface>com.comapny.MyWebService</service-endpoint-interface>
     <service-impl-bean>
       <servlet-link>com.comapny.MyWebServiceSOAPImpl</servlet-link>
     </service-impl-bean>
   </port-component>
 </webservice-description>

Once your web service has been properly annotated and you make the above change to webservices.xml your web service will be setup to support MTOM.

Summary

To summarize, you have to follow two steps to get MTOM support in your JAX-WS web service:

1. Follow IBM’s documentation on annotating your web services implementation classes properly for MTOM support.
2. Set the <enable-mtom> tag to true in the webservices.xml file.

One more note is that the problem of IBM’s incomplete documentation is exasperated by the fact that their “Generate Java bean skeleton” wizard also neglects to update the webservices.xml file properly.  Even if you check the “Enable MTOM Support” check box on the “WebSphere JAX-WS Top Down Web Service Configuration” screen the webservices.xml file will remain unchanged after the wizard completes.  So whether you are using the wizard to create your web service code or doing it manually, you will have to update the webservices.xml afterward to fully enable MTOM support.

Explaining the Confusion

The webservices.xml file is actually completely optional — at least according to This WAS 7 InfoCenter page. Supposedly you can remove the webservices.xml file from your application and the annotations will be enough to enable MTOM support and you won’t have to go through any extra, manual steps.  If I sound unsure it’s because I am.  I tried removing the webservices.xml file from my web service and, after a re-deploy to the server, it was no longer accessible (received this error: “Error 404: SRVE0190E: File not found: /MyWebService”).  Once I restored the webservices.xml file and re-deployed I could reach the web service.

What I can verify is that the file is used on the server side to override any annotations that are found in the web service code.  This explains why MTOM doesn’t work unless you have <enable-mtom> set to true in webservices.xml.  Unfortunately, this is also probably why the file is not kept in sync when generating the code although I have no proof to back up that statement.  Please comment if you have a better or more correct explanation!

References

It seems that none of the official IBM references really catch this problem (otherwise I would not be writing this post :)).  As mentioned earlier in this post, the IBM WAS 7 InfoCenter has some basic directions on enabling MTOM support that are incomplete.  Two other references of high quality, but also incomplete, with respect to MTOM support, are the Redbooks IBM WebSphere Application Server V7.0 Web Services Guide and Rational Application Developer V7.5 Programming Guide.  The Redbooks offer different levels of detail about MTOM support, so it’s worth your time to research MTOM in both books.