Chapter 7: Web Services with Apache SOAP

Prerequisites for Using Apache SOAP

There are several libraries and software components to install. The first piece to install is the Apache Group’s Java container, Tomcat, which allows you to host the SOAP server in addition to servlets and JSPs. The next step after Tomcat involves installing all the necessary libraries including SOAP, JavaMail™, and others. Once the libraries are installed, the CLASSPATH environment variable needs to be installed correctly. For more information on where to download the various libraries and Tomcat, see Appendix B.

Installing Tomcat

On the Apache Group’s Web site at http://www.apache.org, find the file named jakarta-tomcat-3.2.4.zip and unpack it to a directory on your system. This is a slightly older version of Tomcat, but it tends to be more stable and easier to work with. You should create a root directory for all the Apache software used in this chapter, and then install Tomcat under this directory. For example, on the author’s machine all software used in this chapter is found under C:\xmlapache. This puts all the software close together and makes it easier to set CLASSPATH and other environmental variables.

Once Tomcat is extracted, you may want to change the name of the directory from c:\xmlapache\jakarta-tomcat-3-2-4 to c:xmlapache\tomcat.

This will save you some headache as you move forward in the chapter.

Tip

In this chapter, Tomcat is used as a Web server and Java container. In a real production environment you need to use the Apache Webserver as your Web server. Apache directs calls when needed to Tomcat and is far more configurable. This gives your Web application and Web Services more options for security and redirects.

If you don’t already have Java installed on your system, download it from www.javasoft.com and then install it on your system. The examples in this chapter use Version 1.4.0 of the Java Development Kit (JDK).

Installing SOAP and Other Libraries

Now that Java is installed and Tomcat extracted, there are several other files you need to download. Appendix B describes the download files, the URL to download them from, and the recommended installation locations.

Tip

There are versions of the Apache Group’s XML parser Xerces that are newer than Version 1.4.4, but don’t use them with this version of the Apache SOAP library. Otherwise you will receive various strange errors without much explanation from Tomcat and any client you compile.

Once you have extracted all the zip files into the appropriate location for your system, you need to place the soap.war file into Tomcat’s webapps directory (e.g., webapps may have the following path): c:\xmlapache\tomcat\webapps). This is essentially a zip file that Tomcat extracts properly when it executes. This installs all the servlets and other code needed for the Apache SOAP library to execute.

Setting up the CLASSPATH

Now that all the libraries are installed on your machine, you need to tell Java where to find them. This is done by setting up the CLASSPATH environment variable correctly. Creating an MS-DOS batch file is one way to simplify the process. Using a batch file prevents your environment from becoming too polluted because you only set the environment variables that you are using at any particular time. Consider the following example bat file and remember that these examples assume you installed your Apache files in c:\xmlapache. Realize that the line breaks are put here to make it easier to read the code.

    set PATH=%PATH%;c:\jdk1.4.0\bin;.     set JAVA_HOME=c:\jdk1.4.0     set CLASSPATH=c:\xmlapache\javamail\mail.jar;                   c:\xmlapache\jaf\activation.jar;                   c:\xmlapache\soap;                   c:\xmlapache\soap\lib\soap.jar;                   c:\xmlapache\tomcat\lib\servlet.jar;                   %CLASSPATH%;

On the CD This batch file can be found on this book’s CD-ROM in the code for this chapter and it’s called env.bat. This batch file not only sets up the CLASSPATH but also the PATH so that we can execute Java and Javac, and JAVA_HOME is set in order for Tomcat to find the Java root directory.

When the CLASSPATH is set, note that it calls the Java Archive Files (JAR) that you expected but it also includes servlet.jar in the Tomcat directory structure. The SOAP library needs this to execute the servlets that come with the distribution.Examples later in this chapter also utilize servlets.

Finally, to get Tomcat to load the correct XML parser for SOAP, you need to change one of the lines in its startup script. Load the startup.bat batch file into a text editor and change the line that sets the CP environment variable (this is the CLASSPATH for Tomcat) to look like the following.

     set CP=path-to-xerces\xerces.jar;%CLASSPATH%;%CP% 

Testing the Installation of Apache SOAP

To begin testing the Apache SOAP installation, start Tomcat with the startup script found in its bin directory. Make sure you use the env.bat script to set up the environment at a DOS prompt and then change into Tomcat’s bin directory to start the container.

To test your installation, point your browser to the following URL: http://localhost:8080/soap/. You should see what’s shown in Figure 7.1.

Figure 7.1: The appropriate response to a browser after installing the Apache SOAP library.

This means that Tomcat successfully extracted the SOAP war file. Click on the link for the “Admin” tool and you should see what appears in Figure 7.2.

Figure 7.2: How the SOAP “Admin” tool appears in Internet Explorer.

If you visit the SOAP RPC router, it doesn’t really respond to the browser but the results still look like Figure 7.3.

Figure 7.3: The SOAP RPC router in Internet Explorer.

These different Web pages primarily show that the war file installed properly but do not test the functionality. The SOAP distribution comes with several examples that can help you test the installation. In c:\xmlapache\soap\samples you will find a MSDOS batch file named testit.cmd. This will install, test, remove a Web Service that returns the value of IBM’s stock price, and then exit. If it works properly you see the results in a DOS prompt similar to Figure 7.4.

Figure 7.4: The results of running testit.cmd in the Stock Quote sample directory of Apache SOAP.

If you receive an error like the following when you execute testit.cmd, the CLASSPATH for Tomcat is not set up properly.

    java org.apache.soap.server.ServiceManagerC     client http://localhost:8080/soap/servlet/rpcrouter list     Exception in thread "main" [SOAPException:     faultCode=SOAP-ENV:Protocol; msg=Unsupported     response content type "text/html", must be:     "text/xml". Response was:     <h1>Error: 500</h1>     <h2>Location:     /soap/servlet/rpcrouter</h2><b>Internal     ServletError:</b><br><pre>     java.lang.NoClassDefFoundError: javax/mail/ 

Now that you’ve seen how to test Apache SOAP, the next sections describe how to create Apache SOAP Web Services and their consumers.