1. INTRODUCTION
Simple Object Access Protocol (SOAP), as its name implies, is a simple and lightweight mechanism to exchange information between peers. It specifies a modular packaging model to encode information to be changed. Specifically, it uses XML documents, called SOAP messages, to represent information.
However, it does not specify any application semantics such as a programming model or implementation specific semantics. As a result SOAP can be used in a wide variety of systems ranging from messaging systems to RPC.
2. DIFFERENCES WITH XML-RPC
XML-RPC was designed to be as simple as possible, while allowing complex data structures to be transmitted, processed and returned. In fact, the specification itself is seven pages long, including examples and an FAQ, and is fairly easy to understand. An ordinary programmer, after reading its specification, should not find any difficulty whatsoever in implementing XML-RPC in his/her software.
Simplicity is also XML-RPC’s greatest limitation. Though almost all of our RPC needs can be achieved using it, there are certain things that we just can’t do such as passing an object to a function, or specifying which portion of a receiving application the message is intended for etc.
SOAP tried to pick up where XML-RPC left off by implementing user defined data types, the ability to specify the recipient, message specific processing control, and other features. Consequently, the SOAP specification became 40 pages long and is complex.
Literally it is not “lightweight” and it threw out the most important feature of XML-RPC, its simplicity. SOAP extensively uses namespaces and attributes specification tags in almost every element of a message. As a result, it incurs significantly more overhead. However, it adds much more information about what is being sent.
3. SOAP ARCHITECTURE
SOAP was designed as an object-access protocol by Dave Winer et al. in 1998. Its specification is currently maintained by the XML Protocol Working Group of the World Wide Web Consortium. SOAP architecture consists of three parts:
- The SOAP envelope construct that defines an overall framework to express message content, the message exchangers.
- The SOAP encoding rules that define a mechanism that can be used successfully to exchange application-specific type values.
- The SOAP RPC representation defines a protocol that can be used for remote procedure calls and responses.
Figure 18.1: RPC using SOAP
This simple idea can potentially be used in combination with a variety of communication protocols, However, the only bindings defined in the specifications so far describe how to use SOAP in combination with HTTP and HTTP Extension Framework.
The RPC part specification describes a standard, XML-based way to encode requests and responses, such as
- Requests to invoke a method including parameters
- Responses from a method including out parameters
- Errors
Figure 18.1: shows how a remote method can be invoked using HTTP POST messages according to SOAP specification.
4. SOAP FLAVORS
There are two versions of SOAP specification 1.1 and 1.2. Since these versions are referred to frequently while working with SOAP, it is important to understand the relations between these two. This section outlines the changes and benefits brought by SOAP Version 1.2.
Both SOAP Version 1.1 and 1.2 are standardized by World Wide Web Consortium (W3C). Intuitively, version 1.2 extends the specification version 1.1. Some changes are significant, while other changes are minor. In a single sentence, SOAP Version 1.2 is cleaner, better for web integration, more versatile and faster. The following is a summary of significant changes made in Version 1.2.
- SOAP Version 1.2 provides clear processing model.
- SOAP 1.2’s testing and implementation requirements lead to better interoperability.
- SOAP 1.1 is based on XML 1.0. SOAP 1.2 is based on XML Information Set (XML Infoset).
- SOAP 1.2 provides the ability to define transport protocols other than HTTP.
- SOAP 1.2 includes HTTP binding for better integration to the World Wide Web.
- Introduced SOAP with Attachments API for Java (SAAJ) in Version 1.2.
- SOAP Version 1.2 delivers a very well-defined extensibility model.
A detailed list of changes can be found in http://www.w3.org/TR/2001/WD-soap12-20010709/ #changes and http://www.w3.org/2003/06/soap11-soap12.html
5. SOAP MESSAGES
The primary part of the SOAP is the messaging framework. It specifies a set of XML elements for “packaging” information for exchange between peers. The schema for SOAP messages can be downloaded from http://schemas.xmlsoap.org/soap/envelope/.
Any SOAP message is an XML document having the following minimal specification.
- The mandatory root element <Enveiop>.
- The <Envelop> element contains an optional <Header> element followed by a mandatory <Body>
Here is a sample template that shows the structure of a SOAP message:
<soap:Envelope xmlns:soap=”http://schemas.xmlsoap.org/soap/envelope/”>
<soap:Header> <!– optional –>
<!—control information goes here… –>
</soap:Header>
<soap:Body> <!– mandatory –>
<!– payload or Fault element goes here… –>
</soap:Body>
</soap:Envelope>
The elements must always belong to the namespace http://schemas.xmisoap.org/soap/ envelope/. The root element <Enveiop> and namespace together make an XML document a SOAP message. Parsers can simply look at the root element to identify a SOAP message. The <Envelop> contains an optional <Header> element and one mandatory <Body> element that contains payload. Here is a simple SOAP message:
<?xml version=”1.0” ?>
<soap:Envelope xmlns:soap=”http://schemas.xmlsoap.org/soap/envelope/”>
<soap:Body>
<c:add xmlns:c=”http://ws.calc/”>
<arg0>7</arg0>
<arg1>8</arg1>
</c:add>
</soap:Body>
</soap:Envelope>
This message represents a call of a method add() with two argument values 7 and 8. The <Body> element can have any number of attributes or children elements from any namespace. This is ultimately where the data, which we want to send, goes in.
The receiver of the above message may send the result using another message as follows:
<?xml version=”1.0” ?>
<soap:Envelope xmlns:soap=”http://schemas.xmlsoap.org/soap/envelope/”>
<soap:Body>
<c:addResponse xmlns:c=”http://ws.calc/”>
<return>15</return>
</c:addResponse>
</soap:Body>
</soap:Envelope>
A SOAP messages can be validated against the underlying schema which can be downloaded from http://schemas.xmlsoap.org/soap/envelope/. We downloaded it and put it in a file SOAP. xsd. There are various XML document validators available on the web. We downloaded one such free command line validator from https://dl.dropbox.com/u/105 64 62 8/xsd11-validator.jar. Suppose the name of the file containing the above SOAP message is soap.xml. Then we can check if this XML document is a SOAP message using the following command:
java -jar xsd11-validator.jar -sf SOAP.xsd -if soap.xml
Like most existing protocols, SOAP also distinguishes controls information and payload. The <Header> contains application specific control information. Like <Body>, the <Header> element can also have any number of attributes or children elements and must be qualified by any namespace (except the SOAP namespace). However, SOAP itself does not specify any built-in headers. These elements influence processing of payload. Here is an example of SOAP message that uses <Header> element.
<?xml version=”1.0” ?>
<soap:Envelope xmlns:soap=”http://schemas.xmlsoap.org/soap/envelope/”> <soap:Header>
<s:mode xmlns:s=”sample”>cheque</s:mode>
</soap:Header>
<soap:Body>
<pay>10000</pay>
<to>B. S. Roy</to>
</soap:Body>
</soap:Envelope>
The body contains an instruction to pay an amount 10000. The header tells that the payment should be made by cheque.
If the receiver of a SOAP message finds anything wrong, it can inform the sender about it by sending a special response message, called fault message, back to the sender. The <Fault> element is used for this purpose. It is an optional element and if it appears, must be the child of <Body> element. This provides a standard error representation that makes possible for a generic architecture to differentiate between success and error. Here is an example of fault message:
<?xml version=”1.0” ?>
<soap:Envelope xmlns:soap=”http://schemas.xmlsoap.org/soap/envelope/”>
<soap:Body>
<soap:Fault xmlns:ns4=”http://www.w3.org/2003/05/soap-envelope”>
<faultcode>soap:Client</faultcode>
<faultstring>Cannot find dispatch method for {http://ws.calc/}add1</faultstring>
</soap:Fault>
</soap:Body>
</soap:Envelope>
This says that an error occurred due to Client as it couldn’t dispatch method for addi. The <Fauit> element has two mandatory children <fauitcode> and <fauitstring>. The former one holds a code for identifying fault and the latter gives a human readable explanation of the fault.
6. SOAP BINDING
One of the important features of SOAP is that it enables exchange of messages using various underlying protocols. Since it is not bound to a specific protocol, a communicating peer can choose any suitable protocol for SOAP message transport without affecting the message itself.
However, the only bindings defined in the specifications so far describe how to use SOAP in combination with HTTP and HTTP Extension Framework. HTTP binding maps SOAP request/ response message to HTTP request/response message. In the next section, we shall describe how to send SOAP messages over HTTP.
7. RPC USING SOAP
Although SOAP was originally intended for exchanging any type of messages, it is primarily used for Remote Procedure Call (RPC). So, it still defines a convention for encapsulating and exchanging RPC calls and responses. Here is a sample HTTP SOAP request message.
POST /ws/calc HTTP/1.1 Accept: text/xml, multipart/related Content-Type: text/xml; charset=utf-8 SOAPAction: “http://ws.calc/Calculator/addRequest”
User-Agent: JAX-WS RI 2.2.4-b01 Host: 172.16.5.81:9999 Connection: keep-alive Content-Length: 215
<?xml version=”1.0” ?>
<S:Envelope xmlns:S=”http://schemas.xmlsoap.org/soap/envelope/”>
<S:Body>
<ns2:add xmlns:ns2=”http://ws.calc/”>
<arg0>4</arg0>
<arg1>3</arg1>
</ns2:add>
</S:Body>
</S:Envelope>
A SOAP request message is an HTTP POST request message with two mandatory headers Content-Type and Content-Length. The body of the HTTP request message is a SOAP message which represents the call of a method add with two arguments 4 and 3. The corresponding response method may look like this:
HTTP/1.1 200 OK Transfer-encoding: chunked Content-type: text/xml;
charset=utf-8 Date: Sun, 30 Mar 2014 07:53:06 GMT
<?xml version=”1.0” ?>
<S:Envelope xmlns:S=”http://schemas.xmlsoap.org/soap/envelope/”>
<S:Body>
<ns2:addResponse xmlns:ns2=”http://ws.calc/”>
<return>7</return>
</ns2:addResponse>
</S:Body>
</S:Envelope>
Here, the body of the HTTP request message is also a SOAP message which represents the return value 7 from the server.
Source: Uttam Kumar Roy (2015), Advanced Java programming, Oxford University Press.