Very Simple Object Access Protocol with Java

Developer.com content and product recommendations are editorially independent. We may make money when you click on links to our partners. Learn More.

To begin with, I would like to make a few necessary remarks about topics that will be discussed in this article and about the minimal level of knowledge the reader should have. The topics are in the title of article—we will talk about SOAP technology, and will try to explain it as quickly and easily as possible, and, it goes without saying, we will include the usual “Hello World!” example to show the reader what it looks like. To my mind, it is always harder to start learning new technology if you have only the official documentation, with huge examples, explaining all the features and advantages, but doesn’t explain what it looks like. In this article, I’m not supposed just to be able to explain SOAP technology superficially, but whether it will turn out—clearly. Nevertheless, from our side, we will assume that the reader is familiar with the Java language, Web technologies, and (better, much better!) with the XML language, basics of XML Namespaces, and XML Schema. In this case, there should be no difficulties in understanding any part of this material. Although, even without such knowledge, we will explain everything as simply as possible, but you will get in trouble when you will start doing your own SOAP applications. So, it is a good idea to spend some time learning them.

From a technical standpoint, it is necessary to mention that we are using the Windows XP OS with Java 2 SDK 1.4.1, Apache SOAP 2.3.1, JAF 1.0.2, JavaMail 1.3.1, and Xerces 2.6.0. Everything mentioned above works properly with the Tomcat 4.1.29 JSP/Servlet container. All software is free, so you can easily download it and install for yourself, on any platform you like—Windows or UNIX. Java SDK, JAF, and JavaMail are located on Sun Microsystems’ official site, http://java.sun.com, and everything else is on the Jakarta project’s official site, http://jakarta.apache.org. Probably you already became a bit nervous once you saw how many different packages we need, but in reality you should not be afraid of this. It’s rather easy once you understand the basics properly. Installation is not a hard thing; you just need to be very careful when setting your environment variables, such as (for example) CATALINA_HOME, CLASSPATH, JAVA_HOME, and so forth. All these tricks are in manuals; I just would like to concentrate your attention on them once again, so you will pass with this process as quickly as possible. I’ve just added the next few strings into Tomcat’s bin/setclasspath.bat:

...
set CATALINA_HOME=C:Tomcat4.1.29
set CLASSPATH=%JAVA_HOME%libtools.jar
set CLASSPATH=%JAVA_HOME%soap-2.3.1libsoap.jar
set CLASSPATH=%CLASSPATH%;%JAVA_HOME%javamail-1.3.1mail.jar
set CLASSPATH=%CLASSPATH%;%JAVA_HOME%jaf-1.0.2activation.jar
set CLASSPATH=%CLASSPATH%;%JAVA_HOME%xerces-2_6_0xercesImpl.jar
set CLASSPATH=%CLASSPATH%;%JAVA_HOME%xerces-2_6_0xercesSamples.jar
set CLASSPATH=%CLASSPATH%;%JAVA_HOME%xerces-2_6_0xml-apis.jar
set CLASSPATH=%CLASSPATH%;%JAVA_HOME%xerces-2_6_0xmlParserAPIs.jar
set CLASSPATH=%CLASSPATH%;%CATALINA_HOME%commonlibservlet.jar
set CLASSPATH=%CLASSPATH%;%CATALINA_HOME%commonlibtools.jar
...

You need to correct them in case your installation paths are not the same as those used above, shut down, and restart Tomcat. Then, you will have everything ready to work with SOAP. But for now, I would like to forget about the technical part, and learn a bit of theory information.

SOAP means Simple Object Access Protocol. Strangely enough, it is really simple. It is the protocol based on XML that allows program components and applications to interact with each other, using a standard Internet protocol—HTTP. SOAP is an independent platform, it does not depend on the programming language, and it is simple, flexible, and easily expandable. Nowadays, applications can interact with each other using Remote Procedure Calls (RPC) that are based on the DCOM and CORBA technologies, but HTTP was not projected for these purposes. RPC is too difficult to adapt for the Internet. They represent a number of the problems connected to compatibility and safety because firewalls and proxy servers usually block the given kind of the traffic. The best kind of interaction between applications is the use of HTTP because HTTP is supported by all Internet browsers and servers. SOAP was created to achieve the same purposes.

