Clean up your wire protocol with SOAP, Part 2

Use Apache SOAP to create SOAP-based applications

By Tarak Modi, JavaWorld.com, 04/27/01

SOAP (Simple Object Access Protocol) is a wire protocol that uses XML for data encoding. It is a minimalist specification of sorts; it only defines the most critical pieces required by a wire protocol, and purposefully omits the details of garbage collection, object activation, and so forth.

SOAP is especially important for Java developers because it adds to Java's value proposition by making platform independence and portability more interoperable. In fact, I would not be surprised if future releases of Java 2 Platform, Enterprise Edition (J2EE) make SOAP one of the mandatory wire protocols that all J2EE-compliant application servers must support. But that's enough speculation for now.

In Part 2 of this four-part series, I will introduce you to Apache's SOAP implementation.

Read the whole series on SOAP:

Introducing Apache SOAP

Apache SOAP, the Apache Software Foundation's implementation of the SOAP specification, is based on IBM's SOAP4J. Like all Apache projects, Apache SOAP is open source and available under the Apache license. I think it is currently one of the best implementations of SOAP. Though Apache SOAP conforms to version 1.1 of the SOAP specification, it lacks support for some features included in SOAP 1.1. (See Resources for a list of Apache SOAP'S available features.)

Download and install Apache SOAP

As I mentioned above, you can download Apache SOAP free of charge. (See Resources for a link.) For my Windows NT laptop, I downloaded the file soap-bin-2.0.zip, which contains Apache SOAP 2.0, the latest version as of this writing. Installing Apache SOAP is a breeze. It consists of three easy steps:

Unzip the downloaded zip file: This results in the creation of a soap-2_0 subdirectory. I unzipped the contents into the root directory of my E drive, so I now have a directory E:\soap-2_0 that contains Apache SOAP.
Set up your Web environment: You will need a Web server that supports servlets and JavaServer Pages (JSPs). At this point, you will fall into one the following two categories:
- Category 1: You already have a Web server that supports servlets and JSPs, and you feel comfortable configuring it. In this case, set up your Web server so that you can point your browser to http://localhost:8080/apache-soap/. The browser will access the index.html file in the directory soap-2_0 \webapps\soap\.
- Category 2: You don't have a Web server that supports servlets and JSPs, or you have one but don't want to fool around with it. In this case, I suggest downloading the latest version of Tomcat (3.1 at the time of this writing). (See Resources for a link.) Tomcat is yet another example of the excellent software that Apache creates and makes available for free to the software development community. Once you've downloaded the appropriate zip file (jakarta-tomcat-3.1.1.zip), unzip it. A jakarta-tomcat subdirectory will be created. Once again, I've unzipped the contents into the root directory of my E drive. Add a new context to the jakarta-tomcat\conf\server.xml configuration file like this:
```
<Context path="/apache-soap" docBase="E:/soap-2_0/webapps/soap"
         debug="1" reloadable="true">
</Context>
```
  You will need to replace E: in the docBase attribute of the Context element with the location of your soap-2_0 directory. To start Tomcat, execute the startup.bat (startup.sh for Unix) file. To shut it down, execute the shutdown.bat (shutdown.sh for Unix) file. But wait -- don't start Tomcat just yet.
Set up your Web server classpath: Apache SOAP requires Apache Xerces (Java) version 1.1.2 or higher, which supports the DOM (Document Object Model) level 2 candidate recommendation that provides namespace support. I use version 1.2 of Xerces, available from Apache as Xerces-J-bin.1.2.0.zip. Unzipping this file will result in the creation of a xerces-1_2_0 subdirectory. As before, I've unzipped the file into the root directory of my E drive. You must configure your Web server to use xerces.jar (which is in the xerces-1_2_0 subdirectory) -- as opposed to any native library/jar that came with your server -- for all XML parsing. For example, Tomcat comes with an XML parser (jakarta-tomcat\lib\xml.jar) that has the DOM level 1 interfaces. Even if you put the xerces.jar in your classpath, any Java code running in Tomcat will find the wrong interfaces because the shell script/batch file that you use to run Tomcat places your classpath at the end. So you must edit tomcat.bat (tomcat.sh for Unix) in the jakarta-tomcat\bin\directory and put xerces.jar at the front of the classpath that the script builds. That is what I did in my jakarta-tomcat\bin\tomcat.bat file:
```
set CLASSPATH=E:\xerces-1_2_0\xerces.jar;%CLASSPATH%;%cp%
```
If you fall in Step 2's Category 2, then you must also configure your server to use xerces.jar.

Regardless of which category you fall into, in addition to xerces.jar, you must also set your Web server's classpath to use soap.jar from the soap-2_0\lib\ subdirectory.

Test your installation

Now, start your Web server and make sure that your installation is correct by pointing your browser to http://localhost:8080/apache-soap/admin. You should see an administration screen as shown in the figure below.

Apache SOAP administration tool

The HelloWorld example

Now that you have set up Apache SOAP, let's put it to use with a simple HelloWorld application. In SOAP lingo, applications are called services. Typically, services are created in two steps, which may or may not be performed by the same person/organization. The first step is to define and implement the service itself in the language of choice: in this case, Java. The second step is to create clients that actually need and invoke the service. Let's look at the HelloWorld service first.

The HelloWorld service

The HelloWorld service is the Apache SOAP implementation of the example I discussed in Part 1. The service expects to obtain a person/user's name and returns a customized hello message to the caller. The code below shows the complete implementation of the HelloWorld service:

package hello;
public class HelloServer 
{
   public String sayHelloTo(String name)
   {
      System.out.println("sayHelloTo(String name)");
      return "Hello " + name + ", How are you doing?";       
   }    
}

Is that all? That is too simple to be true!

Apache SOAP makes creating services extremely easy. Basically, a service consists of the business logic, which is code that you would write regardless of how you made the service available to the rest of the world. In other words, the service is not tainted by any SOAP-related code, because the Apache SOAP infrastructure -- which consists of the rpcrouter servlet and soap.jar -- handles all the intricacies for you. Let's talk briefly about those intricacies. Just how does Apache SOAP handle remote procedure call (RPC) requests over HTTP? Understanding that will ease the creation of clients (yes, clients).

The org.apache.soap.rpc package provides support for performing RPC over SOAP in Apache SOAP. The central concept behind Apache SOAP's RPC support is that of an object ID. All Apache SOAP services must have a unique ID that acts as the service's object ID. As always, uniqueness is relative; in Apache SOAP, the uniqueness of these object IDs is related to the Apache SOAP server on which a service is deployed. That is, two services deployed on different Apache SOAP servers might have the same object ID.

A client interested in using a service sets up an org.apache.soap.rpc.Call object with the desired service's object ID, the name of the method to be invoked, and the parameters (if any) for that method. Once the Call object is set up, the client calls its invoke() method, which takes two parameters. The first is a URL to the rpcrouter servlet; in this case, the URL is http://localhost:8080/apache-soap/servlet/rpcrouter. The second parameter is the SOAPAction header. Refer to Part 1 for a refresher on the importance of the SOAPAction header and its possible values.

The invoke() method converts the Call object into an XML SOAP request (which is similar to the examples in Part 1) and sends that request to the rpcrouter servlet, as indicated by the URL. When the servlet returns a response, the invoke() method returns an org.apache.soap.rpc.Response object, which contains the service response (if any) or the fault (if a fault was generated). HTTP dictates that every request must have a response; so even if the service itself does not return anything, the rpcrouter servlet always does. Hence, the invoke() method will always return a Response object.

On the service side, the Apache SOAP server -- that is, the rpcrouter servlet -- receives the POSTed SOAP request from the client and rebuilds a Call object. The servlet uses the object ID from the rebuilt Call object to locate the object in the service manager.

The servlet then verifies the method name and invokes it on the located object. The servlet also serializes the return value from this call and sends it back in the HTTP response.

1 | 2 | 3 | 4 | Next >