SOAP

Simple Object Access Protocol (SOAP) version 1.1 is an industry standard designed to improve cross-platform interoperability using the Web and XML. The Web has evolved from simply pushing out static pages to creating customized content that performs services for users. A user can be a customer retrieving specialized Web pages for placing orders or a business partner using a customized form for reviewing stock and sales figures. A wide range of components located on various computers are involved in performing these Web-based services. Because these systems consist of many computers, including the client computer, middle-tier servers, and usually a database server, these systems are called distributed systems. To understand how SOAP works, let's take a look at the distributed system first.

Distributed systems commonly use two models for communication: message passing (which can be combined with message queuing) and request/response messaging system. A message passing system allows messages to be sent at any time. Once a message has been sent, the application that sent the message usually moves on. This type of system is called asynchronous. An asynchronous system typically uses messages, but it can also be based on other models. With the request/response model, the request and the response are paired together and can be thought of as a synchronous system. The request is sent by an application, and the application usually waits until a response is received before continuing. When one application calls an object on another computer by making a Remote Procedure Call (RPC), we can think of this call as synchronous request/response message passing.

The request/response model is commonly used to allow components on different computers to communicate with each other using RPCs. Over the last several years, many attempts have been made to develop a standard that would allow this communication between components on different computers. Currently, the two most commonly used standards are Distributed Component Object Model (DCOM) and the Object Management Group's Internet Inter-Orb Protocol (IIOP). Both of these standards work well; their greatest shortcoming is that they do not natively interoperate with each other. Therefore, you cannot arbitrarily make a call to a component on a server from a client without first knowing what standard that server is using. Usually, you will also have to configure the client so that it can communicate with the server, especially when there are security issues. DCOM works best when all the computers in the system are using Microsoft operating systems. An IIOP system works best when all the computers in the system use the same CORBA Object Request Broker (ORB).

When you are working on an internal system, it might be possible to limit the system to one platform or the other. Once you start working with the Internet or expanding the intranet out to extranets (for example, networks that include the corporation and its partners), it will usually be impossible to have a uniform platform across the entire system. At this point, DCOM and IIOP will no longer allow communication between any two components within the system, and neither of these two standards allows users to cross trust domains easily. Thus, for larger systems expanding across computers with multiple platforms, we need a way to enable objects to communicate with each other. The solution to this problem is SOAP.

The SOAP standard introduces no new concepts¡ªit's built completely from existing technology. It currently uses HTTP as its request/response messaging transport and is completely platform independent. As you know, HTTP connects computers across the entire world. HTTP can go through firewalls and is the easiest means to transport messages to any computer in the world. It's likely that SOAP will evolve to use other protocols in the future.

A SOAP package contains information that can be used to invoke a method. How that method is called is not defined in the SOAP specification. SOAP also does not handle distributed garbage collection, message boxcarring, type safety, or bidirectional HTTP. What SOAP does allow you to do is pass parameters and commands between HTTP clients and servers, regardless of the platforms and applications on the client and server. The parameters and commands are encoded using XML. Let's take a look at how SOAP uses the standard HTTP headers.

Two types of headers are available in HTTP: request headers and response headers. When you are using your Web browser to surf the Internet, each time you navigate to a new URL the Web browser will create a request and send it to the Web server. These requests are written in plain text; each has headers in a standard format. When creating SOAP messages, you will be adding additional information to these standard formats. HTTP servers generate a response message upon receiving the client request. This message contains a status line and response headers. Let's look at the two headers in more detail.

A typical HTTP message in a SOAP request being passed to a Web server looks like this:

  POST /Order HTTP/1.1
  Host: www.northwindtraders.com
  Content-Type: text/xml
  Content-Length: nnnn
  SOAPAction: "urn:northwindtraders.com:PO#UpdatePO"

  Information being sent would be located here.
  

