Technology Blog

If you are only creating SOAP clients, all you need to do is download the correct suite of files and include the relevant JAR files within your CLASSPATH (details to follow). If, however, you are creating SOAP services, you need the right files plus a Java servlet engine. For example, you can install Apache SOAP to BEA WebLogic Application Server, IBM WebSphere, or Allaire JRun. This section includes specific instructions for installing to the open source Apache Jakarta Tomcat 3.2 server. Tomcat is free, easy to set up, and gets you running in just a few minutes.

*You need a Java servlet engine to set up SOAP services because the Apache SOAP service, called rpcrouter, is really just a Java servlet that has been configured to receive SOAP requests.

Downloading the Required Java Files

To install Apache SOAP to Jakarta Tomcat, you need to download five distribution files. First, download the Tomcat and Apache SOAP distributions:
Apache Jakarta Tomcat: http://jakarta.apache.org/tomcat/
Apache SOAP: http://xml.apache.org/soap/
Then, download the Xerces Java Parser, Java Mail, and JavaBeans Activation Framework distributions:
Xerces Java Parser (Version 1.1.2 or higher): http://xml.apache.org/xerces-j/index.html
Java Mail: http://java.sun.com/products/javamail/
JavaBeans Activation Framework: http://java.sun.com/products/javabeans/glasgow/jaf.html

Setting Up the Tomcat CLASSPATH

Next, you need to set the CLASSPATH for Jakarta Tomcat. Specifically, you must include the following JAR files and directories:
soap.jar
xerces.jar
mail.jar
activation.jar
Directory for your SOAP application class files
To set the Tomcat CLASSPATH, edit the server startup file (on Windows, this file is tomcat.bat; on Unix, it is tomcat.sh). For example, I added the following lines to the section entitled “Set Up the Runtime Classpath” in my tomcat.bat file:
echo Adding xerces.jar to beginning of CLASSPATH

set CP=c:web_serviceslibxerces.jar;%CP%

echo Adding soap.jar to CLASSPATH

set CP=%CP%;C:web_serviceslibsoap.jar

echo Adding mail.jar and activation.jar to CLASSPATH

set CP=%CP%;c:web_serviceslibmail.jar;c:web_serviceslibactivation.jar

echo Adding SOAP Examples Directory

set CP=%CP%;c:web_servicesexamplesclasses
Note that the Tomcat distribution includes its own XML parser, but the built-in parser is not namespace-aware and therefore will not work with Apache SOAP. Hence, you need to force Tomcat to use Xerces (1.1.2 or higher) by prepending xerces.jar to the very beginning of your CLASSPATH. For example:
set CP=c:web_serviceslibxerces.jar;%CP%

Configuring Tomcat

As the final step, you must register the Apache SOAP service with Tomcat. To do so, just add the following lines to the Tomcat configuration file (conf/server.xml):
Make sure to set the correct docBase to reflect your local installation.

Starting Tomcat

You are now ready to start the Tomcat server. On Windows, run the startup.bat file. On Unix, run startup.sh. If you are running Windows, you should see the startup window. By default, Tomcat will start on port 8080, and you should see the text “Starting HttpConnectionHandler on 8080″ within the startup window.

Running the SOAP Administrator

With Tomcat running, you can now access the SOAP Administrator. Open a browser window, and go to http://localhost:8080/soap. If you see the welcome screen in, everything is installed correctly, and you can start deploying your own SOAP services.