Dave Cater

Home Page

Career outline

Java

Java references

Java - XML parsing using SAX

Java - XML parsing using DOM

Java - Servlets

Java - SOAP

Linux

Security

Perl

System management

Testing

Musical notes

SOAP is language and operating system independent - I have only looked at implementing services in Java. The HTTP request is processed by a special SOAP router class, which in turn sends the request to the specified service using the Java Servlets scheme. I used the Apache Tomcat servlet engine (see my article on Java Servlets ).

These notes describe how to install SOAP on a client and server system, deploy a simple SOAP service, and write Java client/server code to execute remote procedure calls and display the results returned.

• I followed the Java SOAP tutorial in PC Plus (November 2001). as an introduction. This involved downloading the binary distribution of the SOAP toolkit from the Apache site. The file soap-bin-2.2.tar was downloaded from http://xml.apache.org/soap and unpacked using the tar xvf command.

• To read the documentation I used the following commands:

  	SOAP_HOME=`pwd` export SOAP_HOME
  	cd $SOAP_HOME/soap-2_2/doc
  	netscape `pwd`/index.html
  

• Just to make sure the client environment was set up properly, I started the Tomcat service listening on port 8080, added soap.jar to my CLASSPATH as indicated in the article, and tried to run the command to list SOAP services deployed:

  	java org.apache.soap.server.ServiceManagerClient \
  		http://localhost:8080/soap/servlet/rpcrouter list
  

  Little did I realise how long it would take to get this working properly!

• Java errors indicated that the ServiceManagerClient was not found. I decided to take a closer look at the soap.jar file to see what was there:

  	jar tvf $SOAP_HOME/soap-2_2/lib/soap.jar
  

  This told me that the ServiceManagerClient class is present in the soap toolkit, but must be fully qualified via a prefix:

  	java org.apache.soap.server.ServiceManagerClient \
  		http://localhost:8080/soap/servlet/rpcrouter list
  

• Errors were then reported as I did not have mail.jar or activation.jar in my CLASSPATH. I then started to study the documentation for the SOAP toolkit somewhat more carefully, and found from the Installation pages that I needed both of these and a JAXP-aware XML parser (such as Xerces 1.1.2 or higher). Helpfully, there are links to the sites which supply the missing jar files. Less helpfully, I was fooled into thinking that that my version of Xerces, which was 1.3.1, was adequate. I later found out this was not the case!

  With this done, as expected the ServiceManagerClient class now reported errors (the rpcrouter was not yet installed).

• I then installed the server side components of SOAP in the Tomcat environment:
  • Ensure CLASSPATH contains the aforementioned jar files.
  • Edit the Tomcat startup file to get the XML parser at the start of the CLASSPATH. This was necessary as some Tomcat supplied jar files contain old specifications of the DOM interfaces.
  • Install the SOAP toolkit as a Web application within the servlet environment:

    	cp $SOAP_HOME/soap-2_2/webapps/soap.war $TOMCAT_HOME/webapps
    

    remembering to restart the Tomcat service afterwards.

• This was where the fun really started. I found I was receiving errors not mentioned in the otherwise excellent "Troubleshooting" section of the Installation pages, saying "Unable to resolve namespace URI for 'ns2'."

  Eventually after many fruitless attempts to narrow down the source of the problem I found the answer on the Apache SOAP FAQ list . I was using a version of Xerces with a known incompatibility. I downloaded version 1.3.0 instead of 1.3.1 (see my article on XML Parsing ). With this installed, added to my CLASSPATH, and Tomcat restarted, at long last the ServiceManagerClient class received a reply to its RPC which showed an (empty) list of deployed SOAP services.

• I was now able to install a deployment descriptor from the article:

      java org.apache.soap.server.ServiceManagerClient \
          http://localhost:8080/soap/servlet/rpcrouter deploy hello_dd.xml
  

  This uses an XML format to specify the methods implemented for a particular service, and the class containing the methods (as the service is implemented in Java). An XML namespace (known as the urn) is created with the name of the service specified.

  The XML format used for this study was specific to Apache SOAP implementation - an emerging standard for deployment descriptors is the Web Services Description Language (WDSL).

• A valuable side effect of the investigations to resolve the installation problems was the new tools and documenatation which I came across.

  In the User's Guide, under Tools, I came across the Tunnel GUI. This is a TCP/IP tunnel/monitor which displays two windows containing the XML messages sent by the client and server respectively.

  This can be started as follows:

  	java org.apache.soap.util.net.TcpTunnelGui 8081 localhost.localdomain 8080
  

  assuming the Tomcat service is running on port 8080 on the local host.

• After all this, I was understandably eager to create my own SOAP service to do something (anything).

  I created a client class called Hello (what else) with a main method containing the sample code from the PC Plus article to send a SOAP message to the port on which the Tunnel GUI listens. By guesswork, inspiration, referring to documentation and examining various jar files, I found the following packages need to be imported, to define the classes containing the methods to which the sample code refers:

  import java.io.IOException;
  import java.io.PrintWriter;
   
  import java.net.*;
   
  import java.util.*;
   
  import org.apache.soap.*;
  import org.apache.soap.rpc.*;    
  

• I then wrote a class called HelloServer following the sample in the article.

  I later found I needed to specify the package this class resides in, to match the class specified in the Apache deployment descriptor:

  package com.pcplus.soap.hello;    
  

  and as a consequence, I had to copy the file HelloServer.class to a subdirectory of my Java class directory (com/pcplus/soap/hello). Java uses the current directory to find classes in the default (unnamed) package, but where a package statement is used, classes must be in a subdirectory as shown.

  I also restarted Tomcat with my Java class directory added into CLASSPATH.

• Finally I sent a message from my test client to the server and received a response:

  java Hello
  

  Beguilingly simple after all that went before.

• I also used the SOAP admin pages

  http://localhost:8080/soap/admin/index.html
  

  mentioned in the PC Plus article, and found they provide a simple browser interface to manage the deployment of SOAP services.