Java(TM) Boutique - Using SOAP with Java

Tutorials : Using SOAP with Java :

Test the installation

Once you have followed the previous instructions, we can test your installation by accessing the URL: http://localhost:8080/soap/admin. You will see a default admin page for Apache SOAP coming up. If not, then you might have forgotten to follow a previous instruction, so please recheck them. From this admin page, you can deploy and manage your services. Undoubtedly, there is another way of deploying and managing the services from the command prompt, which we will discuss later.

A simple SOAP service

Right, now we have our environment set up and will develop a very simple SOAP service, which will say Hello to a name variable passed to the service.


public class SoapService extends Object {

    /** Creates new SoapService */
    public SoapService() {
    }

/** This is the SOAP exposes method
*/
    public String sayGreeting(String name)
    {
        return "Hello "+name;
    }
}

As you see, the SOAP service does not necessarily have to use the Apache SOAP API. It can be any simple program to a complex database access program or a Java RMI program. Once deployed in the SOAP container, any SOAP client would be able to access the service in a seamless manner by using the Apache SOAP API. However, the SOAP service can also use Apache SOAP API to obtain fine-grained control over the SOAP messages over the wire.

Deploying the service

To deploy the above service, we have two options. We can deploy it through the admin utility of the Apache SOAP implementation via: http://localhost:8080/soap/admin URL or we can deploy through the command line utility. I would prefer to demonstrate the command line utility just because it will give us a better idea about Deployment Descriptors. Each SOAP service has to be provided with a Deployment Descriptor. The information that you bundle with the Deployment Descriptor depends on the type of service you are specifying. For example, an EJB based service will have to define more information compared to our simple service. The Deployment Descriptor typically contains the following information:

The id of the service, which is a Uniform Resource Name (urn) for the service. This id has to be unique for the set of services deployed in the same container.
The provider type.
The scope of the service (Request/Session/Application).
The provide class or script name.
The method(s) that are to be exposed as SOAP aware.
Optionally a fault listener.

Here is the Deployment Descriptor for our GreetingService SOAP application. You can put it any file (I have used soap.xml) and while deploying will have to pass the file to the utility program.

<isd:service xmlns:isd="http://xml.apache.org/xml-soap/deployment" 
	id="urn:greetingService">
  <isd:provider type="java" scope="Request" methods="sayGreeting">
    <isd:java class="sam.soap.service.SoapService" static="false"/>
  </isd:provider>  
</isd:service>

The above descriptor starts with a top-level service element by declaring an XML namespace to protect it from any other XML schema under the system. This element contains the id information of the service the URN by which it will be identified. Within the nested element provider, it specifies that the provider type for the service is Java language, its scope is Request and the method that is exposed as SOAP service is sayGreeting(). It is to be noted that when you are using a particular application, not all the existing interfaces have to be exposed as SOAP aware. If you want to expose more than one method, you can specify it as a comma delimited list. In the last part of the Deployment Descriptor we specify the fully qualified name of the provider class and also mention if the method exposed is static or not. We will learn to create Deployment Descriptors for more complex Java bean based applications in our next article. Once you have the above Deployment Descriptor file ready and saved it as "soap.xml" (you can chose any other name you want), then we can use the ServiceManagerClient utility provided by Apache SOAP implementation to deploy and manage the service. We can deploy our service with the following command:

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

Note: If you get some sort error or exception while executing the above utility, it is most likely due to a CLASSPATH problem. So please check your CLASSPATH settings as described in the previous section. The first argument to the utility is the URL of the SOAP handler.

You can list a set of services deployed by using the ServiceManagerClient by the following command:

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

You can undeploy any service you want with the following command:

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

Applet Index
(sorted alphabetically)
A B C D E F G H I J K
L M N O P Q R S T U
V W X Y Z #s

The Java Source
(applets w/source code)
A B C D E F G H I J K
L M N O P Q R S T U
V W X Y Z

How to Add Java Applets to Your Site

New on the Java Boutique:

New Review:

Time Management Made Easy with the Quartz Enterprise Job Scheduler
Why not just use the Java timer API? This open source scheduling API boasts simplicity, ease-of-integration, a well-rounded feature set, and it's free!

New Applet:

Reverse Complement
Reverse Complement is a simple applet that converts DNA or RNA sequences into three useful formats.