This chapter is from the book
This chapter is from the book
This chapter is from the book
10.2 Elements in SOAP messages
SOAP defines four elements in the namespace http://schemas.xmlsoap.org/soap/envelope/. These elements are listed in the following sections in alphabetical order, with a description and details of child elements. All four elements can be annotated with any number of namespace-qualified attributes. Example SOAP request and response messages are shown for reference.
10.2.1 Body
<soap:Body xmlns:soap='http://schemas.xmlsoap.org/soap/envelope/' > <!-- message payload goes here --> </soap:Body>
The Body element contains the message payload. In the case of a request message the payload of the message is processed by the receiver of the message and is typically a request to perform some service and, optionally, to return some results. In the case of a response message the payload is typically the results of some previous request or a fault.
Child elements
One or more namespace-qualified elements that are not in the http://schemas.xmlsoap.org/soap/envelope/ namespace or, if a fault occurred, a Fault element in the http://schemas.xmlsoap.org/soap/envelope/ namespace
Examples A SOAP request
<soap:Envelope
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
soap:encodingStyle='http://schemas.xmlsoap.org/soap/encoding/'>
<soap:Body>
<m:Subtract
xmlns:m="http://example.org/Calculator/Points">
<pt1>
<x>10</x>
<y>20</y>
</pt1>
<pt2>
<x>100</x>
<y>200</y>
</pt2>
</m:Subtract>
</soap:Body>
</soap:Envelope>
An example request message showing the Envelope and Body elements
A SOAP response
<soap:Envelope
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
soap:encodingStyle='http://schemas.xmlsoap.org/soap/encoding/'>
<soap:Body>
<method:SubtractResponse
xmlns:method="http://example.org/Calculator/Points">
<ptret>
<x>-90</x>
<y>-180</y>
</ptret>
</method:SubtractResponse>
</soap:Body>
</soap:Envelope>
A message generated in response to the request message in the request example
10.2.2 Envelope
<soap:Envelope xmlns:soap='http://schemas.xmlsoap.org/soap/envelope/' > <!-- header and body go here --> </soap:Envelope>
The Envelope element is the root element for all SOAP messages, identifying the XML as a SOAP message.
Child elements
An optional Header element and a mandatory Body element. Both elements are in the http://schemas.xmlsoap.org/soap/envelope/ namespace.
10.2.3 Fault
<soap:Fault xmlns:soap='http://schemas.xmlsoap.org/soap/envelope/' > <!-- detail goes here --> </soap:Fault>
The Fault element indicates that an error occurred while processing a SOAP request. This element only appears in response messages.
Child elements
A faultcode element followed by a faultstring element followed by an optional faultactor element and an optional detail element. Each of these children is described in the following:
|
Name |
Syntax |
Description |
|
faultcode |
<faultcode xmlns=''> |
The faultcode element is of type QName and indicates what fault occurred. Several existing categories of fault code are defined, all in the http://schemas.xmlsoap.org/soap/envelope/ namespace. VersionMismatch indicates that the recipient of a message did not recognize the namespace name of the Envelope element. MustUnderstand indicates that the recipient of an element child of the Header element had a soap:mustUnderstand attribute but that element was not understood by the recipient. Client indicates the SOAP message did not contain all the required information in order for the recipient to process it. This could mean that something was missing from inside the Body element. Equally, an expected extension inside the Header element could have been missing. In either case, the sender should not resend the message without correcting the problem. Server indicates that the recipient of the message was unable to process the message because of some server-side problem. The message contents were not at fault; rather, some resource was unavailable or some processing logic failed for a reason other than an error in the message. The sender may legitimately resend the message at a later time. All these fault codes may be followed by a period and a further string providing more detailed information about the error; for example, Client.InvalidParameter. |
|
faultstring |
<faultstring xmlns=''> |
The faultstring element is of type string and provides a human-readable description of whatever fault occurred. |
|
faultactor |
<faultactor xmlns=''> |
The faultactor element is of type uriReference and indicates the source of the fault. This may be the ultimate recipient of the request message, in which case the element is optional. Alternatively, the source of the fault may be an intermediary somewhere in the path the message took to get from the sender to the ultimate recipient. In this case the element must be present. |
|
detail |
<detail xmlns=''> any number of elements in any namespace </detail> |
The detail element is used to carry application-specific error information and may be annotated with any number of attributes from any namespace, and may have any number of namespace-qualified element children. The detail element must be present if the fault is the result of the recipient being unable to process the Body element. The detail element is not used to provide error information in the case of the recipient being unable to process an element child of the Header element. In such cases, error information is placed inside the Header element. |
Example A SOAP fault
<soap:Envelope
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
soap:encodingStyle='http://schemas.xmlsoap.org/soap/encoding/'>
<soap:Body>
<soap:Fault>
<faultcode>soap:Client.InvalidRequest</faultcode>
<faultstring>Invalid Request: Divide operation not
supported</faultstring>
<faultactor>http://marting.develop.com/soap/
calcxslt.asp</faultactor>
<detail>
<m:MethodError
xmlns:m='uuid:361C5CDE-FC66-4B17-A2C1-EB221DEFFD66'>
<request>Divide</request>
<reason>Operation not supported</reason>
</m:MethodError>
</detail>
</soap:Fault>
</soap:Body>
</soap:Envelope>
An example of a fault in which the request message contained an invalid operation request
10.2.4 Header
<soap:Header xmlns:soap='http://schemas.xmlsoap.org/soap/envelope/' > <!-- extensions go here --> </soap:Header>
The Header element namespace serves as a container for extensions to SOAP. No extensions are defined by the specification, but user-defined extension services such as transaction support, locale information, authentication, digital signatures, and so forth could all be implemented by placing some information inside the Header element. Children of the Header element may be annotated with the mustUnderstand and/or actor attributes.
Child elements
Any number of namespace-qualified elements that are not in the http://schemas.xmlsoap.org/soap/envelope/ namespace
Example A SOAP Header
<soap:Envelope
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
soap:encodingStyle='http://schemas.xmlsoap.org/soap/encoding/'>
<soap:Header>
<x:Locale
xmlns:x='http://example.org/Extensions/Locale'>
<language>en</language>
<sublang>uk</sublang>
</x:Locale>
</soap:Header>
<soap:Body>
<!-- message payload goes here -->
</soap:Body>
</soap:Envelope>
An example extension for locale information requesting that the recipient of the message send any responses localized for the specified locale; in this case, UK English.