Home > Articles > Programming > Java

Building Web Services with Java: SOAP

  • Print
  • + Share This
Learn how to use SOAP straight out of the box, and how to extend SOAP in multiple ways to support your diverse and changing needs. Steve Graham et al apply design best practices to build several meaningful e-commerce Web services, and prepare you to climb still higher toward the top of the Web services interoperability stack.
This sample chapter is excerpted from Building Web Services with Java: Making Sense of XML, SOAP, WSDL, and UDDI, by Steve Graham, Toufic Boubez, Glen Daniels, Doug Davis, Yuichi Nakamura, Ryo Neyama, and Simeon Simeonov.
This chapter is from the book

There is a lot more to Web services than Simple Object Access Protocol (SOAP). Chapter 1, "Web Services Overview," introduced the Web services interoperability stack that went several levels higher than SOAP. SOAP is synonymous with Web services, however, because since its introduction in late 1999, it has become the de facto standard for Web services messaging and invocation. With competitive and market pressures driving the Web services industry in a hard race to provide meaningful solutions to cross-enterprise integration problems, SOAP is the go-to-market technology of choice.

What is SOAP all about, you ask? Will it save you from failure (and keep you clean) while you toil 80-hour work weeks on a business-to-business (B2B) integration project from hell? Will it support your extensibility needs as requirements change, and provide you with interoperability across multi-vendor offerings? Will it be the keyword on your resume that will guarantee you a big raise as you switch jobs? In short, is it the new new thing? Well, maybe.

SOAP is so simple and so flexible that it can be used in many different ways to fit the needs of different Web service scenarios. This is both a blessing and a curse. It is a blessing because chances are that SOAP can fit your needs. It is a curse because you probably won't know how to make it do that. This is where this chapter comes in. When you are through with it, you will know not only how to use SOAP straight out of the box, but also how to extend SOAP in multiple ways to support your diverse and changing needs. You will also have applied design best practices to build several meaningful e-commerce Web services for our favorite company, SkatesTown. Last but not least, you will be ready to handle the rest of the book and climb still higher toward the top of the Web services interoperability stack. To this end, the chapter will discuss the following topics:

  • The evolution of XML protocols and the history and motivation behind SOAP's creation

  • The SOAP envelope framework, complete with discussions of versioning, header-based vertical extensibility, intermediary-based horizontal extensibility, error handling, and bindings to multiple transport protocols

  • The various mechanisms for packaging information in SOAP messages, including SOAP's own data-encoding rules and a number of heuristics for putting just about any kind of data in SOAP messages

  • The use of SOAP within multiple distributed system architectures such as RPC- and messaging-based systems in all their flavors

  • Building and consuming Web services using the Java-based Apache Axis Web services engine

One final note before we begin. The SOAP 1.1 specification is slightly over 40 pages long. This chapter is noticeably longer, because the purpose of this book is to be something more than an annotated spec or a tutorial for building Web services. We've tried hard to create a thorough treatment of Web services for people who want answers to questions that begin not only with "what" and "how" but also with "why." To become an expert at Web services, you need to be comfortable dealing with the latter type of questions. We are here to help.

So, why SOAP? As this chapter will show, SOAP is simple, flexible, and highly extensible. Because it is XML based, SOAP is programming language, platform, and hardware neutral. What better choice for the XML protocol that is the foundation of Web services? To prove this point, let's start the chapter by looking at some of the earlier work that inspired SOAP.

Evolution of XML Protocols

The enabling technology behind Web services is built around XML protocols. XML protocols govern how communication happens and how data is represented in XML format on the wire. XML protocols can be broadly classified into two generations. First-generation protocols are based purely on XML 1.0. Second-generation protocols take advantage of both XML Namespaces and XML Schema. SOAP is a second-generation XML protocol.

First-Generation XML Protocols

There were many interesting first-generation XML protocol efforts. They informed the community of important protocol requirements and particular approaches to satisfying these requirements. Unfortunately, very few of the first-generation XML protocols achieved multi-vendor support and broad adoption. Two are worth mentioning: Web Distributed Data Exchange (WDDX) and XML-RPC.


WDDX provides a language- and platform-neutral mechanism for data exchange between applications. WDDX is perfect for data syndication and remote B2B integration APIs because it is all about representing data as XML. For example, Moreover Technologies, the Web feed company, exposes all its content through a WDDX-based remote API. Access http://moreover.com/cgi-local/page?index+wddx with an XML-aware browser such as Internet Explorer and you will get a WDDX packet with current headline news. A simplified version of the packet is shown in the following example. You can see from it that the data format is a recordset (tabular data) with three fields containing the URL to the full article, its headline text, and the publishing source:

<wddxPacket version="1.0">
      <recordset rowCount="2" fieldNames="url,headline_text,source">
         <field name="url">
         <field name="headline_text">
            <string>Firefighters hold line in Wyoming</string>
            <string>US upbeat as China tensions ease</string>
         <field name="source">

Allaire Corporation (now Macromedia, Inc.) created WDDX in 1998. WDDX is currently supported in many environments and is flexible enough to handle most useful datatypes (strings, numbers, booleans, date/time, binary, arrays, structures, and recordsets), but it cannot represent arbitrary data in XML. It is an epitome of the 80/20 rule: flexible enough to be useful yet simple enough to be broadly supported. Because WDDX is not bound to any particular transport, applications can exchange WDDX packets via HTTP, over e-mail, or by any other means. Many applications persist data as XML in a relational database using WDDX.


XML-RPC is an RPC protocol introduced in the market in 1998 by Userland. XML-RPC supports a set of datatypes similar to that supported by WDDX and uses HTTP as the underlying transport protocol. Because of its simplicity, XML-RPC enjoyed good multi-vendor support. Here's an example XML-RPC method call and response:


First-Generation Problems

Although first-generation XML protocols have been and still are very useful, their simplicity and reliance on XML 1.0 alone causes some problems.

First-generation protocols are not very extensible. The protocol architects had to reach agreement before any changes were implemented, and the protocol version had to be revved up in order to let tools distinguish new protocol versions from old ones and handle the XML appropriately. For example, when XML-RPC and WDDX added support for binary data, both protocols had to update their specifications, and the protocol implementations on all different languages and platforms supporting the protocols had to be updated. The overhead of constantly revising specifications and deploying updated tools for handling the latest versions of the protocols imposed limits on the speed and scope of adoption of first-generation protocols. Second-generation protocols address the issue of extensibility with XML namespaces.

The second problem with first-generation protocols had to do with datatyping. First-generation XML protocols stuck to a single Document Type Definition (DTD) to describe the representation of serialized data in XML. In general, they used just a few XML elements. This approach made building tools supporting these protocols relatively easy. The trouble with such an approach is that the XML describing the data in protocol messages expressed datatype information and not semantic information. In other words, to gain the ability to represent data in XML, first-generation XML protocols went without the ability to preserve information about the meaning of the data. Second-generation XML protocols use XML schema as a mechanism to combine descriptive syntax with datatype information.

To sum things up, the need to provide broad extensibility without centralized standardization and the need to combine datatype information with semantic information were the driving forces behind the effort to improve upon first-generation efforts and to create SOAP, the de facto standard XML protocol for modern Web services and B2B applications.

  • + Share This
  • 🔖 Save To Your Account