Simple Object Access Protocol (SOAP) Tutorial
SOAP has gained status as a common messaging protocol in Web services and SOA projects. This SOAP tutorial provides insight as to what SOAP standard is and when to use it. SOAP basics, how it compares to REST, SOAP attachments and how SOAP functions with WSDL will be covered.
SOAP has gained status as a common messaging protocol in Web services and SOA projects. This SOAP tutorial provides insight as to what SOAP standard is and when to use it. SOAP basics, how it compares to REST, SOAP attachments and how SOAP functions with WSDL will be covered.
TABLE OF CONTENTS
SOAP Basics
SOAP Tools
The State of SOAP
More Learning Guides
Simple Object Access Protocol (SOAP) was created in 1998 by Dave Winer, Don Box, Bob Atkinson, and Mohsen Al-Ghosein with backing by Microsoft. SOAP is a messaging framework that gained widespread support in the Java, .NET and open source communities during the early part of the 2000s. It has served as the foundation of many Web services projects and provides the mechanism by which many other Web services standards communicate.
What is SOAP?
SOAP (Simple Object Access Protocol) is a way for a program running in one kind of operating system (such as Windows 2000) to communicate with a progam in the same or another kind of an operating system (such as Linux) by using the World Wide Web's Hypertext Transfer Protocol (HTTP) and its Extensible Markup Language (XML) as the mechanisms for information exchange.
Since Web protocols are installed and available for use by all major operating system platforms, HTTP and XML provide an already at-hand solution to the problem of how programs running under different operating systems in a network can communicate with each other. SOAP specifies exactly how to encode an HTTP header and an XML file so that a program in one computer can call a program in another computer and pass it information. It also specifies how the called program can return a response.
The case for SOAP
Ed Tittel, full-time writer and XML trainer, wrote an article discussing SOAP 1.2. He states that in April of 2007, the World Wide Web Consortium released a collection of four documents as W3C recommendations. Together these documents enshrine a SOAP 1.2 Second Edition as the latest and greatest definition of XML-based information suitable for exchanging structured and typed information between peers in a runtime environment that is both distributed and decentralized.
Of course, SOAP has been in use for some time now. The original SOAP 1.2 recommendations were released in 2003. The Second Edition of the core SOAP documents are interesting to look at, because the W3C has taken great pains to make sure that changes are easy to see (additions appear in green, changes in yellow and deletions in washed-out red). According to the organization, the Second Edition of SOAP 1.2 "incorporates corrections for the known errata" in the first edition.
There are several arguments between those for the use of SOAP and those opposed. Here is a list of advantages:
- Using SOAP over HTTP allows for easier communication through proxies and firewalls than previous remote execution technology.
- SOAP is versatile enough to allow for the use of different transport protocols. The standard stacks use HTTP as a transport protocol, but other protocols are also usable (e.g. SMTP, RSS).
- SOAP is platform independent.
- SOAP is language independent.
- SOAP is simple and extensible.
The list of disadvantages are as follows:
- Because of the verbose XML format, SOAP can be considerably slower than competing middleware technologies.
- When relying on HTTP as a transport protocol and not using WS-Addressing or an ESB, the roles of the interacting parties are fixed. Only one party (the client) can use the services of the other. Developers must use polling instead of notification in these common cases.
- Most uses of HTTP as a transport protocol are done in ignorance of how the operation would be modeled in HTTP. This is by design (with analogy to how different protocols sit on top of each other in the IP stack), but the analogy is imperfect (because the application protocols used as transport protocols are not really transport protocols). Because of this, there is no way to know if the method used is appropriate to the operation. This makes good analysis of the operation at the application-protocol level problematic at best with results that are sub-optimal (if the POST-based binding is used for an application which in HTTP would be more naturally modeled as a GET operation).
The most argued topic regarding SOAP is its relation to REST and which is preferable.
SOAP vs. REST
There is a long-time controversy between those using REST vs. those using SOAP. In order to gain a little more perspective on REST, let's recap a typical process for a SOAP/WSDL design:
1 - Provider creates and implements a Web service interface onto an existing application.
2 - Provider creates a WSDL contract in order to distribute the Web service details to potential consumers.
3 - Consumer obtains WSDL contract for consumption.
4 - Consumer implements the WSDL in a specific platform - Java, C#, PHP, Perl - and creates a caller application.
William Brogden discusses how "REST versus SOAP" is somewhat misleading. REST is a style rather than a standard. However, as discussed in a previous article, many software designers thinking about Web services have come to the conclusion that SOAP is overly complicated and services such as eBay and Google are exposing their massive amounts of data with REST style services.
REST relies on a simple set of "verbs" and puts all complexity into "nouns" that specify the resource. SOAP on the other hand permits quite a complex set of XML formatted commands and data transmission options.
That said, the analyst community and users generally agree that SOAP and REST will co-exist in the future.
SOAP messaging
A SOAP message may need to be transmitted together with attachments of various sorts, ranging from facsimile images of legal documents to engineering drawings. Such data are often in some binary format. For example, most images on the Internet are transmitted using either GIF or JPEG data formats.
A SOAP message is an ordinary XML document containing the following elements:
- A required Envelope element that identifies the XML document as a SOAP message
- An optional Header element that contains header information
- A required Body element that contains call and response information
- An optional Fault element that provides information about errors that occurred while processing the message
According to W3C, "a SOAP message package contains a primary SOAP 1.1 message. It may also contain additional entities that are not lexically within the SOAP message but are related in some manner. These entities may contain data in formats other than XML. The primary SOAP 1.1 message in a message package may reference the additional entities. Such additional entities are often informally referred to as 'attachments.'"
Vendors offer varied tools for developing and managing SOAP services. Because SOAP is considered a layering system, it allows for attachments to provide SOAP with considerably more power and memory.
SOAP attachments
As an XML-based messaging protocol, SOAP messages require considerable processing power and memory. All parts of a SOAP message must conform to XML rules for allowed characters and character sequences so binary data can not be included directly. Furthermore, SOAP implementations typically parse the entire SOAP message before deciding what to do with the contents, so large data fields could easily exceed available memory. For all these reasons it was recognized that SOAP requires some mechanism for carrying large payloads and binary data as an attachment rather than inside the SOAP message envelope.
Over the years since SOAP first entered the awareness of Java programmers, a number of toolkits for SOAP servers and clients have been created. Although considerable stability in the SOAP specification has been achieved, the continuous parallel developments in general XML tools and the competing visions of various vendors have prevented any one toolkit becoming the universal choice of Java programmers.
Java has the Java Community Process procedure sponsored by Sun which attempts to define standard APIs (called Java Specification Requests, JSRs) by agreement between industry representatives. JSRs related to SOAP include JSR-67, which has produced two related specifications. The most basic functions are covered by a specification called SOAP with Attachments API for Java (SAAJ) version 1.3, most recently updated in April 2006.
The other product of this group is the Java API for Messaging, or JAXM, currently in version 1.1. JAXM builds on SAAJ by adding message transmission APIs.
The SOAP with Attachments API Version 1.3
The SOAP with Attachments API for Java (SAAJ) 1.3 provides the API for creating and sending SOAP messages by means of the javax.xml.soap package. It is used for the SOAP messaging that goes on behind the scenes in JAX-RPC and JAXR implementations. Developers can also use it to write SOAP messaging applications directly instead of using JAX-RPC.
The essential object for using SAAJ is a SOAPMessage object created by a call to the createMessage method of MessageFactory. The problem of the existence of both SOAP 1.1 and SOAP 1.2 Web services is solved by having MessageFactory implementations which let the programmer specify the style to be generated. The scope of the SAAJ standard emphasizes the API for constructing SOAP messages, but it does provide the abstract SOAPConnection class, which implementations can use for simple message transmission.
In the SAAJ toolkit, a SOAPMessage object contains a complete SOAP message. A message is either a SOAP-formatted XML document or a MIME multipart message whose first section is an XML document. The SOAP formatted XML is contained in a SOAPPart object which implements the org.w3c.dom Document interface. All SOAPMessages contain a single SOAPPart, which in turn contains a SOAPEnvelope corresponding to the root element of the document.
SOAP has been ever changing since its inception. Because of its ability to transform, it is expected that SOAP will continue to get steady use alongside WSDL, REST and SOA.
SOAP and WSDL
SOAP is often used in conjunction with WSDL (Web Services Description Language. WSDL is a service description language. It describes the interface of the service, i.e., the structure of the XML messages that the service can accept/return. WSDL also describes how those messages are encoded and indicates what protocols the service supports (e.g., SOAP over HTTP).
If you're familiar with CORBA, SOAP is like IIOP, and WSDL is like IDL. WSDL provides a programmatic description of the service. A tool can parse the WSDL and generate SOAP middleware code.
When building web services in Java, a developer typically uses a web services framework that generates the SOAP code. Popular open source Web services frameworks for Java include Apache Axis2, Apache CXF, and Sun's JAX-WS reference implementation. All Java EE application servers also include a Web services framework. The specific tooling used to generate the code is framework-specific.
The future of SOAP
The SOAP/XML/Java world does not seem inclined to stand still. The W3C is working on a "SOAP Message Transmission Optimization Mechanism," which will undoubtedly require yet another version of Java toolkits such as SAAJ.
SOAP is a lightweight protocol that can replace more complicated, distributed object technologies for many applications. However, SOAP's use of Web servers to tunnel through firewalls may limit its usefulness because it potentially opens corporations to external access. As it becomes more ubiquitous, SOAP may increasingly find itself in the sights of security personnel.
Security isn't stopping businesses from using SOAP. During the past 12 months, VetSource Inc. developed an SOA e-commerce application providing home delivery of veterinary prescriptions. With the new service veterinary hospitals can set up their own website where pet owners can order medications directly once they have a prescription from their veterinarian, explains Craig Sutter, the technical director at VetSource. His company hosts all the e-commerce applications, but allows the vet hospital to customize it to list office hours and services such as boarding.
The VetSource SOA is based on RESTful services, but can interact with SOAP-based Web services from partners linked into the system.
"All the services we're deploying in Mule are RESTful services," Sutter explained. "We use SOAP externally. Some of our partners provide their services over SOAP."
"From the beginning, the VetSource SOA implementation was designed to support business growth, which the company is already seeing, including increasing volume in its call centers," Sutter said.
SOAP will be leveraged as a binding class by the Apache Tuscany project. In a Tuscany demonstration at the 2008 JavaOne conference, IBM's Jean-Sebastien Delfino provided an example of how to add a SOAP binding while updating the online catalog for a fruit store. The entire operation was performed using simple HTML-style carrot tags.
He showed how to add a new component class (vegetables in this case) and a database, the latter of which involved another Atompub feed. After that he added a third-party supplier to the service by inserting a single SOAP binding line. "You can point to a WSDL if you want or specify policies," he said.
- Representational State Transfer (REST) Tutorial
- Ajax Learning Guide
- XML Security Learning Guide
- BPEL Learning Guide
- SOA Learning Guide
- Eclipse Learning Guide
- BPM Learning Guide
- ESB Learning Guide
