Using SOAP with Tomcat

02/27/2002

The Apache SOAP Project is an open source Java implementation of the Simple Object Access Protocol (SOAP) v1.1. SOAP is a wire protocol that leverages HTTP or SMTP as its transport layer and XML as its data layer, to execute remote methods, known as SOAP services.

The Apache implementation of SOAP provides two methods for invoking SOAP services: a Remote Procedure Call (RPC) model and a message-based model. The RPC method, which is the focus of this article, is a synchronous technique using a client-server model to execute remote SOAP services. The message-based model uses SMTP to transport SOAP documents to and from the appropriate SOAP server. While this method is interesting, it is out of the scope of this article.

The RPC model can be defined using the following steps:

1. A client application builds an XML document containing the URI of the server that will service the request, the name of the remote method to execute, and the parameters associated with that method.
2. The targeted server receives and unwinds the XML document. It then executes the named method.
3. After the named method has returned its results, the results are packed into a response XML document, which is sent back to the calling client.
4. The client application receives the response and unwinds the results, which contains the response of the invocated method.

Integrating Apache SOAP into Tomcat

Before we begin using the Apache SOAP project, we must acquire the necessary components to execute SOAP services. Listing 1 provides a list of these items and where they can be found.

Listing 1. Components required to execute SOAP clients and services

SOAP v2.2 (soap.jar)

http://xml.apache.org/soap/index.html

mail.jar v1.2

This .jar file is packaged with Tomcat in the <TOMCAT_HOME>/common/lib/ directory.

activation.jar v1.0.1

This .jar file is packaged with Tomcat in the <TOMCAT_HOME>/common/lib/ directory.

xerces.jar v1.4.2

This .jar file is packaged with Tomcat in the <TOMCAT_HOME>/common/lib/ directory.

Once we have all of these items, we need to extract the SOAP archive to a local directory. We then need to add each of the previously mentioned .jar files to your classpath, including soap.jar, which comes packaged with the SOAP archive. This step is very important and must not be ignored.

Deploying Apache-SOAP using Tomcat

There are several ways to deploy a SOAP project to Tomcat. Of these methods, we are going to perform the easiest, which is simply to copy the soap.war file to the <TOMCAT_HOME>/webapps/ directory. You can find this file in the SOAP 2.2 archive.

Related Reading Programming Web Services with SOAP By James Snell, Doug Tidwell, Pavel Kulchenko

Once you have moved the soap.war file into <TOMCAT_HOME>/webapps/directory, you need to make sure that each of the previously listed .jar files are in the <TOMCAT_HOME>/common/lib/ directory, excluding the soap.jar file.

After you have copied the above files to the named locations, restart Tomcat. You should now be able to access the SOAP Web application by opening your Web browser to http://localhost:8080/soap/

You should see a page similar to Figure 1.

At this point, you should also be able to use the SOAP admin tool, which can be accessed by selecting the Run link. Figure 2 shows the home page for the SOAP admin tool. From this page, you can list the current services, deploy new services, and remove previously-deployed services.

Creating a Sample SOAP Application

Now let's develop a simple SOAP application that acts as a simple integer calculator, with only addition and subtraction functions. To do this, we need to first develop a SOAP service for handling our calculator functions, and then create a client to access the service.

SOAP Services

Writing an RPC-based SOAP service is a very simple process that can be broken down into three steps.

• Create the Java class that contains the SOAP service to publish.
• Create a deployment descriptor that describes the service.
• Publish the service.

Creating a SOAP Service

Creating a SOAP service is the simplest step of the entire "SOAPifying" process. A SOAP service can be just about any Java class that exposes public methods for invocation. The class does not need to know anything about SOAP, or even that it is being executed as a SOAP service.

The only restriction is that the method parameters of a SOAP service must be serializable. The available types that can, by default, be used as SOAP service parameters are shown in Listing 2.

Listing 2. Types that can be used as SOAP service parameters.

• All Java primitive types and their corresponding wrapper classes
• Java arrays
• java.lang.String
• java.util.Date
• java.util.GregorianCalendar
• java.util.Vector
• java.util.Hashtable
• java.util.Map
• java.math.BigDecimal
• javax.mail.internet.MimeBodyPart
• java.io.InputStream
• javax.activation.DataSource
• javax.activation.DataHandler
• org.apache.soap.util.xml.QName
• org.apache.soap.rpc.Parameter
• java.lang.Object (must be a JavaBean)

The source listing for our service, a simple adding and subtracting calculator, is shown in its entirety in Example 1.

Example 1. Simple calculator service

package onjava;
public class CalcService {
  public int add(int p1, int p2) {
  
    return p1 + p2;
  }

  public int subtract(int p1, int p2) {

    return p1 - p2;
  }
}

As you can see, there is really nothing special about this class. It simply defines two public methods, add() and subtract(), each with a parameter list containing two native ints. To make this class available, build and copy it into the <TOMCAT_HOME>/webapps/soap/WEB-INF/classes/onjava/ directory.

Pages: 1, 2, 3

Next Page