On Coupling


Team-Fly

	XML, Web Services, and the Data Revolution By Frank P. Coyle
	Table of Contents

	Chapter 4. SOAP

SOAP

SOAP carries on the XML-RPC tradition by defining an XML language for packaging arbitrary XML inside an XML envelope. Although SOAP does not depend on HTTP, the momentum behind SOAP is attributable to the fact that HTTP will usually be used as the transport protocol for SOAP messages.

Understanding SOAP is important for seeing how XML can be used to move information across the Web and how it fits in the grand vision of making XML-based distributed computing a reality. Dave Winer, whom some consider the godfather of XML-RPC, and who publishes a widely read forum called "DaveNet," ^[2] wrote about his work with RPC and caught the attention of some folks at Microsoft who asked Winer if he'd be interested in working with them on XML-over-HTTP. As Winer recounts it:

^[2] http://davenet.userland.com/.

I flew up to Redmond, met with Bob and met Mohsen Al-Ghosein and Don Box for the first time. We sat in a conference room, I had a projected laptop. I opened Notepad with an example call from our earlier protocol. As people expressed their ideas I changed the example. It was one of the most productive brainstorming sessions of my career....A few weeks into the process I wanted to release the software to our users, so we forked a release, called it XML-RPC, and continued working with Microsoft on what would become SOAP 1.1. ^[3]

^[3] See note 1 on p. 112.

On Coupling

In discussions about SOAP, the term "coupling" is often used with different shades of meaning depending on context. One meaning, taken from the software engineering literature, refers to coupling as the degree of connectedness between modules in a software system.

In a classic 1972 software engineering paper, Dave Parnas argued that the criteria for creation of modules should center around their capacity to insulate themselves through a focus on core functionality. ^[4] Later, Glenford Myers extrapolated on Parnas' ideas, identifying "High Module Independence" as one of the most important characteristics of quality software and using the term "coupling" to mean the degree of connectedness between modules. ^[5]

In the late 1980s and 1990s, another related meaning of the word "coupling" emerged based on the relationship between sending and receiving processes in distributed networks. In tightly coupled networks, senders and receivers rendezvous with each other, requiring that both processes exist at the same time and maintain knowledge of each other's identity and location. Loosely coupled networks, on the other hand, ease these constraints. Through the use of messaging middleware, loosely coupled systems do not require that sender and receiver be operational at the same time, nor do they require identity or location to be known in advance.

With SOAP, we find both meanings of the word "coupling" applicable . SOAP is decoupled from any underlying transport software and , through its message structure, enables the creation of loosely coupled networks that don't require tight binding between processes in order to communicate.

^[4] David L. Parnas, "On the criteria to be used in decomposing systems into modules," Communications of the ACM, 1972, 15(12): 105358.

^[5] Glenford Myers, The Art of Software Testing (New York: John Wiley & Sons, 1979).

SOAP Background

