Describe the function of each element contained in a SOAP message, the SOAP binding to HTTP, and how to represent faults that occur when processing a SOAP message.

A SOAP message is an XML document that consists of a mandatory SOAP envelope, an optional SOAP header, and a mandatory SOAP body. The namespace identifier for the elements and attributes from SOAP message is "http://schemas.xmlsoap.org/soap/envelope/". A SOAP message contains the following:

The grammar rules are as follows:

  1. Envelope

    • The element name is "Envelope".

    • The element MUST be present in a SOAP message.

    • The element MAY contain namespace declarations as well as additional attributes. If present, such additional attributes MUST be namespace-qualified. Similarly, the element MAY contain additional sub elements. If present these elements MUST be namespace-qualified and MUST follow the SOAP Body element.

    								
    <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" 
               xmlns:tns="http://schemas.xmlsoap.org/soap/envelope/" 
               targetNamespace="http://schemas.xmlsoap.org/soap/envelope/">
    
      <xs:complexType name="Envelope">
        <xs:sequence>
          <xs:element ref="tns:Header" minOccurs="0" />
          <xs:element ref="tns:Body" minOccurs="1" />
          <xs:any namespace="##other" minOccurs="0" maxOccurs="unbounded" processContents="lax" />
        </xs:sequence>
        <xs:anyAttribute namespace="##other" processContents="lax" /> 
      </xs:complexType>  
      ....  
    </xs:schema> 
    
    								

  2. Header

    • The element name is "Header".

    • The element MAY be present in a SOAP message. If present, the element MUST be the first immediate child element of a SOAP Envelope element.

    • The element MAY contain a set of header entries each being an immediate child element of the SOAP Header element. All immediate child elements of the SOAP Header element MUST be namespace-qualified.

      NOTE: WS-I BP 1.0 requires all immediate children of Header element be namespace qualified.

    								
    <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" 
               xmlns:tns="http://schemas.xmlsoap.org/soap/envelope/" 
               targetNamespace="http://schemas.xmlsoap.org/soap/envelope/">           
      ....
      <xs:complexType name="Header">
        <xs:sequence>
          <xs:any namespace="##other" minOccurs="0" maxOccurs="unbounded" processContents="lax" /> 
        </xs:sequence>
        <xs:anyAttribute namespace="##other" processContents="lax" /> 
      </xs:complexType>  
      ....  
    </xs:schema> 
    
    								

  3. Body

    • The element name is "Body".

    • The element MUST be present in a SOAP message and MUST be an immediate child element of a SOAP Envelope element. It MUST directly follow the SOAP Header element if present. Otherwise it MUST be the first immediate child element of the SOAP Envelope element.

    • The element MAY contain a set of body entries each being an immediate child element of the SOAP Body element. Immediate child elements of the SOAP Body element MAY be namespace-qualified. SOAP defines the SOAP Fault element, which is used to indicate error messages.

      NOTE: WS-I BP 1.0 requires all immediate children of Body element be namespace qualified.

    								
    <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" 
               xmlns:tns="http://schemas.xmlsoap.org/soap/envelope/" 
               targetNamespace="http://schemas.xmlsoap.org/soap/envelope/">           
      ....
      <xs:complexType name="Body">
        <xs:sequence>
          <xs:any namespace="##any" minOccurs="0" maxOccurs="unbounded" processContents="lax" /> 
        </xs:sequence>
        <xs:anyAttribute namespace="##any" processContents="lax">
          <xs:annotation>
            <xs:documentation>
              Prose in the spec does not specify that attributes are allowed on 
              the Body element
            </xs:documentation> 
          </xs:annotation>
        </xs:anyAttribute>
      </xs:complexType>  
      ....  
    </xs:schema> 
    
    								

