Sayed Y. Hashimi

A step-by-step guide to writing a web service which supports MTOM and a web service client to call it. The example assumes a Windows environment and Eclipse as the development environment.

Setup the Development Environment

1. Download Tomcat version 5.5 from http://tomcat.apache.org/download-55.cgi

2. Set the JAVA_HOME environment variable to the Java JDK directory. Note that you have to set the variable to the JDK and not the JRE install folder.

3. Run startup.bat from the Tomcat distribution bin directory to make sure Tomcat will run. If all is good, run shutdown.bat from the bin directory to stop the Tomcat server.

4. Download Axis2 version 1.3 (http://ws.apache.org/axis2/download/1_3/download.cgi)

a. Download the Standard Distribution and the WAR distribution.

5. Copy the axis2.war file from the WAR distribution in step 4 to the webapps folder under Tomcat. Start Tomcat by running startup.bat. If Tomcat was able to consume the war file, then you should be able to browse to http://localhost:8080/axis2/ to see the Axis2 web application default page.

6. Upon startup, Tomcat unpacked the axis2.war file. Have a look at the axis2.xml configuration file within axis2\WEB-INF\conf\ folder.

7. The axis2.xml file contains the administrator username and password for axis2 administration. By default the username and password to admin and axis2, respectively. You can modify this by changing the values and restarting Tomcat.

8. Point your browser to the axis2 web application and choose the Administration link. http://localhost:8080/axis2/axis2-admin/login. Type in the username and password to access the admin console.

9. So far we have Tomcat and Axis2 up and running. To make this exercise less painful, we should also download TCPMon so we can view the SOAP message we create. Download TCPMon from: http://ws.apache.org/commons/tcpmon/download.cgi. This utility is very cool and easy to use. Before you start TCPMon (by running tcpmon.bat from the build), have a look at the user guide. http://wso2.org/project/wsas/java/2.1/docs/tools/tcpmonguide.html

Create MTOM Enabled Web Service

1. Create a new Java Project in Eclipse. Name the project TestMTOM.

2. Add the axis2 jar files to the classpath. The axis2 jar files are within the lib directory of the axis2 standard distribution.

3. Create a new class named TestService within a package named com.test. Paste the following for the class implementation.

package com.test;

import java.io.File;

import java.io.FileNotFoundException;

import java.io.FileOutputStream;

import java.io.IOException;

import java.io.InputStream;

import java.io.OutputStream;

import javax.activation.DataHandler;

import org.apache.axiom.om.OMElement;

import org.apache.axiom.om.OMText;

public class TestService

{

private static final String OUTPUT_FILE = "C:\\HOLD\\att.pdf";

public void receiveMTOM(OMElement element) throws Exception

{

System.out.println("received request...");

OMText binaryNode = (OMText) (element.getFirstElement()).getFirstOMChild();

binaryNode.setOptimize(true);

DataHandler dh = (DataHandler) binaryNode.getDataHandler();

InputStream is = dh.getInputStream();

byte[] buf = readFully(is);

writeOutput(buf);

System.out.println("done writing output file.");

}

private static void writeOutput(byte[] buf)throws IOException

{

File of = new File(OUTPUT_FILE);

if(of.exists())

{

of.delete();

}

of.createNewFile();

setContents(new File(OUTPUT_FILE),buf);

}

private static void setContents(File aFile, byte[] aContents) throws FileNotFoundException, IOException

{

if (aFile == null)

{

throw new IllegalArgumentException("File should not be null.");

}

if (!aFile.exists())

{

throw new FileNotFoundException("File does not exist: " + aFile);

}

if (!aFile.isFile())

{

throw new IllegalArgumentException("Should not be a directory: " + aFile);

}

if (!aFile.canWrite())

{

throw new IllegalArgumentException("File cannot be written: " + aFile);

}

/**

* declared here only to make visible to finally clause;

* generic reference

OutputStream output = null;

try

{

output = new FileOutputStream(aFile);

output.write(aContents);

}

finally

{

/**

* flush and close both "output" and its underlying FileWriter

if (output != null)

output.close();

}

private static byte[] readFully(InputStream is) throws IOException

{

int size = 10000;

/**

* Offset - how much we've read

int off = 0;

int got;

byte[] ret = new byte[size];

try

{

while (true)

{

got = is.read(ret, off, size - off);

/**

* End of stream

if (got == -1)

break;

off += got;

if (off == size)

{

/**

* If we've read to the end of our buffer,

* enlarge it.

size *= 2;

byte[] tmp = new byte[size];

System.arraycopy(ret, 0, tmp, 0, off);

ret = tmp;

}

finally

{

if(is!=null)is.close();

}

/**

* If we've got a bigger buffer than we need, resize it

if (off != size)

{

byte[] tmp = new byte[off];

System.arraycopy(ret, 0, tmp, 0, off);

ret = tmp;

}

return ret;

}

The receiveMTOM() method expects an OMElement, which then contains the binary file. The method simply pulls the binary file out of the SOAP message and saves it to the local file system. The file is identified by the OUTPUT_FILE static variable. Note that we have to

binaryNode.setOptimize(true);

prior to calling the getDataHandler() method.

4. The service implementation is done. Now we have to create a service.xml file. To do that, first create a folder under the root of the project and name it META-INF. Within this folder, create an xml file and name it services.xml. Paste the following into that file.

This service is to get the running Axis version

</description>

<parameter name="ServiceClass">com.test.TestService</parameter>

</operation>

</service>

To enable MTOM, we have to add a parameter for the service called enableMTOM and set its value to true. Note that MTOM is disabled by default.

5. The next thing we have to do is package the service as a jar file but with a "aar" extension. You can do this several ways, but the easiest approach is to just use Eclipse's Export functionality.

6. Once you have the aar file, copy it under the axis2 deployment within Tomcat. This would be at TOMCAT_INSTALL\webapps\axis2\WEB-INF\services\

7. Restart Tomcat.

Create MTOM enabled Web Service Client

1. Before we can call the service, we need a proxy to the web service. Assuming Tomcat is running, browse to the following URL. http://localhost:8080/axis2/services/TestService?wsdl

2. To create the proxy, save the WSDL file to the bin directory of the Axis2 installation. Name the file TestService.wsdl. Note that within this directory, you'll also have the WSDL2Java.bat file that we need to use to create the web service proxy.

3. After you save the WSDL file, open a command prompt and execute

WSDL2JAVA -uri TestService.wsdl

This should create the proxy files with a folder name src.

4. Now we need to create a java project within Eclipse for the web service client. Create a new Project and name it TestMTOMClient.

5. Add the Axis2 jar files to the classpath.

6. Copy the src folder from step 3 under the TestMTOMClient project and refresh the project in Eclipse.

7. Now create a class to execute the web service. Name the class TestClient and paste the following in its place.

package com.test;

import java.io.File;

import java.io.FileInputStream;

import java.io.IOException;

import java.io.InputStream;

import junit.framework.TestCase;

import org.apache.axiom.om.OMAbstractFactory;

import org.apache.axiom.om.OMElement;

import org.apache.axiom.om.OMFactory;

import org.apache.axiom.om.OMNamespace;

import org.apache.axiom.om.OMText;

import org.apache.axis2.Constants;

import org.apache.axis2.util.~~Base64~~;

import com.test.TestServiceStub.ReceiveMTOM;

public class TestClient extends TestCase

{

private static final String EPR = "http://localhost:9080/axis2/services/TestService";

private static final String INPUT_FILE = "C:\\HOLD\\small.pdf";

public static void main(String[] args) throws Exception

{

}

public void testMTOM()throws Exception

{

TestServiceStub stub = new TestServiceStub(EPR);

stub._getServiceClient().getOptions().setProperty(

Constants.Configuration.ENABLE_MTOM, Constants.VALUE_TRUE);

/**

* set timeout

stub._getServiceClient().getOptions().setTimeOutInMilliSeconds(10000);

String base64String = ~~Base64~~.encode(readFully(INPUT_FILE));

ReceiveMTOM rmtom = new ReceiveMTOM();

OMFactory fac = OMAbstractFactory.getOMFactory();

OMText binaryNode =fac.createOMText(base64String,"application/pdf",true);

OMNamespace omNs = fac.createOMNamespace("http://test.com", "ns0");

OMElement method = fac.createOMElement("receiveMTOM", omNs);

method.addChild(binaryNode);

rmtom.setElement(method);

stub.receiveMTOM(rmtom);

System.out.println("done calling service...");

}

The testMTOM() method creates a stub and sets the enableMTOM property. It then reads the a file and then does a base64 encoded on the file's contents. Finally, it calls the receiveMTOM() metod on the stub. Note that to call the web service, we need a sample file. The class above assumes there is a file named "small.pdf" at c:\hold\. So create a folder named hold in the root of the c:\ drive and copy a pdf file in that directory. Name the file small.pdf.

9. Before you call the service, start TCPMon so we can view the SOAP message that the client sends to the service so you can verify that the SOAP Message is really an MTOM enabled SOAP request. Configurre TCPMon so that the listen port is 9080 and the listener's Target port is 8080. Assuming that Tomcat is running on port 8080. Also realize that the client above is setup to call the service on 9080 so as long as we configure TCPMon correctly we should be okay. If you are not using TCPMon, change the EPR variable in the client class so that it points to port 8080 or whatever port your service is running on.

10. Assuming you did everything correctly, you should be able to send some MTOM SOAP messages to the service. When the service receives a request, it save the binary file to c:\hold\att.pdf.

References

1. Download Tomcat: http://tomcat.apache.org/download-55.cgi

2. Download Axis2 version 1.3: http://ws.apache.org/axis2/download/1_3/download.cgi

3. Download TCPMonitor: http://ws.apache.org/commons/tcpmon/download.cgi

4. Using TCPMonitor: http://wso2.org/project/wsas/java/2.1/docs/tools/tcpmonguide.html

5. A very good article on MTOM with Axis2: http://ws.apache.org/axis2/1_1_1/mtom-guide.html

6. Apache MTOM User Guide: http://ws.apache.org/axis2/1_0/mtom-guide.html

Web Services

11/9/2007 3:22:14 PM (Eastern Standard Time, UTC-05:00)