The first line of the message contains three separate components: the request method, the request URI, and the protocol version. In this case, the request method is POST; the request URI is /Order; and the version number is HTTP/1.1. The Internet Engineering Task Force (IETF) has standardized the request methods. The GET method is commonly used to retrieve information on the Web. The POST method is used to pass information from the client to the server. The information passed by the POST method is then used by applications on the server. Only certain types of information can be sent using GET; any type of data can be sent using POST. SOAP also supports sending messages using M-POST. We'll discuss this method in detail later in this chapter. When working with the POST method in a SOAP package, the request URI actually contains the name of the method to be invoked.

The second line is the URL of the server that the request is being sent to. The request URL is implementation specific¡ªthat is, each server defines how it will interpret the request URL. In the case of a SOAP package, the request URL usually represents the name of the object that contains the method being called.

The third line contains the content type, text/xml, which indicates that the payload is XML in plain text format. The payload refers to the essential data being carried to the destination. The payload information could be used by a server or a firewall to validate the incoming message. A SOAP request must use the text/xml as its content type. The fourth line specifies the size of the payload in bytes. The content type and content length are required with a payload.

The SOAPAction header field must be used in a SOAP request to specify the intent of the SOAP HTTP request. The fifth line of the message, SOAPAction: "urn: northwindtraders.com:PO#UpdatePO", is a namespace followed by the method name. By combining this namespace with the request URL, our example calls the UpdatePO method of the Order object and is scoped by the urn:northwindtraders.com:PO namespace URI. The following are also valid SOAPAction header field values:

  SOAPAction: "UpdatePO"
  SOAPAction: ""
  SOAPAction:
  

The header field value of the empty string means that the HTTP request URI provides the intent of the SOAP message. A header field without a specified value indicates that the intent of the SOAP message isn't available.

Notice that there is a single blank line between the fifth line and the payload request. When you are working with message headers, the carriage-return/line-feed sequence delimits the headers and an extra carriage-return/line-feed sequence is used to signify that the header information is complete and that what follows is the payload.

A typical response message that contains the response headers is shown here:

  200 OK
  Content-Type: text/plain
  Content-Length: nnnn

  Content goes here.
  

The first line of this message contains a status code and a message associated with that status code. In this case, the status code is 200 and the message is OK, meaning that the request was successfully decoded and that an appropriate response was returned. If an error had occurred, the following headers might have been returned:

  400 Bad Request
  Content-Type: text/plain
  Content-Length: 0
  

In this case, the status code is 400 and the message is Bad Request, meaning that the request cannot be decoded by the server because of incorrect syntax. You can find other standard status codes in RFC 2616.

As you can see, SOAP uses HTTP as the request/response messaging transport. We can add a SOAP request payload in the request message and a response payload in the response message. In this way, we can issue an RPC to any component using HTTP.

The SOAP specification defines several SOAP elements that can be used with a SOAP request: envelope, head, and body. The envelope is a container for the head and body. The head contains information about the SOAP message, and the body contains the actual message. Namespaces are used to distinguish the SOAP elements from the other elements of the payload. For example, SOAP-ENV:Envelope, SOAP-ENV:Head, and SOAP-ENV:Body are used in a SOAP document.

