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
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
typeattribute defines the implementation type of the SOAP service. We defined our service as a Java service.
scopeattribute defines the lifetime of the SOAP service. The possible values are
application. These scope values map one-to-one with the scope values defined by the JSP specification.
methodsattribute 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:
deployfunction allows you to deploy a new service to a SOAP server.
undeployfunction removes an existing SOAP service from a SOAP server.
listfunction 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.
listcommand lists all currently deployed services. To execute the
listcommand, 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
ServiceManagerClientwith two parameters: the location of the SOAP server, and the command to perform (
list, in this case).
deploycommand 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
listcommand. 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.htmland 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.
undeploycommand removes a previously deployed service. To execute the
undeploycommand, 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.
undeploycommand takes three parameters: the location of the SOAP server, the actual command to perform (in this case, the
undeploycommand), and the name of the service to remove.