In the previous blog SOAP with Attachments made easy with CE; we looked at all the different options to send binary data using SOAP. Specifically we looked at what the client application needs to do in order to add MTOM attachment before calling a web service, and then we looked at how to create a web service that receives attachments. The aim of this blog is to show you how to use an implementation of SAAJ called Apache Axis that allows you to add MIME attachments to SOAP responses.
Axis (Apache EXtensible Interaction System) is Open Source and the third generation of Apache SOAP. It takes care of converting the Java objects to SOAP data when it sends or receives results. Axis is simply an implementation of SOAP contained in a JAR file that can be added to any web application. Installing it can be a bit tricky but hopefully this blog will help. There are currently 2 different implementations of Axis, 1.4 and Axis2. Axis2 is the successor and supports both MTOM attachments and RESTful services. The next version of this blog will feature Axis2; for now the focus will be on SAAJ with Axis 1.4 as it is widely adopted by the industry today.
Let’s get started
The following steps will show you how to deploy both the Axis libraries and an example Axis web service to the SAP NetWeaver Composition Environment EhP1. The web service shown in this scenario can both receive and respond with MIME SOAP attachments.
External Library Project
Make sure to download the Axis 1.4 jar files from Apache (http://ws.apache.org/axis) and add them to the libraries folder. The most important library is the axis.jar file but there are several other dependent jar files that you also need; for example activation and mail libraries are specifically used for SOAP Attachments. You do not have to deploy the external library project; rather create a dependency to your web application that you will create later. You will do so using the notion of Public Parts and expose all the jar files as shown below. Then depending on the type of Public Part the libraries will be assembled into your web project. It is important that you define the public part of type Assembly in the next step.
J2EE Web Module Project
Add a dependency to the External Library Project of type “Build Time”, as mentioned the Axis libraries will automatically be added to the Web Module war file.
Axis servlet (web.xml)
There should already be a web.xml file in the web-inf directory so you do not have to create one. To speed things up you can simply use the file that came with Axis but do not copy all the information, only copy the Listener and Servlet settings. Since we are not using Tomcat, make sure that all the backslashes prefixes are removed.
The first thing that you might find strange when you get ready to create the web service is that you have to add your code to a JWS file and not to a standard Java file. If you look at the above web.xml file you can see that the Axis requests (*.JWS) will be handled by the Axis Servlet. When the web service is first called it will compile the .JWS file into a standard java class file used during runtime.
Axis will take care of converting the Java objects to SOAP data automatically so therefore you really do not need to be concerned with the communication layer. You simply create the methods including the input and output parameters and then Axis converts everything for you.
In this example we used one JWS file. If we did not use Axis then we would have had to create a Session Bean and expose that as a Web Service, however then we would need something that would take the binary data and add that as an attachment. This is where Axis is really helpful; it will take the “DataHandler” information and add that as a MIME attachment to the SOAP response message.
J2EE Enterprise Application Project
Make sure to references the previously created J2EE Web Module Project. Then finally you can deploy the EAR file to the SAP NetWeaver Composition Environment and access the Web Service through the URL.
Interestingly when you type the web service location in the browser URL you will see a page that has a link to the WSDL file. If there were any compilation errors you will see them on the screen at this point. Simply click on the WSDL link to see the detailed SOAP Document.
Test your web service or just use the sample code as a baseline. The web service that you created earlier accepts attachments and then simply responds with the same attachments.
One of the neat additional features of Axis is the TCPMon proxy utility that allows you to observe the SOAP communication traffic in real time. Simply change the URL variable in the client program above and forward TCPMon requests to your server.
When you run the example notice the binary attachment outside the SOAP Envelope included in both the SOAP request and response message.
I often get asked “why is SOAP with attachments important and why do we need to be concerned with this?” The answer lies in the fact that it’s becoming more and more standard practice to send compressed MIME attachments to brokers and public eCommerse sites. Especially if messages are extremely large then it’s quite common to compress the data and add them as attachments to SOAP Messages.