The SOAP schema for the envelope will look as follows:

  <?xml version="1.0" ?>
  <!-- XML Schema for SOAP v 1.1 Envelope -->
  <!-- Copyright 2000 DevelopMentor, International Business
  Machines Corporation, Lotus Development Corporation,
  Microsoft, UserLand Software -->
  <schema xmlns="http://www.w3.org/1999/XMLSchema"
      xmlns:tns="http://schemas.xmlsoap.org/soap/envelope/"
      targetNamespace="http://schemas.xmlsoap.org/soap/envelope/">
      <!-- SOAP envelope, header, and body -->
      <element name="Envelope" type="tns:Envelope"/>
      <complexType name="Envelope">
          <element ref="tns:Header" minOccurs="0"/>
          <element ref="tns:Body" minOccurs="1"/>
          <any minOccurs="0" maxOccurs="*"/>
          <anyAttribute/>
      </complexType>
      <element name="Header" type="tns:Header"/>
      <complexType name="Header">
          <any minOccurs="0" maxOccurs="*"/>
          <anyAttribute/>
      </complexType>
      <element name="Body" type="tns:Body"/>
      <complexType name="Body">
          <any minOccurs="0" maxOccurs="*"/>
          <anyAttribute/>
      </complexType>
      <!-- Global Attributes.  The following attributes are 
           intended to be usable via qualified attribute names on 
           any complex type referencing them.
      -->
      <attribute name="mustUnderstand" default="0">
          <simpleType base="boolean">
              <pattern value="0|1"/>
          </simpleType>
      </attribute>
      <attribute name="actor" type="uri-reference"/>
      <!-- 'encodingStyle' indicates any canonicalization
       conventions followed in the contents of the containing
       element.  For example, the value
       'http://schemas.xmlsoap.org/soap/encoding/' indicates 
       the pattern described in SOAP specification.
      -->
  <simpleType name="encodingStyle" base="uri-reference"
      derivedBy="list"/>
      <attributeGroup name="encodingStyle">
          <attribute name="encodingStyle" 
              type="tns:encodingStyle"/> 
      </attributeGroup>
      <!-- SOAP fault reporting structure -->
      <complexType name="Fault" final="extension">
          <element name="faultcode" type="qname"/>
          <element name="faultstring" type="string"/>
          <element name="faultactor" type="uri-reference"
              minOccurs="0"/> 
          <element name="detail" type="tns:detail" minOccurs="0"/>
      </complexType>
      <complexType name="detail">
          <any minOccurs="0" maxOccurs="*"/>
          <anyAttribute/>
      </complexType>
  </schema>
  

A SOAP request including the payload defined in the schema would look like this:

  POST /Order HTTP/1.1
  Host: www.northwindtraders.com
  Content-Type: text/xml
  Content-Length: nnnn
  SOAPAction: "urn:northwindtraders.com:PO#UpdatePO"

  <SOAP-ENV:Envelope
  xmlns:xsi="http://www.w3.org/1999/XMLSchema/instance"
     xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope"
     xsi:schemaLocation=
        "http://www.northwindtraders.com/schemas/NPOSchema.xsd">
     <SOAP-ENV:Body xsi:type="NorthwindBody">
        <UpdatePO>
           <orderID>0</orderID>
           <customerNumber>999</customerNumber>
           <item>89</item>
           <quantity>3000</quantity>
           <return>0</return>
        </UpdatePO>
     </SOAP-ENV:Body>
  </SOAP-ENV:Envelope>
  

Because the Body element contains the any element in the SOAP schema, you could also have written SOAP body as follows:

  <SOAP-ENV:Envelope
     xmlns:xsi="http://www.w3.org/1999/XMLSchema/instance"
     xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope">
     <SOAP-ENV:Body xsi:type="NorthwindBody">
        <m:UpdatePO xmlns:m= 
           "http://www.northwindtraders.com/schemas/NPOSchema.xsd">
           <orderID>0</orderID>
           <customerNumber>999</customerNumber>
           <item>89</item>
           <quantity>3000</quantity>
           <return>0</return>
        </m:UpdatePO>
     </SOAP-ENV:Body>
  </SOAP-ENV:Envelope>
  

As you can see, the payload of a SOAP request is an XML document that contains the parameter values of the method. The HTTP header of this package has identified the UpdatePO method of the Order object as the recipient of this method call. The top-level element of the method call must have the same name as the method identified in SOAPAction.

The elements contained within the top element are the parameters for the method. The preceding example contains four parameters: orderID, customerNumber, item, and quantity. In Microsoft Visual Basic, this method could be written as follows:

  Public Sub UpdatePO(byval orderID as Integer, _
      byval customerNumber as Integer, _
      byval item as Integer, _
      byval quantity as Integer, _
      byref return as Integer)
  

In Java, this method would look like this:

  public class UpdatePO {public int orderID;
      public int customerNumber;
      public int item;
      public int quantity;
      public int return;}
  

