Copyright  2001-2007 Nicholas Quaine.
Home   Basics   ServerSide   ClientSide   Demos   FAQ   Resources
ServerSide
1. Overview
2. Deploying Tomcat
3. Deploying SOAP
4. Deploying Services
Packages
Version Details
Sun Java
Tomcat
Apache SOAP
JavaMail
JAF
Xerces

Prev   1    2    3    4    Next
Server-Side SOAP
3. Deploying the SOAP Webapp to Tomcat

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.

STEP FIVE Download and install libraries required by Apache SOAP



  • 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.

STEP SIX Deploy the SOAP Webapp to Tomcat



  • Firstly we need to supply Tomcat with the SOAP webapp modules. To do this on a Win32 system simply copy the soap.war file from C:\soap\soap-2.2\webapps to C:\soap\jakarta-tomcat-3.2.x\webapps. On a UNIX system simply copy the soap.war file from /usr/me/soap/soap-2.2/webapps to /usr/me/soap/jakarta-tomcat-3.2.x/webapps.
  • Next we give Tomcat access to the SOAP and other related jar files. To do this we modify our startup script to look like the following (new lines shown in bold):
    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
      %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
      export CLASSPATH
      $TOMCAT_HOME/bin/startup.bat
    
  • This is an important step : YOU MUST ALTER THE TOMCAT STARTUP BATCHFILE (tomcat.bat on Win32 / tomcat.sh on UNIX). This file is called by startup.bat/sh which is in turn called at the end of your own startup script mystartup.bat/sh to launch Tomcat. We need to alter this script to ensure that the tomcat jar files are postpended rather than prepended to the classpath as setup by you - this is because the xerces xmlparser (xerces.jar) must have precedence over the tomcat xmlparser (parser.jar) for SOAP to work properly. To do simply open up the file C:\soap\jakarta-tomcat-3.2.x\bin\tomcat.bat (on Win32) or /home/me/soap/jakarta-tomcat-3.2.x/bin/tomcat.sh (on UNIX) and change the line as shown below:
    Win32 script : tomcat.bat
    
      .
      .
      .
      :chkClasspath
      if "%CLASSPATH%" == "" goto noClasspath
      set CP=%CP%;%CLASSPATH%
      :noClasspath
      .
      .
      .
    
    change the line shown in bold to the following:
    
      set CP=%CLASSPATH%;%CP%
    
    UNIX script : tomcat.sh
    
      .
      .
      .
      if [ "$oldCP" != "" ]; then
        CLASSPATH=${CLASSPATH}:${oldCP}
      fi
      .
      .
      .
    
    change the line shown in bold to the following:
    
        CLASSPATH=${oldCP}:${CLASSPATH}
    
  • Now simply stop and restart Tomcat for the changes to take effect. When you restart you should see soap reported as one of the configured servlet contexts (aka webapps) as shown in bold below:
      2001-07-04 01:35:14 - ContextManager: Adding context Ctx( /examples )
      2001-07-04 01:35:14 - ContextManager: Adding context Ctx( /admin )
      Starting tomcat. Check logs/tomcat.log for error messages
      2001-07-04 01:35:21 - ContextManager: Adding context Ctx(  )
      2001-07-04 01:35:25 - ContextManager: Adding context Ctx( /test )
      2001-07-04 01:35:29 - ContextManager: Adding context Ctx( /soap )
      2001-07-04 01:35:33 - PoolTcpConnector: Starting HttpConnectionHandler on 8080
      2001-07-04 01:35:33 - PoolTcpConnector: Starting Ajp12ConnectionHandler on 8007
    
  • You can test that the SOAP Webapp is running by pointing a browser to http://localhost:8080/soap/servlet/rpcrouter. You should see a page with the following message. If so then all is fine.

    SOAP RPC Router

    Sorry, I don't speak via HTTP GET- you have to use HTTP POST to talk to me.


STEP SEVEN Deploy one of the demo services



  • 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.

STEP EIGHT Verify that the demo service is operating correctly



  • 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.


You now have the Tomcat application server up and running, the SOAP Webapp deployed and a demo SOAP service in operation. Feel free to go ahead and deploy and test any of the other demo services supplied by the Apache SOAP developers. When you're finished, the following section teaches you how to write and deploy your own services.

[ Nicholas Quaine ]

Next

Copyright 2001-2007 Nicholas Quaine. All rights reserved.