Introduction to Simple Object Access Protocol

Similar to the WSDL definition, we visit the SOAP constructs, which are important in context of service-centric architecture. Especially, we discuss the constructs that add flexibility to a service-centric architecture and provide mechanisms for better B2B implementation.

Note

A SOAP message is an XML document that consists of a mandatory SOAP envelope, an optional SOAP header, and a mandatory SOAP body. This XML document is referred to as a SOAP message as per the SOAP specification.

A SOAP message contains the following:

• Envelope The envelope is the root element of the XML document representing the message. The element must be present in a SOAP message and may contain namespace declarations and additional attributes. The envelope contains an optional SOAP header, and a mandatory SOAP body.

• Header 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 certain header attributes that can be used to indicate who should deal with a given feature and whether it is optional or mandatory. The Header element is optional in a SOAP message. If present, the element must be the first immediate child element of a SOAP Envelope element. It may contain a set of header entries, each being an immediate child element of the SOAP Header element. The child elements must be namespace-qualified. The header entries are an extensibility feature that are leveraged to provide semantic information to nodes along a message path; it may also carry information necessary for infrastructure components that provide transactional and security semantics.

• Body The body is a container for mandatory information intended for the ultimate recipient of the message. The Fault element is subordinate to the Body element, and is used for reporting errors. The Body element must be present in a SOAP message. When the Header element is present, the Body element must directly follow the Header element; otherwise the Body element must be the first immediate child element of the Envelope element. This element may contain a set of body entries, each being an immediate child element of the Body element.

For the MyService example, a SOAP request message that accesses the operation foo(2222) exposed by MyService will take the following form:

 <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:foo xmlns:m="http://www.openuri.org/">                  <arg>2222</arg>           </m:foo>    </SOAP-ENV:Body> </SOAP-ENV:Envelope> 

The correlated SOAP response received back from the service will take the following form:

 <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:fooResponse xmlns:m="http://www.openuri.org/">                  <fooResult>2222</fooResult>           </m:fooResponse>    </SOAP-ENV:Body> </SOAP-ENV:Envelope> 

In the following subsection, we examine SOAP message constructs that are architecturally significant in designing a Web service.

SOAP Envelope

The SOAP envelope defines the overall framework for expressing what is in a message, who should deal with the message, and whether parts of the message are optional or mandatory. The SOAP encodingStyle global attribute (specified using the namespace declaration SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/") can be used to indicate the serialization rules used in a SOAP message. 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. There is no default encoding defined for a SOAP message. The attribute value is an ordered list of one or more URIs; these URIs identify the serialization rules that can be used to deserialize the SOAP message indicated in the order of most specific to least specific.

SOAP Header

The SOAP header provides an extension mechanism for adding additional semantics to a SOAP message when such information cannot be ordinarily added to the SOAP body, or it is inappropriate to add such information to the SOAP body. When a SOAP message follows a message path—that is, it travels from the originator to its final destination—it can potentially pass through a set of SOAP intermediaries that fall along the message path. A SOAP intermediary is an application that is capable of both receiving and forwarding SOAP messages. The role of a recipient of a Header element is similar to that of accepting a contract in that it cannot be extended beyond the recipient; this is because the meaning of the header is understood only between the sender and the recipient. This does not preclude the recipient from adding a Header element when it forwards the message to another node; in this case the contract is between the sender application and the recipient of that Header element. Examples of extensions that can be implemented as header entries are security context, transaction context, and so on.

For example, an originating service constructs a Header element targeted for an authentication service along the message path; the authentication service performs authentication, and if the authentication is successful, it forwards the SOAP message to the next destination in the message path. The SOAP global attribute ‘actor’ can be used to indicate the recipient of a Header element. The value of the SOAP ‘actor’ attribute is a URI. Omitting the ‘actor’ attribute implies that the recipient is the ultimate destination of the SOAP message. When the SOAP ‘actor’ attribute is set to the special URI http://schemas.xmlsoap.org/soap/actor/ next, it indicates that the Header element is intended for the very first SOAP application that Connection header field in HTTP. The SOAP Header element has a significant architectural feature. It can be used to build a complex B2B system where numerous Web services are collaborating to realize a set of complex business functions. The SOAP mustUnderstand global attribute indicates whether a header entry is mandatory or optional for the recipient to process. If the mustUnderstand attribute has the value "1", the recipient of the header entry must either obey the semantics and process the header entry correctly or must fail processing the message. In the following representation of a SOAP message, the Header element contains a header entry Transaction; this header entry's meaning is known only to the receiving application that may be capable of dealing with the transactional context of the caller.

 <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">             1234        </t:Transaction>    </SOAP-ENV:Header>    <SOAP-ENV:Body>          ... body entries ...    </SOAP-ENV:Body> </SOAP-ENV:Envelope> 

SOAP Body

According to the SOAP specification, 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. 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. SOAP defines one body entry called the fault entry used for reporting errors. 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.

• The SOAP encodingStyle attribute may be used to indicate the encoding style used for the body entries.

The following example illustrates a SOAP message in which the function foo exposed by the Web service is being accessed; the function takes an integer value as parameter. You will recall from our WSDL discussion how WSDL will be used in the creation of stubs and proxies that will understand the semantics embedded in this SOAP message.

 <SOAP-ENV:Envelope   xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"   SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>     <SOAP-ENV:Header>           ... header entries ...     </SOAP-ENV:Header>     <SOAP-ENV:Body>           <m:foo xmlns:m="http://www.openuri.org/">              <arg>2222</arg>           </m:foo>    </SOAP-ENV:Body> </SOAP-ENV:Envelope> 

SOAPFault

The SOAP Fault element defines the following four sub-elements:

• faultcode Intended for use by software to provide an algorithmic mechanism for identifying the fault.

• faultstring Intended to provide a human readable explanation of the fault and is not intended for algorithmic processing.

• faultactor Intended to provide information about who caused the fault to happen within the message path.

• detail Intended for carrying the 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. 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 where the problem could be with the server process and not the Body element itself.

The following demonstrates the use of the Fault element. If we call the MyService Web service, whose foo operation expects an integer value, with a bad string like "garbageString", we receive the following SOAP response:

 <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:ServiceError</faultcode>            <faultstring>Invalid request</faultstring>            <detail>Error deserializing arguments. 'garbageString' is not                 a valid encoding for type java.lang.Integer</detail>         </SOAP-ENV:Fault     > </SOAP-ENV:Body> </SOAP-ENV:Envelope>