So, what does everything look like? For example, one application (A) needs to interact with another application (B) with the help of SOAP. They will interact using the following scheme:

The SOAP envelope is an XML document that consists of the following parts:

As you can see, it’s pretty simple; it looks exactly like a normal letter or any of your e-mail. Do you want to see it in action? Here we go! We are a few steps away from creating and running our own “Hello World” application with SOAP, but because we are going to keep it very simple, I would like to show you the scheme of how it will work.

Our “Hello World” example will consist of a SOAP Service to which our SOAP Client will send its name and try to get some answer. This SOAP Service will need to be deployed with a SOAP Admin Tool, so that the SOAP (Proxy) RPC Router that will redirect all requests will know with which service it should work. In general, this will looks like that:

Now, step by step we will find out what happens. In Step 1, HelloWorldClient will connect to a SOAP RPC Router, requesting our SOAP Service and passing a String value containing our name to it. The SOAP RPC Router will check whether it has deployed theSOAP Service or not. If it is found, it will pass data to the SOAP Service and call the specified method. This is Step 2. The Method of the SOAP Service will be executed, and will return some String value (this will be its answer to SOAP Client) (Step 3). The SOAP RPC Router will just redirect this data to the SOAP Client in Step 4. That is all. All data transfer in Step 1 and Step 4 will be done in SOAP Envelopes (hold on for a while, and you will see what they look like). As you can see, the algorithm is pretty simple, too, so we are ready to take care about the code.

First of all, we will create the SOAP Service. The code is below, and do not forget to put it into a HelloWorld/ directory (and, eventually, include this directory into your CLASSPATH):

1: // SOAPService.java
2: package HelloWorld;
3: public class SOAPService {
4:   public String sayHi(String x) {
5:     return("Hello my friend, " + x + "! Glad to see you!");
6:   }
7: }

(Please note that the numbers on the left to the text are just for your information. You do not need to type them!)

I guess it’s too easy to add any comments. So, just compile it with the following command:

javac SOAPService.java

Secondly, once we have the SOAP Service ready, we need to deploy it with the SOAP Service Manager. There are a few ways to do that, but I suggest the easiest, to my mind, for the beginner in SOAP understanding. We assume that your Web server (Tomcat or any other) is already running, and you installed SOAP properly, so when browsing to http://localhost:8080/soap/ you will see the Apache SOAP Welcome page. Click Run the admin client, then Deploy. You will get a screen, on which you need to fill in the next fields—ID, Scope, Methods, Provider Type, and Java Provider. You can forget about all the other fields until you need them. We do not need them for our “Hello World” example now. So, the values will be the following:

A few comments: ID is field in which we will identify our SOAP Service from SOAP Client. The Methods field contains a list of methods that the SOAP Service provides. Java Provider – Provider Class is the name of the SOAP Service Java class.

Now, click the Deploy button and your service will be deployed. Again, please pay attention to correctly setting the CLASSPATH environment variable, so your HelloWorld.SOAPService class can be found and all necessary jars can be found too. This is the common mistake almost everybody makes. And now, you can click List and you will see your service deployed. Congratulations!

