Using SOAP with Tomcat
Pages: 1, 2, 3

Creating the Deployment Descriptor

The next step in creating a new SOAP service is to create a deployment descriptor. The deployment descriptor describes the SOAP service. This description is required for the service to be published as an Apache SOAP service. The deployment descriptor for our service is contained in Example 2.

Example 2. Deployment descriptor for a simple calculator

<isd:service xmlns:isd="http://xml.apache.org/xml-soap/deployment"
    id="urn:onjavaserver">
        <isd:provider type="java"
            scope="Application"
            methods="add subtract">
            <isd:java class="onjava.CalcService"/>
        </isd:provider>
    <isd:faultListener>org.apache.soap.server.DOMFaultListener</isd:faultListener>
</isd:service>

The deployment descriptor for our calculator service contains only three elements that we need to look at. The first element is the service element, which defines two attributes, the XML namespace and the unique ID of the service to be deployed. The ID defined in the service element must be unique, since this attribute is used to uniquely identify a published SOAP service.

The next element we need to examine is the provider element. It defines the actual implementation of the SOAP service. It does this with three attributes, each of which are defined as follows:

Listing 3. Attributes of the Provider Element

type

The type attribute defines the implementation type of the SOAP service. We defined our service as a Java service.

scope

The scope attribute defines the lifetime of the SOAP service. The possible values are page, scope, session, and application. These scope values map one-to-one with the scope values defined by the JSP specification.

methods

The methods attribute defines the names of the methods that can be invoked on this service object. This list should be a space-separated list of method names.

The final element of the deployment descriptor that we'll look at here is the java element. This element contains a single attribute, class, which names the fully qualified class of the named service.

Running the Server-Side Admin Tool to Manage Services

Now that we have defined our SOAP service and its deployment descriptor, we can publish it so that it can start servicing requests. To do this, you need to first compile the service and make sure it is in your classpath.

After you have compiled the service, you're ready to deploy it. The Apache SOAP Project is packaged with two administration tools -- a graphical tool and a command-line tool. They both allow you to easily deploy and undeploy services to the SOAP server. The three functions provided by these tools are listed below:

• The deploy function allows you to deploy a new service to a SOAP server.
• The undeploy function removes an existing SOAP service from a SOAP server.
• The list function lists all deployed SOAP services.

For our examples, we are going to use the Apache SOAP command-line tools to manage our service. SOAP command-line management functions are implemented by the org.apache.soap.server.ServiceManagerClient class. Using the ServiceManagerClient is very easy. We'll go through each of its functions in this section.

As we cover the following commands, you should note that each command references a servlet named rpcrouter. This servlet is at the core of all SOAP actions. It performs all service management and execution.

• List

  The list command lists all currently deployed services. To execute the list command, type the following line:

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

  If you have not published any other SOAP services, you should get a response that shows no deployed services. If you examine this command, you see that it executes the Java application ServiceManagerClient with two parameters: the location of the SOAP server, and the command to perform (list, in this case).

• Deploy

  The deploy command deploys our service to the SOAP server. This command also uses the ServiceManagerClientwith the deployment descriptor describing the SOAP service. To deploy our service, execute the following command:

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

  This command takes three parameters: the URL to the SOAP server, the command deploy, and the file containing our deployment descriptor. After you have executed this command, execute the list command. You should now see output listing urn:onjavaserver, which is the unique ID of our service. You can also view this service from the Web admin tool. Go to http://localhost:8080/soap/admin/index.html and select the "List" button. Typical results are shown in Figure 3.

  If you select the service name, you will see the details of the service, as shown in Figure 4.

• Undeploy

  The undeploy command removes a previously deployed service. To execute the undeploy command, type the following line:

  java org.apache.soap.server.ServiceManagerClient
  
  http://localhost:8080/soap/servlet/rpcrouter undeploy urn:onjavaserver

  Note: Do not execute this command until you have completed the remaining exercises in this article.

  The undeploy command takes three parameters: the location of the SOAP server, the actual command to perform (in this case, the undeploy command), and the name of the service to remove.

Pages: 1, 2, 3

Next Page