 | Level: Introductory Bob DuCharme (bob@snee.com), VP of Corporate Documentation, UDICo
01 May 2001 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.
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:
- Your program passes the name of the remote method to invoke and any necessary
parameters.
- The library assembles the appropriate XML document of a SOAP
request to package this information.
- 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.
- 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.
- 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.
SOAPClient4XG
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.)
Resources
About the author | 
| |
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. |
Rate this page
| |
