Steps four to eight cover the deployment the Apache SOAP Webapp to Tomcat (the SOAP webapp contains the SOAP Servlet and some JSP-based admin pages which we will see soon). These instructions are applicable to both Win32 and UNIX operating systems - take care to follow the instructions appropriate to your operating system in sections where differences exist.

STEP FOUR

Download and install Apache SOAP

• Go to http://xml.apache.org/soap/index.html and download the Apache SOAP for Java package (choose Download then version-2.2 and choose "soap-bin-2.2.zip" for Win32 or "soap-bin-2.2.tar.gz" for UNIX and save it to your machine).
• Unpack to the soap directory. Everything will be contained in a subdirectory named soap-2_2. Ensure that within soap-2_2 there is a lib directory that contains a file called soap.jar - this is the all important soap package.

• Apache SOAP for Java requires the JavaMail API which is in turn dependent upon the Java Activation Framework (JAF). Apache SOAP also requires XML parser package Xerces so we need to download and install that as well. Instructions follow.
• Go to http://java.sun.com/products/javamail (this is the javamail homepage), in the section entitled "Download JavaMail API Implementation" choose CONTINUE, read and ACCEPT the agreement (if you are happy with the terms) then choose the appropriate site for FTP download. Save the zipfile to your machine. Unpack it to the soap directory. Everything will be contained in a subdirectory called javamail-1.2. Ensure that in javamail-1.2 there is a file called mail.jar - this is the JavaMail package that we will make available to the SOAP package.
• Go to http://java.sun.com/products/javabeans/glasgow/jaf.html (this is the JAF homepage), choose CONTINUE to get to the download section, read and ACCEPT the agreement (if you are happy with the terms) then choose the appropriate site for FTP download. Save the zipfile to your machine. Unpack it to the soap directory. Everything will be contained in a subdirectory called jaf-1.0.1. Ensure that in jaf-1.0.1 there is a file called activation.jar - this is the JAF package that we will make available to the JavaMail package.
• Go to http://xml.apache.org/index.html and download the Xerces-J package (choose Downloads then xerces-j/ then old_xerces1/ and choose "Xerces-J-bin.1.2.3.zip" for Win32 or "Xerces-J-bin.1.2.3.tar.gz" for UNIX and save it to your machine). Unpack it to the soap directory. Everything will be contained in a subdirectory called xerces-1_2_3. Ensure that in xerces-1_2_3 there is a file called xerces.jar - this is the Xerces package that we will make available to the SOAP package.

  Warning : Do not choose a later version of Xerces-J. In particular, version 1.3.1 will cause problems due to incompatibility with the Apache SOAP package.

• Apache SOAP comes with several demo services which you can deploy. We will do this to ensure that everything is operating correctly before writing and deploying our own services. A couple of points of clarification though before we get started. Firstly, Why do we sometimes say service and other times say service method? Well, when speaking casually it is easy (and acceptable) enough to call a service method a service but from the point of view of an Apache-based SOAP server deployer such as yourself they are different. A service method is the Web Services version of a function (or method in java). Whereas a service is actually a group of one or more related methods. We'll see the difference quite clearly further down this page when we deploy the demo service urn:AddressFetcher. Secondly, What do we mean when we say "deploy a service"? In the simplest terms this means declaring a service method to the SOAP servlet such that it can reference it later on when the service is called. In other words the SOAP servlet can only invoke service methods that it knows about and service deployment is how we let it know. Luckily, when we deploy a service, a certain file (called DeployedServices.ds) will be updated with the specifics of the service and this file is read by the SOAP Servlet at initialisation, so we do not have to redeploy each time we restart Tomcat. If you want to see this file you will be able to find it on Win32 systems in the directory C:\soap\jakarta-tomcat-3.2.x\webapps\soap or on UNIX systems in the directory /home/me/soap/jakarta-tomcat-3.2.x/webapps/soap - but only once you have deployed a service.
• The first thing to learn about service deployment is that there are two ways to do it:
  1. The manual (tedious) way where we fill out a web page and submit it. The web page is a part of the SOAP Webapp and is available via http://localhost:8080/soap/admin/index.html. From this page you can list, deploy and undeploy your services (if you choose "List" you should get a message saying that there are no services currently deployed). Following the choice "Deploy" you can see the web page where you can describe a service to the SOAP servlet. This works fine but the problem is that you will have to redo it each time you modify a service or create a new SOAP server. It is fairly obvious that this is not desirable - you want a more rigorous approach when rolling out your SOAP server to production for example.
  2. The second (better) way is to script the deployment. For this purpose the Apache SOAP developers have given us a java utility (java org.apache.soap.server.ServiceManagerClient) which takes as parameters the SOAP Servlet URL and an XML file describing the service (note that the XML file can actually contain more than just a single service method). These XML files are called Deployment Descriptors. The demo service that we will deploy is the addressbook example and can be found in C:\soap\soap-2_2\samples\addressbook (on Win32) or /home/me/soap/soap-2_2/samples/addressbook (on UNIX). In that directory you will find the relevant Deployment Descriptor(filename DeploymentDescriptor.xml).