And, last but not least, let’s create the SOAP Client. The code will look a bit more complex, but it’s not in reality—just a bit long.

 1: // HelloWorldClient.java
 2: import java.io.*;
 3: import java.net.*;
 4: import java.util.*;
 5: import org.apache.soap.*;
 6: import org.apache.soap.rpc.*;
 7: public class HelloWorldClient {
 8:   public static void main(String[] arg) throws Exception {
 9:     Call c = null;
10:     URL url = null;
11:     Vector params = null;
12:     Response rep = null;
13:     String ourName = "Superman";
14:     String ourUrn = "urn:HelloWorld_SOAPService";
15:     String ourMethod = "sayHi";
16:     url = new URL("http://localhost:8080/soap/servlet/
                       rpcrouter");
17:     System.out.println("Passing to our deployed "+ourUrn+"
                            our name ("+ourName+"): ");
18:     c = new Call();
19:     c.setTargetObjectURI(ourUrn);
20:     c.setMethodName(ourMethod);
21:     c.setEncodingStyleURI(Constants.NS_URI_SOAP_ENC);
22:     params = new Vector();
23:     params.addElement(new Parameter("ourName", String.class,
                                         ourName, null));
24:     c.setParams(params);
25:     System.out.print("and its answer is: ");
26:     rep = c.invoke(url, "");
27:     if (rep.generatedFault()) {
28:       Fault fault = rep.getFault();
29:       System.out.println("nCall failed!");
30:       System.out.println("Code = " + fault.getFaultCode());
31:       System.out.println("String = " + fault.getFaultString());
32:     } else {
33:       Parameter result = rep.getReturnValue();
34:       System.out.print(result.getValue());
35:       System.out.println();
36:     }
37:   }
38:}

(Please note that the numbers on the left to the text are just for your information. You do not need to type them!)

I would like to add a few comments. In Line 13, we set our name, which we will pass to the SOAP Service. In Line 14, we set the ID of the service that we will invoke, and in Line 15, the method of this service. With this ID, this service should be deployed in the SOAP Service Manager. We do not set any other values, and just work with these. You can get information about the functions from the official documentation on SOAP that comes with your SOAP package. Explaining them goes beyond the scope of this article.

Compile the SOAP Client in the following way:

javac HelloWorldClient.java

To crown it all, let’s check whether everything is ready for our test. Tomcat is running, all environment variables are set correctly, the SOAP Service is compiled and deployed, and the SOAP Client compiled successfully. Okay, let’s run it and you will see this screen:

As you can see, our SOAP Client successfully sent its name and received an answer with the SOAP protocol. And, as promised above, here is the source of the SOAP envelopes that were sent to and received from the SOAP Service.

SOAP Envelope that was sent to SOAP Service

<?xml version='1.0' encoding='UTF-8'?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/
                                   soap/envelope/"
                   xmlns_xsi="http://www.w3.org/2001/
                              XMLSchema-instance"
                   xmlns_xsd="http://www.w3.org/2001/XMLSchema">
<SOAP-ENV:Body>
<ns1:sayHi xmlns_ns1="urn:HelloWorld_SOAPService"
           SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/
                                   soap/encoding/">
<ourName xsi_type="xsd:string">Superman</ourName>
</ns1:sayHi>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>:

SOAP Envelope that was received from SOAP Service

<?xml version='1.0' encoding='UTF-8'?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/
                                   soap/envelope/"
                   xmlns_xsi="http://www.w3.org/2001/
                              XMLSchema-instance"
                   xmlns_xsd="http://www.w3.org/2001/XMLSchema">
<SOAP-ENV:Body>
<ns1:sayHiResponse xmlns_ns1="urn:HelloWorld_SOAPService"
                   SOAP-ENV:encodingStyle="http://schemas.xmlsoap.
                                           org/soap/encoding/">
<return xsi_type="xsd:string">Hello my friend, Superman!
                              Glad to see you!</return>
</ns1:sayHiResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

To understand what all these tags in the SOAP Envelopes are, I suggest that you spend some time reading the http://www.w3.org/2001/06/soap-envelope namespaces specification.

I hope this article was at least a little help for you in understanding SOAP technology. This technology is simple and interesting, powerful, and flexible; it is used in many Web applications and the number of them is growing. It’s worth learning SOAP, at least just to know what is it and how it works.

© Olexiy Prokhorenko
http://www.7dots.com/resume/
Co-author: Alexander Prohorenko