There are two forms of installation with regard to SOAP. The first is running a SOAP client, using the SOAP API to communicate with a server that can receive SOAP messages. The second is running a SOAP server, which can receive messages from a SOAP client. I cover installation of both cases in this section.
To use SOAP on a client, you first need to download Apache SOAP,
available online at http://xml.apache.org/dist/soap.
I've downloaded version 2.2, in the binary format (in the
subdirectory). You should then extract the contents of the archive into a
directory on your machine; my installation is in the
c:\javaxml2 on my Windows machine,
/javaxml2 on my Mac OS X
machine). The result is
/javaxml2/soap-2_2. You'll also need to
download the JavaMail package, available from Sun at http://java.sun.com/products/javamail/.
This is for the SMTP transfer protocol support included in Apache SOAP. Then,
download the JavaBeans Activation Framework (JAF), also from Sun, available
online at http://java.sun.com/products/beans/glasgow/jaf.html.
I'm assuming that you still have Xerces or another XML parser available for
NOTE: Ensure your XML parser is JAXP-compatible and namespace-aware. Your parser, unless it's a very special case, probably meets both of these requirements. If you have problems, go back to using Xerces.
Use a recent version of Xerces; Version 1.4 or greater should suffice. There are a number of issues with SOAP and Xerces 1.3(.1), so I'd avoid that combination like the plague.
There's a lot of talk about running SOAP over other protocols, like SMTP (or even Jabber). This isn't part of the SOAP standard, but it may be added in the future. Don't be surprised if you see it discussed.
Expand both the JavaMail and JAF packages, and then add the
jar files to your classpath, as well as the
library. Each of these
jar files are either in the
root directory or in the
lib/ directory of the relevant installation. At the end, your classpath should look something like this:
$ echo $CLASSPATH
On Windows, it should look like:
Finally, add the
javaxml2/soap-2_2/ directory to your
classpath if you want to run the SOAP samples. I cover setup for specific
examples in this chapter as I get to them.
For building a SOAP-capable set of server components, you first
need a servlet engine. As in earlier chapters, I'll use Apache Tomcat
throughout this chapter for examples, which is available from http://jakarta.apache.org/. You'll then
need to add everything needed on the client to the server's classpath. The
easiest way to do that is to drop
mail.jar, as well as your parser, in your servlet engine's library
directory. On Tomcat, this is simply the
lib/ directory, which contains
libraries that should be autoloaded. If you want to support scripting (which
is not covered in this chapter, but is in the Apache SOAP samples), you'll
also need to put
bsf.jar, available online at http://oss.software.ibm.com/developerworks/projects/bsf,
js.jar, available from http://www.mozilla.org/rhino/, in the
NOTE: If you are using Xerces with Tomcat, you'll need to perform the same renaming trick I talked about in Chapter 10. Rename
z_jaxp.jar, to ensure that
xerces.jarand the included version of JAXP is loaded prior to any other parser or JAXP implementation.
Now restart your servlet engine, and you're ready to write SOAP server components.
The router servlet and admin client
In addition to basic operation, Apache SOAP includes a router servlet as well as an admin client; even if you don't want to use these, I recommend you install them so you can test your SOAP installation. This process is servlet-engine-specific, so I just cover the Tomcat installation here. However, installation instructions for several other servlet engines are available online at http://xml.apache.org/soap/docs/index.html.
Installation under Tomcat is a piece of cake; you simply need to
soap.war file located in the
directory, and drop it in your
$TOMCAT_HOME/webapps directory. That's it! To test
the installation, point your web browser to http://localhost:8080/soap/servlet/rpcrouter. You should get a response like that shown in Figure 12-2.
Although this looks like an error, it does indicate that things are working correctly. You should get the same response pointing your browser to the admin client, at http://localhost:8080/soap/servlet/messagerouter.
As a final test of both the server and client, ensure you have followed all the setup instructions so far. Then execute the following Java class as shown, supplying your servlet URL for the RPC router servlet:
C:\>java org.apache.soap.server.ServiceManagerClient http://localhost:8080/soap/servlet/rpcrouter list Deployed Services:
You should get the empty list of services, as shown here. If you get any other message, consult the long list of possible errors at http://xml.apache.org/soap/docs/trouble/index.html. A fairly complete list of problems that you can run into is there. If you do get the empty list of services, then you're set up and ready to continue with the examples in the rest of this chapter.