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.

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.

Back to top

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

• The SOAP Toolkits section at the SOAP::Lite for Perl home page provides a choice of toolkits in a variety of programming languages.
  
  
• Graham Glass's developerWorks series "The Web services (r)evolution," particularly Part 2 and Part 3, provide a great introduction to SOAP development.
  
  
• James Snell's Web services insider, Part 1: Reflections on SOAP gives an update on SOAP's role in the industry right now and compares features of several SOAP toolkits.
  
  
• Uche Ogbuji's Using WSDL in SOAP applications introduces Web Services Description Language and the benefits it can provide to SOAP development.
  
  
• XMethods.com has a growing list of publicly available SOAP services to play with.
  
  
• The SOAP 1.1 specification draft at the W3C site lays out the current technical details.
  
  
• The Apache XML Project includes Apache SOAP, an implementation of the SOAP submission to the W3C.
  
  
• Sun's page on its Brazil open-source Web application framework describes how it supports SOAP messaging.
  
  

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.

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• SOAPClient4XG
• Running it
• Resources
• About the author
• Comments

Next steps from IBM

Spring, JRuby, and Ajax development is easier with WebSphere Application Server - a smart Java 5 and J2EE Web services-based application server.

---

• Try: The no-charge WebSphere Application Server Community Edition is a pre-integrated, lightweight Java 5 application server built on Apache Tomcat and other best-of-breed open source software such as OpenEJB, Apache Axis, and Apache Derby.
• Article: The article leverage the Spring Framework and the WebSphere Application Server to improve your J2EE project productivity.
• Tutorial: See how the free WebSphere Application Server and XML can improve the efficiency of your JRuby on Rails and Ajax development.
• Buy: WebSphere Application Server - Express

My developerWorks community

Dig deeper into XML on developerWorks

Rate a product. Write a review.

Write a review for Rational products today!

Special offers