• We will implement the second method. Create another script to run the actual deployment (call it mydeployer.bat on Win32, mydeployer.sh on UNIX) like the following. Note that for the Win32 script we put a pause at the end so that we can see any error messages that occur. Note that the arrow ( ) is used to indicate where a line is a continuation of the preceeding one but we had to split it just for display purposes.

  Win32 script : mydeployer.bat

  set JAVA_HOME=C:\jdk1.3.1 set CLASSPATH=C:\soap\soap-2_2\lib\soap.jar set CLASSPATH=%CLASSPATH%;C:\soap\javamail-1.2\mail.jar set CLASSPATH=%CLASSPATH%;C:\soap\jaf-1.0.1\activation.jar set CLASSPATH=%CLASSPATH%;C:\soap\xerces-1_2_3\xerces.jar java org.apache.soap.server.ServiceManagerClient http://localhost:8080/soap/servlet/rpcrouter deploy %1 pause

  UNIX script : mydeployer.sh

  #!/bin/sh JAVA_HOME=/usr/java export JAVA_HOME CLASSPATH=/home/me/soap/soap-2_2/lib/soap.jar CLASSPATH=${CLASSPATH}:/home/me/soap/javamail-1.2/mail.jar CLASSPATH=${CLASSPATH}:/home/me/soap/jaf-1.0.1/activation.jar CLASSPATH=${CLASSPATH}:/home/me/soap/xerces-1_2_3/xerces.jar export CLASSPATH java org.apache.soap.server.ServiceManagerClient http://localhost:8080/soap/servlet/rpcrouter deploy $1

• We have to give Tomcat access to the sample classes. To do this add the following line (in bold) to mystartup.bat:

  Win32 script : mystartup.bat

  set JAVA_HOME=C:\jdk1.3.1 set TOMCAT_HOME=C:\soap\jakarta-tomcat-3.2.x set CLASSPATH=C:\soap\soap-2_2\lib\soap.jar set CLASSPATH=%CLASSPATH%;C:\soap\javamail-1.2\mail.jar set CLASSPATH=%CLASSPATH%;C:\soap\jaf-1.0.1\activation.jar set CLASSPATH=%CLASSPATH%;C:\soap\xerces-1_2_3\xerces.jar set CLASSPATH=%CLASSPATH%;C:\soap\soap-2_2 %TOMCAT_HOME%\bin\startup.bat

  UNIX script : mystartup.sh

  #!/bin/sh JAVA_HOME=/usr/java export JAVA_HOME TOMCAT_HOME=/home/me/soap/jakarta-tomcat-3.2.x export TOMCAT_HOME CLASSPATH=/home/me/soap/soap-2_2/lib/soap.jar CLASSPATH=${CLASSPATH}:/home/me/soap/javamail-1.2/mail.jar CLASSPATH=${CLASSPATH}:/home/me/soap/jaf-1.0.1/activation.jar CLASSPATH=${CLASSPATH}:/home/me/soap/xerces-1_2_3/xerces.jar CLASSPATH=${CLASSPATH}:/home/me/soap/soap-2_2 export CLASSPATH $TOMCAT_HOME/bin/startup.bat

• Stop and restart Tomcat so it can take into account the new classpath.
• Once Tomcat has completed its startup run the deployer script, giving the Deployment Descriptor filename as a parameter, like this:

    Win32
    > mydeployer.bat C:\soap\soap-2_2\samples\addressbook\DeploymentDescriptor.xml
  

    UNIX
    > mydeployer.sh /home/me/soap/soap-2_2/samples/addressbook/DeploymentDescriptor.xml
  

• One very common error reported at this point is this:

    Exception in thread "main" java.lang.NoClassDefFoundError: org/w3c/dom/Node
  

  This error occurs if you do not have xerces before all other XML parsers in your classpath or you have an incompatible version of xerces (1.3.1 for example). If you get this error check that you have correctly modified tomcat.bat as shown above and that you have the correct version of xerces as specified above.
• If there was no error it means the service was deployed successfully. You can now see it listed as urn:AddressFetcher on the SOAP admin page http://localhost:8080/soap/admin/index.html. Click on it to see the deployment details you would otherwise have had to enter by hand. Notice that there were actually four service methods deployed (getAddressFromName, addEntry, getAllListings and putListings) and that these are all grouped under one service or URN (Uniform Resource Name) called urn:AddressFetcher. You can think of this URN as a way of grouping related service methods under a single service umbrella. The important thing to note here is that all the service methods in a service are implemented by the same provider class.

