SCDJWS Study Guide: SOAP
The Basic Structure of SOAP
SOAP messages are transmitted between applications and may pass through a number of intermediaries as they travel from the initial sender to the ultimate recipient.
A SOAP message, represented by the Envelope element, contains an optional Header and a mandatory Body child element. The Body element can contain a number of body entries (The optional Fault child element of Body element is present only in messages that report a processing exception).
The Envelope element identifies the XML as being a SOAP message and must be the root element of the SOAP message. The Body element contains the message payload which is the actual application data being exchanged between applications. The Header element provides an extension hook that allows SOAP to be extended in arbitrary ways. If a Header element is presented, it must be the immediate child of the Envelop element and precede the Body element.
The structure of a Basic SOAP message is shown in the following Listing:
<?xml version=”1.0” encoding=”UTF-8”?>
<!-- extensions of Header blocks go here -->
<!-- message payload goes here -->
The element of SOAP message is shown in the following table:
||Root element of the SOAP message.|
||Encloses header entrues.
||Header entries provide additional information on the message’s content. For example, digital signatures, authorization data, and so on.|
||Encloses the message's body
||Body entries make up the content of the message. Their element names depend on the message’s content.|
||entry used to report a problem. When used, no other body entry can be present.|
||Indicates the reason for the fault. Intended for application use.|
||Human-readable version of the fault reason.|
||Indicates which entity along the message path raised the fault.|
||Encloses detail entries
||Contain application-specific information about the fault.|
SOAP has its own XML schema, namespace http://schemas.xmlsoap.org/soap/envelope, and processing rules.
As can be seen, SOAP messages rely heavily on XML Namespaces. All of the elements in our XML document are prefixed with the namespace soap, and there is a good reason why the SOAP specification uses namespaces so extensively. In order for a SOAP message to carry any arbitrary XML payload, all the elements of the message must be scoped in some fashion to avoid conflicts in the names of elements.
The Namespaces in XML Recommendation can be found at http://www.w3.org/TR/REC-xml-names/.
The namespace prefix soap is used on most of the elements in the above message. The prefix is associated with the namespace URI http://schemas.xmlsoap.org/soap/envelope/, and it identifies the elements that are part of a standard SOAP message. Like all namespace prefixes, the choice of soap is irrelevant. The namespace prefix could have been something else entirely. The namespace prefix could also be eliminated completely if the namespace is the default namespace for the document.
- A SOAP message may have an XML declaration <?xml …?>, which states the version of XML used and the encoding format. The version of XML must be 1.0 and the encoding must be either UTF-8 (default) or UTF-16. The XML declaration must at the first line of the SOAP message document.
- A SOAP message adheres to the SOAP 1.1 XML schema, which requires that elements and attributes be fully qualified (use prefixes or default namespaces).
- The Envelope element is the root element of the SOAP message. It contains one and only one Body element preceded by zero or one Header element. If the Header element is used, it must be the immediate child of the Envelope element.
- The Envelope element can not contain any other children elements other than Header and Body elements.
The interpretation of sibling elements following the soap:Body
element is unclear. Therefore, such elements are disallowed. [WS-I
Basic Profile 1.0]
||A MESSAGE MUST NOT have any element children of soap:Envelope following the soap:Body.|
All the attributes that the SOAP envelope schema defines are global (they are not associated with a particular element). Also, each element in a SOAP message is free to use any attribute, regardless of where it’s defined, either in SOAP’s schema or another one, which is one of SOAP’s extensibility features. This means that elements are free to use any number of attributes. The following table describes the attributes that the SOAP specification defines.
||Specifies the entity that is to process the element. When absent, the actor is the ultimate recipient of the message. This attribute is used mainly to assign header entries to specific entities.|
||0 or 1
||Indicates whether the element’s actor must process the element. When set to 1 and if the actor is unable to process the element, the actor must respond with a Fault.|
||A list of URIs
||Indicates the encoding style used for the element’s content.|
The soap:mustUnderstand attribute has a restricted type of “xsd:Boolean” that takes only “0” or “1”. Therefore, only those two values are allowed. [WS-I Basic Profile 1.0]
||A MESSAGE containing a soap:mustUnderstand attribute Must only use the lexical forms “0” and “1”|