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 Envelope is the top element of the XML document representing the message.
The Header is a generic mechanism for adding features to a SOAP message in a decentralized
manner without prior agreement between the communicating parties. SOAP defines a few attributes that can be used to
indicate who should deal with a feature and whether it is optional or mandatory. NOTE: Header
element is OPTIONAL.
The Body is a container for mandatory information intended for the ultimate recipient
of the message. SOAP defines one element for the body, which is the Fault element used for
reporting errors. NOTE: Body element is MANDATORY and MUST be exactly 1 per message.
The grammar rules are as follows:
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>
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>
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:
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.
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:
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.
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.
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.
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:
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.
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
| Error | Description |
|---|
| VersionMismatch |
The processing party found an invalid namespace for the SOAP Envelope element.
|
| MustUnderstand | An 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>
