A simple SOAP client

A general-purpose Java SOAP client


Updated: June 2001

SOAP, the Simple Object Access Protocol, is an evolving W3C standard developed by representatives of IBM, Microsoft, DevelopMentor, and UserLand Software for the exchange of information over a network. As more SOAP servers become publicly available on the Web, SOAP is doing for programs written in nearly any language -- even short little programs written in popular, simple languages like Visual Basic, JavaScript, and perl -- what HTML does for Web browsers: It gives them a simple way to take advantage of an increasing number of information sources becoming available over the Web.

Like HTML, SOAP provides a set of tags to indicate the roles of different pieces of information being sent over the Web using the HTTP transport protocol (and since SOAP 1.1, SMTP as well). SOAP, however, gives you much more power than HTML. With SOAP, your program sends a "SOAP request" (a short XML document that describes a method to invoke on a remote machine and any parameters to pass to it) to a SOAP server. The SOAP server will try to execute that method with those parameters and send a SOAP response back to your program. The response is either the result of the execution or the appropriate error message. Public SOAP servers are available to provide stock prices, the latest currency conversion rates, FedEx package tracking information, solutions to algebraic expressions, and all kinds of information to any SOAP client that asks.

Before SOAP existed, programs trying to use this kind of information had to pull down Web pages and "scrape" the HTML to look for the appropriate text. A visual redesign of those Web pages (for example, putting the current stock price in a table's third column instead of its second column) was all it took to render these programs useless. The SOAP spec, along with its brief accompanying schemas for SOAP requests and responses, provides the framework for a contract between clients and servers that creates a foundation for much more robust information-gathering tools.

There are plenty of SOAP clients available for most popular programming languages; see the SOAP Toolkits section at the SOAP::Lite for Perl homepage for an extensive list (see Related topics). Most provide you with a class library, a COM object, or its equivalent to call from your own program. Typically, the use of these client libraries follows this pattern:

  1. Your program passes the name of the remote method to invoke and any necessary parameters.
  2. The library assembles the appropriate XML document of a SOAP request to package this information.
  3. The library passes this XML document to the SOAP server identified by a SOAP endpoint URL, much the way you point a browser at a Web server address by specifying the server's URL.
  4. After the SOAP server attempts to execute the method, it assembles a SOAP response XML document around the result of the execution and passes it back to the SOAP client.
  5. Upon receiving the SOAP response, the client library parses the XML to get the result of the method invocation and passes this result to the program using the library.


Introductions to SOAP always talk about the structure of the XML documents used for SOAP requests and responses, but the SOAP clients that I played with always took care of the XML assembly and parsing under the hood so I didn't have to. As an XML geek, I wanted to do the XML part myself; I decided that if SOAP was so simple, I should be able to write a simple SOAP client that read an XML document of a SOAP request, sent it to a SOAP endpoint URL specified on the command line, read back the response document, and output that response. This would make it a truly general-purpose SOAP client, because it could invoke any method on any SOAP server.

The SoapClient4XG ("SOAP Client for XML Geeks") Java class shown in Listing 1 performs this without using any of the specialized Java SOAP classes listed at the SOAP Toolkits page mentioned earlier (see Related topics). After checking for the required SOAP endpoint URL and SOAP XML document filename parameters and the optional SOAP action parameter, it reads in the file, sends it to the SOAP server, reads back the response, and outputs that to standard out.

Because this SOAP client uses the HTTP protocol to send the XML SOAP request, much of the necessary work is the HTTP setup. Java offers an HttpURLConnection class with plenty of "set" methods to set each HTTP parameter appropriately, and most of them can be set with simple strings. The one HTTP parameter that requires a bit of extra code is Content-Length, so SoapClient4XG computes the length of the XML request by putting it into a byte array after reading it in, then checking the byte array's length property.

Other HTTP implementations are available that can take care of setting these HTTP parameters for you. Sun's open-source Brazil Web application framework (see Related topics) automates the handling of HTTP issues and makes proper SOAP error handling easier, because (unlike the older HttpURLConnection class) it's a general-purpose HTTP class that wasn't written specifically to ease the loading of images and other Web resources by Java applets.

See Listing 1 for the complete SOAP client.

Running it

Xmethods.com provides an ever-growing list of publicly available SOAP services. In addition to telling you whether the optional SOAP Action parameter is necessary for each service, descriptions of many of them include sample XML requests, so I copied the sample request for their weather temperature SOAP server, added some white space, and substituted my own zip code in its zipcode element, as shown in Listing 2.

With this file stored in a file called weattherreq.xml, the command line in Listing 3 sends its contents to the SOAP endpoint URL specified on the same XMethods Web page where I got the sample XML.

As shown in Listing 4, the SOAP server sends back a SOAP response with the current temperature stored in its response element.

Because this SOAP client sends a SOAP request from an XML document file that you create -- instead of one it creates for you under the hood where you don't have access to it -- you can use an XML editor or text editor to tinker directly with the XML being sent. More importantly, this SOAP client shows how little work needs to be done to take advantage of the growing choice of SOAP services. You simply need to name the SOAP endpoint URL of the service, set up the HTTP parameters, send some XML that indicates the methods to invoke and the parameters to pass to them, then wait for the response.

By all means, check out the SOAP libraries available for your favorite programming language. They usually offer better error handling than my SOAP client and other features that lay a better foundation for robust application development. Just remember the simplicity ultimately underlying it all, and the great power that this simple protocol makes possible.

(Special thanks to Michael Brennan for his help with the HTTP issues.)

Downloadable resources

Related topics

ArticleTitle=A simple SOAP client