When you are building the request, you will include one element for each in or in/out parameter. This technique of associating one element with each parameter is also known as the element-normal form (ENF). The name of each element is the name of the parameter the element is associated with.

The request can also contain a header element that includes additional information. There are no predefined elements in the header element¡ªyou can include any element you want, as long as it is either prefixed by a namespace or the header type is overridden using xsi:type and a type defined in a schema.

We can add a header element to our payload example as shown here:

  <SOAP-ENV:Envelope 
     xmlns:xsi="http://www.w3.org/1999/XMLSchema/instance"
     xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope"
     xsi:schemaLocation=
        "http://www.northwindtraders.com/schemas/NPOSchema.xsd">
     <SOAP-ENV:Header xsi:type="NorthwindHeader">
        <GUID>
        10000000-0000-abcd-0000-000000000001
        </GUID>
     </SOAP-ENV:Header>
     <SOAP-ENV:Body xsi:type="NorthwindBody">
        <UpdatePO>
           <orderID>0</orderID>
           <customerNumber>999</customerNumber>
           <item>89</item>
           <quantity>3000</quantity>
           <return>0</return>
        </UpdatePO>
     </SOAP-ENV:Body>
  </SOAP-ENV:Envelope>
  

Because the any element is used in the header element in the SOAP schema, we could also rewrite the SOAP header as follows:

  <SOAP-ENV:Header>
        <COM:GUID xmlns:COM="http://comobject.Northwindtraders.com">
           10000000-0000-abcd-0000-000000000001
        </COM:GUID>
  </SOAP-ENV:Header>
  

In this case, we have created an element named GUID. It will be up to the receiving application to interpret this header, but it's likely that it will be used to instantiate the correct COM object. These additional elements can be considered processing instructions.

You can include a predefined attribute named mustUnderstand as an attribute of a header element. The mustUnderstand attribute can be used to indicate whether the header information is essential for processing of the information. If the header information is essential, mustUnderstand should be set to true. If the receiving element cannot recognize the processing instruction and mustUnderstand is set to 1, the message must be rejected. Thus, we could have the following header element:

  <SOAP-ENV:Header xsi:type="Transaction">
        <transactionID mustUnderstand="1">
           10000000
        </transactionID >
  </SOAP-ENV:Header>
  

In this case, we are creating an element named TransactionID. This element must be understood by the receiving application, or the message will be rejected.

You can restrict messages coming through a firewall or a proxy server by using the MPOST method instead of POST. M-POST is a new HTTP method defined using the HTTP Extension Framework located at http://www.w3.org/Protocols/HTTP/ietf-ext-wg. This method is used when you are including mandatory information in the HTTP header, just as you used the mustUnderstand attribute in the SOAP header element.

As we mentioned, SOAP supports both POST and M-POST requests. A client first makes a SOAP request using M-POST. If the request fails and either a 501 status code (Not Implemented status message) or a 510 status code (Not Extended status message) returns, the client should retry the request using the POST method. If the client fails the request again and a 405 status code (Method Not Allowed status message) returns, the client should fail the request. If the returning status code is 200, the message has been received successfully. Firewalls can force a client to use the M-POST method to submit SOAP requests by blocking regular POSTs of the text/xml-SOAP content type.

If you use M-POST, you must use a mandatory extension declaration that refers to a namespace in the Envelope element declaration. The namespace prefix must precede the mandatory headers. The following example illustrates how to use M-POST and the mandatory headers:

  M-POST /Order HTTP/1.1
  Host: www.northwindtraders.com
  Content-Type: text/xml
  Content-Length: nnnn
  Man: "http://schemas.xmlsoap.org/soap/envelope; ns=49"
  49-SOAPAction: "urn:northwindtraders.com:PO#UpdatePO"
  

The Man header maps the URI http://schemas.xmlsoap.org/soap/envelope to the header prefix 49. Any header that has a prefix of 49 will be associated with this URI and will therefore be a mandatory header. In this case, the SOAPAction will be associated with the URI and is a mandatory header.

discuss this topic to forum