The SOAP 1.0 specification was developed by Microsoft, DevelopMentor, and Dave Winer of UserLand Software and released in the spring of 1998. Figure 4.8 illustrates the influences on SOAP. Prior to the release of SOAP 1.0, Winer released his work on RPC as the XML-RPC specification (http://www.xmlrpc.com), which is very close to SOAP 1.0. Following the release of SOAP 1.0, IBM and Lotus joined the original developers, along with a group of partners including Ariba, Commerce One, Compaq, IONA, Intel Corp., ObjectSpace, Rogue Wave, and others. SOAP 1.1 was published by the W3C as a Note in May 2000. In July 2001, the W3C released the first public Working Draft for SOAP Version 1.2 based on the work of the W3C's XML Protocol Working Group.

Figure 4.8. The SOAP specification and its influences.

graphics/04fig08.jpg

The SOAP Protocol

As Figure 4.9 illustrates, SOAP is a transport protocol similar to IIOP for CORBA, ORPC for DCOM, or JRMP for RMI. SOAP differs from CORBA, RMI, or DCOM in several ways:

IIOP, ORPC, and JRMP are binary protocols, while SOAP is a text-based protocol that uses XML. Using XML for data encoding makes SOAP easier to debug and easier to read than a binary stream.
Because SOAP is text-based, it is able to move more easily across firewalls than IIOP, ORPC, or JRMP.
SOAP is based on XML, which is standards-driven rather than vendor-driven. Potential adopters are less likely to fear vendor lock-in with SOAP.

Figure 4.9. The SOAP protocol opens up new options for data exchange across the Web.

graphics/04fig09.jpg

The net effect is that SOAP can be picked up by different transport protocols and delivered in different ways. For example, when used with HTTP it can be delivered to a Web server; when used over FTP it can deposited directly into a file system; and when used with SMTP it can delivered to a user 's mailbox.

Figure 4.10 illustrates that SOAP can be used for direct connection between sender and receiver, or, with the use of messaging middleware, SOAP messages can be stored for subsequent delivery and/or broadcast to multiple receivers.

Figure 4.10. SOAP extends the Web from server-to-browser to server-to-server interaction.

graphics/04fig10.jpg

It should be noted that for many companies, using SOAP as protocol for exchanging data between established partners is proving a totally satisfactory way to leverage the benefits of XML and the Web. In this scenario all that is required is an agreed-upon schema, either a DTD or an XML Schema, for the XML data being exchanged and a SOAP server capable of handling the incoming XML as it arrives over the Web. Details about what kind of schemas to expect and who will check that the XML conforms to the schemas are decided offline by individuals participating in the process. On the software side, senders need to be involved in packaging their data in an XML document. For those companies already storing data in XML, this should require only minimal effort. If the stored XML data is not in the form required by the agreement, an XSL Transformations (XSLT) style sheet can be programmed to automate the transformation.

SOAP Overview

SOAP consists of three parts :

Encoding rules that control XML tags that define a SOAP message and a framework that describes message content
Rules for exchanging application-defined data types, including when to accept or discard data or return an exception to the sender
Conventions for representing remote procedure calls and responses

SOAP messages define one-way data transmission from a sender to a receiver. However, SOAP messages are often combined to implement patterns such as request-response . When using HTTP bindings with SOAP, SOAP response messages can use the same connection as the inbound request.

SOAP Message Structure

Figure 4.11 illustrates the structure of a SOAP message, consisting of three parts:

The SOAP Envelope : The outermost element of a SOAP message. The Envelope element is the root of the XML document that defines a SOAP message.
The SOAP Header : An optional, yet key element in architecting a distributed system around XML. The Header element provides a modular way of directing SOAP servers to do processing before passing the SOAP message on. For example, it is possible to add SOAP header information that instructs a server to add transaction or authentication information. Headers are also important in building piped architectures where processing is done in stages and data is modified as it is passed from handler to handler.
The SOAP Body : An element that must appear in a SOAP message. The Body element is where the transported XML is loaded. SOAP makes no assumptions about the kind of XML transported in the body of a SOAP message. The data may be domain-specific XML or it may take the form of a remote procedure call.

Figure 4.11. SOAP messages have a common format that includes a SOAP Envelope, an optional Header, and a Body section that contains the message content. SOAP also defines a message path and set of roles that SOAP nodes can adopt along a path .

graphics/04fig11.jpg

SOAP Messaging Example

In the previous section we looked at sending XML-RPC over HTTP to execute specific procedures on our ZwiftBooks server. With SOAP we may still use XML-RPC to trigger specific methods on the server, or we may simply define XML elements that get processed by our SOAP server.

To understand how SOAP works, let's continue our ZwiftBooks example and look at how SOAP may be used to expand business functionality by opening our server up to collectors who wish to notify ZwiftBooks about books they have for sale. ZwiftBooks will then add the providers and their books to the ZwiftBooks database.

To make this happen, several things must be done by ZwiftBooks:

Define a top-level element and related subelements that will trigger processing of the book availability data by the SOAP server.
Define a schema (DTD or XML Schema) that dictates the form of the XML that will arrive from collectors and book providers.
Specify a namespace that is unique to ZwiftBooks. This may be the ZwiftBooks Web site or any URI.
Configure the server to return a fault if the incoming SOAP message is not one of the special elements defined in step 1.

Figure 4.12 illustrates a SOAP request for the ZwiftBooks guaranteed delivery time for a specific book, specified by ISBN number. Note that the SOAP Envelope element is the top-level element in the body of the SOAP message and within the SOAP body element is found the request for GetGuaranteedDeliveryTime , packaged as an element including the ISBN number.

Figure 4.12. A SOAP request sent to the ZwiftBooks server.

graphics/04fig12.jpg

A SOAP response takes the form illustrated in Figure 4.13. Here the XML response indicating the best delivery time is packaged in a SOAP message that is delivered using the standard HTTP response protocol. As far as HTTP is concerned , it's just data being returned to the client that initiated the request. However, for a client that understands SOAP, the data becomes useful information.

Figure 4.13. A SOAP response to a request to the ZwiftBooks server.

graphics/04fig13.jpg

Message Paths

An important aspect of SOAP is the provision for message paths. Independent of the transport protocol used to send SOAP messages, messages may be routed from server to server along a so-called message path. As we saw in Figure 4.11, message paths support message processing at one or more intermediate nodes in addition to the ultimate destination.

SOAP Intermediaries

SOAP intermediaries are an essential aspect of building scalable Web-based distributed systems. Intermediaries can act in different roles, including proxies, caches, store-and-forward hops, and gateways. Again, experience with HTTP has shown that intermediaries cannot be implicitly defined but must be provided as an explicit part of the messaging path model. Thus, one of the key motivations of the Working Group is to ensure that an XML protocol supports composability between peers.

A SOAP-compliant server must be able to act as a SOAP intermediary capable of processing and forwarding a SOAP message on a path from its origin to a final destination. SOAP intermediaries may be explicitly specified by providing their URIs as the value of the SOAP actor attribute within a SOAP header , for example:

<SOAP-ENV:Header
SOAP-ENV:actor=http://yourServer.com
. . .>

Alternatively, a SOAP message can specify that the header should be processed by the first SOAP application that processes the message, as in this example:

<SOAP-ENV:Header
SOAP-ENV:actor="http://schemas.xmlsoap.org/soap/actor/next"
. . .>

SOAP and Actors

If the SOAP actor attribute is not present in a header, then the recipient of the message is considered the final destination. The following list covers the rules a well-behaved SOAP server must follow when receiving a SOAP message:

Identify the parts of the SOAP message intended for that application. This means checking the header for an actor attribute that is either the URI of the application or the URI http://schemas.xmlsoap.org/soap/actor/next, which means that the application must process the header.
Verify that all parts of the header intended for the application and associated with a mustUnderstand="true" attribute are supported by the application. If the application cannot process the message, then it must discard the message and return a SOAP fault (see section on SOAP faults on page 137).
Process the parts of the header intended for the application. If there are elements that include the attribute mustUnderstand="false" or that do not specify the mustUnderstand attribute, then the application may ignore those elements.

If the application is not the ultimate destination of the message, then it must remove all header elements intended for it before forwarding the message.

SOAP Design Patterns

Architectural design patterns capture the proven experience of software architects in the form of architectural patterns, each with distinct properties that address different architectural design problems. To a business strategist, software architecture patterns provide a high-level conceptual view of a software system independent of the specific implementation's details. To a software engineer, patterns provide a structure within which components can be designed and integrated. To those tasked with moving from requirements to design, patterns provide a starting point for developing implementation strategies.

Figure 4.14 illustrates two of the architectural patterns in wide use today: the Layers Pattern, and the Pipe and Filter Pattern. The Layers Pattern is one of the earliest successful architectural patterns and is the basis for the design of telecommunications infrastructures such as TCP/IP. Layers describe a solution to a problem by partitioning the problem into subtasks that are assigned to individual layers. Each layer draws on services from the layer below and provides services to the layer above.

Figure 4.14. Architectural design patterns: The Layers Pattern and the Pipe and Filter Pattern.

graphics/04fig14.jpg

A variant of the Layers pattern, the Multitier Pattern, is used to build tiered systems. For example, two-tier client-server systems partition display functionality to the client tier and business logic to the server tier. Three-tier systems add another tier for managing data.

The Pipe and Filter Pattern is another architectural approach to systems construction that assumes a stream of data moving through a series of pipes and filters and being transformed as it travels from origin to destination. In addition to serving as transforming agents , stages in the Filter Pattern can be used to buffer data and help deal with issues that arise in working with interruptible network connections.

The SOAP specification provides support for the filters through its ability to specify intermediary processing agents along a path from an XML document's origin to a final destination.

Filters are also supported by the Simple API for XML (SAX), a Java application program interface for processing XML. SAX makes use of a filter class that can act as an intermediary in a complex chain of processing. The filter class is passed as the event handler to another class that generates SAX events, forwarding all or some of those events to the next handler or filter in the processing chain.

Filters may be used to prune the document tree by not forwarding events for elements with a given name (or that satisfy some other condition), or a filter can generate new events to add parent or child elements to an existing document stream. Filters can also be used to add or remove element attributes or modify the character data.

The Filter is related to UNIX's capability to take simple processing functions and pipe them together to perform complex tasks . The power of SOAP and SAX filters derives from the fact that simpler, easy-to-maintain filters may be chained together to produce complex XML data transformations.

SOAP Faults

SOAP faults occur when an application cannot understand a SOAP message or when an error occurs during the processing of a message. SOAP defines an XML fault element that carries error and/or status information back to the message sender.

Faults are intended to provide detail to the sender as to why the fault occurred. The information that can be returned as part of a fault includes the following:

faultcode : SOAP defines a set of faultcodes for basic SOAP errors, although an application may provide its own codes.
faultstring : This element provides a readable explanation as to why the fault occurred.
detail : The value of the detail element is that it provides information about the problem that occurred while processing the Body element. If not present, it indicates that the problem did not occur in the body of the SOAP message.