• Time to test the service. You will of course need some kind of SOAP client which understands how to formulate a SOAP request and understand the SOAP response provided by the server before you can consume the service that you have just deployed. Luckily the Apache SOAP developers have supplied just such a client (written in Java and exploiting the Apache SOAP for Java package - the same package that we have used on the server-side). Once again we will write a little script to run the client. Let's call it getaddress.bat on Win32 / getaddress.sh on UNIX as it will call the getAddressFromName service method. It looks like the following (note that in the Win32 script we again put a pause at the end, this time to see the result of the service call):

  Win32 script : getaddress.bat

  set CLASSPATH=C:\soap\soap-2_2\lib\soap.jar set CLASSPATH=%CLASSPATH%;C:\soap\javamail-1.2\mail.jar set CLASSPATH=%CLASSPATH%;C:\soap\jaf-1.0.1\activation.jar set CLASSPATH=%CLASSPATH%;C:\soap\xerces-1_2_3\xerces.jar set CLASSPATH=%CLASSPATH%;C:\soap\soap-2_2 java samples.addressbook.GetAddress http://localhost:8080/soap/servlet/rpcrouter "John B. Good" pause

  UNIX script : getaddress.sh

  #!/bin/sh CLASSPATH=/home/me/soap/soap-2_2/lib/soap.jar CLASSPATH=${CLASSPATH}:/home/me/soap/javamail-1.2/mail.jar CLASSPATH=${CLASSPATH}:/home/me/soap/jaf-1.0.1/activation.jar CLASSPATH=${CLASSPATH}:/home/me/soap/xerces-1_2_3/xerces.jar CLASSPATH=${CLASSPATH}:/home/me/soap/soap-2_2 export CLASSPATH java samples.addressbook.GetAddress http://localhost:8080/soap/servlet/rpcrouter "John B. Good"

  Run the script. You should see the following output:

    123 Main Street
    Anytown, NY 12345
    (123) 456-7890
  

• Now that your service is up and running you may want to see the SOAP dialogue that is going on between the SOAP client and server. Again, the Apache SOAP developers have provided you with a utility to do this. It is called the TcpTunnelGui and is included in the soap.jar package. The idea is that you startup the tunnel, it listens on a certain port for TCP/IP requests, displays them on the screen and then forwards them to the port that handles the request. When it receives the response it posts that on the screen as well before forwarding the response to the client. We'll start it to listen to port 5555 and then change our client process to make requests on that port instead of 8080. The following script starts up the tunnel:

  Win32 script : tunnel.bat

  set CLASSPATH=C:\soap\soap-2_2\lib\soap.jar java org.apache.soap.util.net.TcpTunnelGui 5555 localhost 8080

  UNIX script : tunnel.sh

  #!/bin/sh CLASSPATH=/home/me/soap/soap-2_2/lib/soap.jar export CLASSPATH java org.apache.soap.util.net.TcpTunnelGui 5555 localhost 8080

  Then all you need to do is change your client (getaddress.bat) to send requests to port 5555 instead of 8080 like this:

  Win32 script : getaddress.bat

  set CLASSPATH=C:\soap\soap-2_2\lib\soap.jar set CLASSPATH=%CLASSPATH%;C:\soap\javamail-1.2\mail.jar set CLASSPATH=%CLASSPATH%;C:\soap\jaf-1.0.1\activation.jar set CLASSPATH=%CLASSPATH%;C:\soap\xerces-1_2_3\xerces.jar set CLASSPATH=%CLASSPATH%;C:\soap\soap-2_2 java samples.addressbook.GetAddress http://localhost:5555/soap/servlet/rpcrouter "John B. Good" pause

  UNIX script : getaddress.sh

  #!/bin/sh CLASSPATH=/home/me/soap/soap-2_2/lib/soap.jar CLASSPATH=${CLASSPATH}:/home/me/soap/javamail-1.2/mail.jar CLASSPATH=${CLASSPATH}:/home/me/soap/jaf-1.0.1/activation.jar CLASSPATH=${CLASSPATH}:/home/me/soap/xerces-1_2_3/xerces.jar CLASSPATH=${CLASSPATH}:/home/me/soap/soap-2_2 export CLASSPATH java samples.addressbook.GetAddress http://localhost:5555/soap/servlet/rpcrouter "John B. Good"

  Startup the tunnel by running tunnel.bat/sh then run getaddress.bat/sh to call the service. You should see the SOAP dialogue appear on the Tunnel's GUI - one pane will show all requests made to port 5555. The other will show the responses.