GuidesJava Meets SOAP

Java Meets SOAP

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

SOAP is the Simple Object Access Protocol, a new protocol for distributed applications developed by Microsoft, IBM, DevelopMentor, and UserLand.

I can see some of you frowning at the first mention of "distributed applications." The expression conjures visions of CORBA, DCOM. and RMI — three technologies famous for their complexity. However, as we will see, SOAP strikes an interesting balance between complexity and flexibility.

SOAP is highly modular to support different applications; however, the most popular one is to enable remote procedure calls (RPC) over HTTP and XML.

SOAP Principles

You can approach SOAP from different angles. The simplest one is probably to see SOAP as a variation on file transfer — a popular, but not very glamorous, approach to distributed computing.

Indeed, many distributed applications rely on file transfer. The client uploads a file with its request. The server decodes the file and prepares its response for the client, again as a file. Popular Internet applications, including e-mail and the Web don’t work differently. It may be less glamorous than calling RPC, as advocated by CORBA, DCOM, and RMI, but it is well understood, reliable, and very flexible.

SOAP Request and Response

A SOAP request looks like Listing 1. As you can see, it’s an HTTP POST request with an XML payload. SOAP adds one new parameter to the HTTP header: SOAPAction. SOAPAction is an arbitrary URI identifying the request. It need not be the URL for the Web server; in many respects it is similar to URIs in XML namespaces. According to the specification, the SOAPAction parameter exists primarily to allow firewalls to filter SOAP requests by looking at the HTTP header only.

The request is encoded in an XML document. SOAP defines an envelope and body elements (as well as an optional header). It encodes the procedure call as a XML element whose name is the method name ("reverse" in Listing 1) and whose content (“st” in Listing 1) is the call parameters.

Listing 1. SOAP request.

POST /ibm-soap/rpcrouter.jsp HTTP/1.1Host: localhostContent-Type: text/xml; charset="utf-8"Content-Length: 484SOAPAction: "http://www.psol.com/soap/reverse"<SOAP-ENV:Envelope   xmlns_xsi="http://www.w3.org/1999/XMLSchema/instance/"   xmlns_xsd="http://www.w3.org/1999/XMLSchema/"   xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">   <SOAP-ENV:Body>      <ns1:reverse         xmlns_ns1="http://www.psol.com/soap/reverse"         SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">         <st xsi_type="xsd:string">Pineapplesoft</st>      </ns1:reverse>   </SOAP-ENV:Body></SOAP-ENV:Envelope>

The server response is in Listing 2. Again, it’s an HTTP response with an XML document. The XML document includes the same envelope and body. The result is encoded in the body (as you can see, the return element contains the reversed string).

Listing 2. SOAP response.

HTTP/1.1 200 OKContent-Type: text/xml; charset="utf-8"Content-Length: 508<SOAP-ENV:Envelope   xmlns_xsi="http://www.w3.org/1999/XMLSchema/instance/"   xmlns_xsd="http://www.w3.org/1999/XMLSchema/"   xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">   <SOAP-ENV:Body>      <ns1:reverseResponse         xmlns_ns1="http://www.psol.com/soap/reverse"         SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">         <return xsi_type="xsd:string">tfoselppaeniP</return>      </ns1:reverseResponse>   </SOAP-ENV:Body></SOAP-ENV:Envelope>

Clearly SOAP is a simple solution. It relies on HTTP (and soon SMTP) for transfering XML document. Reliance on HTTP guarantees that SOAP will work across most firewalls.

Furthermore, an XML document encourages a lousy coupling between the client and the server. It proves more flexible than CORBA RPCs. Finally, since a SOAP request is essentially a Web page, it is not difficult to implement SOAP in servlets, JSP, ASP, or CGI scripts.

Implementing SOAP in Java

Although it would not be difficult, as discussed previously, to roll your own implementation of SOAP. Java programmers have a simpler solution: IBM and DevelopMentor have released Java libraries that implement the protocol. They are available from www.alphaworks.ibm.com (search SOAP for Java) and www.develop.com/SOAP, respectively.

To demonstrate them, we will implement the reverse client/server application using IBM’s SOAP for Java 1.1.

Listing 3 is the SOAP server with the

reverse()
method. You might wonder what makes it a SOAP server, Listing 3 looks suspiciously like a regular Java class. That’s the beauty of the IBM library, which completely hides SOAP on the server. It uses a descriptor file (in Listing 4) to interpret SOAP calls in terms of Java objects.

Listing 3. Reverse server.

public class Reverse{   public String reverse(String st)   {      return new StringBuffer(st).reverse().toString();   }}

Listing 4. Service descriptor.

<isd:service   xmlns_isd="http://www.ibm.com/namespaces/soap/deployment"   id="http://www.psol.com/soap/reverse">   <isd:provider class="Reverse"                      scope="Application"                       static="false"                       methods="reverse"/></isd:service>

The SOAP client is in Listing 5. Unlike the server, it relies heavily on SOAP objects, so you cannot mistake it for a regular class! Specifically, the client uses the Call object to implement the RPC. The Call object generates the XML document, establishes the HTTP connection, exchanges files, and decodes the result.

Pay particular attention to the call to

setTargetObjectURI()
since it may be confusing. The URI is not the HTTP server where Reverse resides, this URI is used for an XML namespace. The URL for the server is passed as a parameter to

invoke()
.

Listing 5. The SOAP client.

import java.net.*;import java.util.*;import com.ibm.soap.*;import com.ibm.cs.xml.*;import com.ibm.soap.rpc.*;import com.ibm.soap.encoding.*;import com.ibm.soap.encoding.soapenc.*;public class DoReverse{   public final static void main(String args[])      throws MalformedURLException, SOAPException   {      Call call = new Call();      call.setTargetObjectURI("http://www.psol.com/soap/reverse");      call.setMethodName("reverse");      call.setEncodingStyleURI(Constants.NS_URI_SOAP_ENC);      Vector params = new Vector();      params.addElement(new Parameter("st",String.class,                                      args[0],null));      call.setParams(params);      URL url =         new URL("http://localhost:8080/ibm-soap/rpcrouter.jsp");      Response resp =         call.invoke(url,"http://www.psol.com/soap/reverse");      if(!resp.generatedFault())      {         Parameter ret = resp.getReturnValue();         System.out.println(ret.getValue());      }      else      {         Fault fault = resp.getFault();         System.err.println(fault.getFaultCode() + " / " +                            fault.getFaultString());       }   }}

Running This Example

When installing this example, remember that SOAP for Java is still alpha software (it’s part of AlphaWorks). You should not try running it unless you are comfortable working with alpha software.

You will need to install the following components:

Carefully read the instructions that come with SOAP for Java. In particular, make sure you follow the steps outlined to modify your installation of Tomcat. A word of warning: I have also found Tomcat unstable under JDK 1.2. You should turn to JDK 1.1.8 or 1.2.2.

The Future

SOAP is the second generation of XML-based remote procedure call (the first generation was XML-RPC www.xml-rpc.com), but it is unlikely to be the last generation.

Indeed, SOAP was submitted to the IETF and the W3C for further standardization. This process will ultimately deliver a new specification that, if history is any judge, might end up being incompatible with SOAP. Regardless of the evolution of SOAP, there is definitively a role for XML-based remote procedure call.

About the Author

Benoît Marchal is a software engineer and writer who has been working extensively in Java and XML. He is the author of the book XML by Example and has his own business, Pineapplesoft, in Namur, Belgium. He is currently working on a new book.

Get the Free Newsletter!

Subscribe to Developer Insider for top news, trends & analysis

Latest Posts

Related Stories