A simple SOAP client

A general-purpose Java SOAP client

This article describes a simple, general purpose SOAP client in Java that uses no specialized SOAP libraries. Instead of creating the SOAP request XML document for you under the hood, this client lets you create your own request with any XML editor (or text editor). Instead of merely giving you the remote method's return values, the client shows you the actual SOAP response XML document. The short Java program shows exactly what SOAP is all about: opening up an HTTP connection, sending the appropriate XML to invoke a remote method, and then reading the XML response returned by the server.


Bob DuCharme, VP of Corporate Documentation, UDICo

picture of Bob DuCharme Bob DuCharme (www.snee.com/bob) is the author of Manning Publications' forthcoming XSLT Quickly, Prentice Hall's XML: The Annotated Specification and SGML CD, and McGraw Hill's Operating Systems Handbook. He writes the "Transforming XML" column for XML.com and has contributed to XML Magazine, XML Journal, IBM developerWorks, and Prentice Hall's XML Handbook. A frequent speaker at industry conferences and user groups, Bob is vice president of corporate documentation at UDICo (www.udico.com), makers of a high-performance, small-footprint middleware engine and development kit. He received his BA in religion from Columbia University and his masters in computer science from New York University, and currently lives in Park Slope, Brooklyn, with his wife Jennifer and their daughters Madeline and Alice.

01 May 2001

Also available in Japanese

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 Resources). 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 (see Graham Glass's excellent "The Web services (r)evolution" column on developerWorks) 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 Resources). 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 Resources) 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 (see Resources) 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.)



developerWorks: Sign in

Required fields are indicated with an asterisk (*).

Need an IBM ID?
Forgot your IBM ID?

Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.


All information submitted is secure.

Dig deeper into XML on developerWorks

ArticleTitle=A simple SOAP client