The SOAP Body element provides a simple mechanism for exchanging mandatory information intended for the ultimate recipient of the message. Typical uses of the Body element include marshalling RPC calls and error reporting. The Body element is encoded as an immediate child element of the SOAP Envelope XML element. If a Header element is present then the Body element MUST immediately follow the Header element, otherwise it MUST be the first immediate child element of the Envelope element. All immediate child elements of the Body element are called body entries and each body entry is encoded as an independent element within the SOAP Body element. The encoding rules for body entries are as follows:

  1. A body entry is identified by its fully qualified element name, which consists of the namespace URI and the local name. Immediate child elements of the SOAP Body element MAY be namespace-qualified.

    NOTE: WS-I BP 1.0 requires all immediate children of Body element be namespace qualified.

  2. The SOAP encodingStyle attribute MAY be used to indicate the encoding style used for the body entries (this attribute MAY appear on any element, and is scoped to that element's contents and all child elements not themselves containing such an attribute, much as an XML namespace declaration is scoped).

SOAP Fault

SOAP defines one body entry, which is the Fault entry used for reporting errors. Here is schema definition of Fault element:


<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" 
           xmlns:tns="http://schemas.xmlsoap.org/soap/envelope/" 
           targetNamespace="http://schemas.xmlsoap.org/soap/envelope/">           
  ....
  <xs:complexType name="Fault" final="extension">
    <xs:annotation>
      <xs:documentation>Fault reporting structure</xs:documentation> 
    </xs:annotation>
    <xs:sequence>
      <xs:element name="faultcode" type="xs:QName" /> 
      <xs:element name="faultstring" type="xs:string" /> 
      <xs:element name="faultactor" type="xs:anyURI" minOccurs="0" /> 
      <xs:element name="detail" type="tns:detail" minOccurs="0" /> 
    </xs:sequence>
  </xs:complexType>
  ....  
</xs:schema> 

					

The SOAP Fault element is used to carry error and/or status information within a SOAP message. If present, the SOAP Fault element MUST appear as a body entry and MUST NOT appear more than once within a Body element. The SOAP Fault element defines the following four subelements:

  1. faultcode - The faultcode element is intended for use by software to provide an algorithmic mechanism for identifying the fault. The faultcode MUST be present in a SOAP Fault element and the faultcode value MUST be a qualified name. SOAP defines a small set of SOAP fault codes covering basic SOAP faults.

  2. faultstring - The faultstring element is intended to provide a human readable explanation of the fault and is not intended for algorithmic processing. The faultstring element is similar to the 'Reason-Phrase' defined by HTTP. It MUST be present in a SOAP Fault element and SHOULD provide at least some information explaining the nature of the fault.

  3. faultactor - The faultactor element is intended to provide information about who caused the fault to happen within the message path. It is similar to the SOAP actor attribute but instead of indicating the destination of the header entry, it indicates the source of the fault. The value of the faultactor attribute is a URI identifying the source. Applications that do not act as the ultimate destination of the SOAP message MUST include the faultactor element in a SOAP Fault element. The ultimate destination of a message MAY use the faultactor element to indicate explicitly that it generated the fault.

  4. detail - The detail element is intended for carrying application specific error information related to the Body element. It MUST be present if the contents of the Body element could not be successfully processed. It MUST NOT be used to carry information about error information belonging to header entries. Detailed error information belonging to header entries MUST be carried within header entries. The absence of the detail element in the Fault element indicates that the fault is not related to processing of the Body element. This can be used to distinguish whether the Body element was processed or not in case of a fault situation. All immediate child elements of the detail element are called detail entries and each detail entry is encoded as an independent element within the detail element.

    
    <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" 
               xmlns:tns="http://schemas.xmlsoap.org/soap/envelope/" 
               targetNamespace="http://schemas.xmlsoap.org/soap/envelope/">           
      ....
      <xs:complexType name="detail">
        <xs:sequence>
          <xs:any namespace="##any" minOccurs="0" maxOccurs="unbounded" processContents="lax" /> 
        </xs:sequence>
        <xs:anyAttribute namespace="##any" processContents="lax" /> 
      </xs:complexType>
      ....  
    </xs:schema> 
    
    								

    The encoding rules for detail entries are as follows:

    1. A detail entry is identified by its fully qualified element name, which consists of the namespace URI and the local name. Immediate child elements of the detail element MAY be namespace-qualified.

    2. The SOAP encodingStyle attribute MAY be used to indicate the encoding style used for the detail entries

The faultcode values MUST be used in the faultcode element when describing faults. The namespace identifier for these faultcode values is "http://schemas.xmlsoap.org/soap/envelope/". The default SOAP faultcode values are defined in an extensible manner that allows for new SOAP faultcode values to be defined while maintaining backwards compatibility with existing faultcode values. The mechanism used is very similar to the 1xx, 2xx, 3xx etc basic status classes classes defined in HTTP. However, instead of integers, they are defined as XML qualified names. The character "." (dot) is used as a separator of faultcode values indicating that what is to the left of the dot is a more generic fault code value than the value to the right. Example:

Client.Authentication
					
NOTE: WS-I BP 1.0 PROHIBITS the use of "dot" notation of faultcode element.

The set of predefined faultcode values is:

Table 2.2. SOAP Fault Codes

ErrorDescription
VersionMismatch The processing party found an invalid namespace for the SOAP Envelope element.
MustUnderstandAn immediate child element of the SOAP Header element that was either not understood or not obeyed by the processing party contained a SOAP mustUnderstand attribute with a value of "1".
Client The Client class of errors indicate that the message was incorrectly formed or did not contain the appropriate information in order to succeed. For example, the message could lack the proper authentication or payment information. It is generally an indication that the message should not be resent without change.
Server The Server class of errors indicate that the message could not be processed for reasons not directly attributable to the contents of the message itself but rather to the processing of the message. For example, processing could include communicating with an upstream processor, which didn't respond. The message may succeed at a later point in time.

NOTE: WS-I BP 1.0 ALLOWS using of custom values of faultcode element. In this case they MUST be fully qualified:


<faultcode>ns1:ProcessingError</faultcode>

					

Using SOAP in HTTP

Binding SOAP to HTTP provides the advantage of being able to use the formalism and decentralized flexibility of SOAP with the rich feature set of HTTP. Carrying SOAP in HTTP does not mean that SOAP overrides existing semantics of HTTP but rather that the semantics of SOAP over HTTP maps naturally to HTTP semantics.

SOAP naturally follows the HTTP request/response message model providing SOAP request parameters in a HTTP request and SOAP response parameters in a HTTP response. Note, however, that SOAP intermediaries are NOT the same as HTTP intermediaries. That is, an HTTP intermediary addressed with the HTTP Connection header field cannot be expected to inspect or process the SOAP entity body carried in the HTTP request.

HTTP applications MUST use the media type "text/xml" when including SOAP entity bodies in HTTP messages.

The SOAPAction HTTP request header field can be used to indicate the intent of the SOAP HTTP request. The value is a URI identifying the intent. SOAP places no restrictions on the format or specificity of the URI or that it is resolvable. An HTTP client MUST use this header field when issuing a SOAP HTTP Request.

The presence and content of the SOAPAction header field can be used by servers such as firewalls to appropriately filter SOAP request messages in HTTP. The header field value of empty string ("") means that the intent of the SOAP message is provided by the HTTP Request-URI. No value means that there is no indication of the intent of the message. Examples:

CORRECT:


SOAPAction: "http://electrocommerce.org/abc#MyMessage"

					
CORRECT:

SOAPAction: "myapp.sdl"

					
CORRECT (empty quoted string):

SOAPAction: ""

					
INCORRECT (SOAPAction value MUST be a quoted string):

SOAPAction:

					

SOAP HTTP follows the semantics of the HTTP Status codes for communicating status information in HTTP. For example, for a two-way operations a 2xx status code indicates that the client's request including the SOAP component was successfully received, understood, and accepted etc. In case of a SOAP error while processing the request, the SOAP HTTP server MUST issue an HTTP 500 "Internal Server Error" response and include a SOAP message in the response containing a SOAP Fault element indicating the SOAP processing error (for two-way operations only).

Below is an example of HTTP request, successful response and fault response of simple Web Service for retrieving Quote information.

Quote SOAP HTTP request:


POST /StockQuoteProj/servlet/rpcrouter HTTP/1.0
Host: localhost:9080
Content-Type: text/xml; charset=utf-8
Content-Length: 469
SOAPAction: ""

<?xml version='1.0' encoding='UTF-8'?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" 
                        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
                        xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <SOAP-ENV:Body>
    <ns1:getQuote xmlns:ns1="http://tempuri.org/StockQuoteService" 
                  SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
      <symbol xsi:type="xsd:string">ibm</symbol>
    </ns1:getQuote>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

					

NOTE: WS-I BP 1.0 MANDATES the use of HTTP POST method for SOAP messages sending.

Quote SOAP HTTP successful response:


HTTP/1.1 200 OK
Server: WebSphere Application Server/5.1
Content-Type: text/xml; charset=utf-8
Content-Length: 488
Content-Language: ru-RU
Connection: close

<?xml version='1.0' encoding='UTF-8'?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" 
                        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
                        xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <SOAP-ENV:Body>
    <ns1:getQuoteResponse xmlns:ns1="http://tempuri.org/StockQuoteService" 
             SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
      <return xsi:type="xsd:float">93.12</return>
    </ns1:getQuoteResponse>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

					

Quote SOAP HTTP fault response (exception is thrown by service endpoint object):


HTTP/1.1 500 Internal Server Error
Server: WebSphere Application Server/5.1
Expires: Thu, 01 Dec 1994 16:00:00 GMT
Set-Cookie: JSESSIONID=0000XEtXnz75hI--bFdY49XCHGU:-1;Path=/
Cache-Control: no-cache="set-cookie,set-cookie2"

<?xml version='1.0' encoding='UTF-8'?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" 
                        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
                        xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <SOAP-ENV:Body>
    <SOAP-ENV:Fault>
      <faultcode>SOAP-ENV:Server</faultcode>
      <faultstring>Exception from service object: null</faultstring>
      <faultactor>/StockQuoteProj/servlet/rpcrouter</faultactor>
    </SOAP-ENV:Fault>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

					

Example of SOAP HTTP request Using POST with a Mandatory Header:

								
POST /StockQuote HTTP/1.1
Host: www.stockquoteserver.com
Content-Type: text/xml; charset="utf-8"
Content-Length: nnnn
SOAPAction: "Some-URI"

<SOAP-ENV:Envelope  xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
            SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
  <SOAP-ENV:Header>
    <t:Transaction xmlns:t="some-URI" SOAP-ENV:mustUnderstand="1">
      12345
    </t:Transaction>
  </SOAP-ENV:Header>
  <SOAP-ENV:Body>
    <m:GetLastTradePrice xmlns:m="Some-URI">
      <symbol>DEF</symbol>
    </m:GetLastTradePrice>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

					

Example of SOAP HTTP request Using POST with multiple request parameters:

								
POST /StockQuote HTTP/1.1
Host: www.stockquoteserver.com
Content-Type: text/xml; charset="utf-8"
Content-Length: nnnn
SOAPAction: "Some-URI"

<SOAP-ENV:Envelope  xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
            SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
  <SOAP-ENV:Body>
    <m:GetLastTradePriceDetailed xmlns:m="Some-URI">
      <Symbol>IBM</Symbol>
      <Company>IBM Corp</Company>
    </m:GetLastTradePriceDetailed>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

					

Example of SOAP HTTP response with a Mandatory Header:

								
HTTP/1.1 200 OK
Content-Type: text/xml; charset="utf-8"
Content-Length: nnnn

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
           SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
  <SOAP-ENV:Header>
    <t:Transaction xmlns:t="some-URI" xsi:type="xsd:int" mustUnderstand="1">
      12345
    </t:Transaction>
  </SOAP-ENV:Header>
  <SOAP-ENV:Body>
    <m:GetLastTradePriceResponse xmlns:m="Some-URI">
      <Price>134.5</Price>
     </m:GetLastTradePriceResponse>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>


					

Example of SOAP HTTP response with a Struct:

								
HTTP/1.1 200 OK
Content-Type: text/xml; charset="utf-8"
Content-Length: nnnn

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
           SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
  <SOAP-ENV:Body>
    <m:GetLastTradePriceResponse xmlns:m="Some-URI">
      <PriceAndVolume>
        <LastTradePrice>
          134.5
        </LastTradePrice>
        <DayVolume>
          10000
        </DayVolume>
      </PriceAndVolume>
    </m:GetLastTradePriceResponse>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

					

Example of SOAP HTTP response Failing to honor Mandatory Header:

								
HTTP/1.1 500 Internal Server Error
Content-Type: text/xml; charset="utf-8"
Content-Length: nnnn

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
           SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
  <SOAP-ENV:Body>
    <SOAP-ENV:Fault>
      <faultcode>SOAP-ENV:MustUnderstand</faultcode>
      <faultstring>SOAP Must Understand Error</faultstring>
    </SOAP-ENV:Fault>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

					

Example of SOAP HTTP response Failing to handle Body:

								
HTTP/1.1 500 Internal Server Error
Content-Type: text/xml; charset="utf-8"
Content-Length: nnnn

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
           SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
  <SOAP-ENV:Body>
    <SOAP-ENV:Fault>
      <faultcode>SOAP-ENV:Server</faultcode>
      <faultstring>Server Error</faultstring>
      <detail>
        <e:myfaultdetails xmlns:e="Some-URI">
          <message>
            My application didn't work
          </message>
          <errorcode>
            1001
          </errorcode>
        </e:myfaultdetails>
      </detail>
    </SOAP-ENV:Fault>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

					

Professional hosting     Belorussian informational portal         Free SCWCD 1.4 Study Guide     Free SCBCD 1.3 Study Guide     SCDJWS 1.4 Quiz     Free IBM Certified Associate Developer Study Guide     Free SCJP 5.0 (Tiger) Study Guide     Free Mock Exam Engine     IBM Test 000-287. Enterprise Application Development with IBM WebSphere Studio, V5.0 Study Guide     IBM Test 000-255. Developing with IBM Rational Application Developer for WebSphere Software V6 Study Guide