Section 4.2. Architectural Concepts | Web Services Platform Architecture(c) SOAP, WSDL, WS-Policy, WS-Addressing, WS-BP[. .. ] More

4.2. Architectural Concepts

The SOAP version 1.2 specificationssimply called SOAP for the rest of this chapterintroduce a set of concepts to describe the protocol together with the transmission and receiving of encapsulated data. First, it's important to define some of the terms that are used later on to describe SOAP in more detail.

4.2.1. Defining Some Terms

SOAP is a set of conventions that specify a message format together with a set of rules that govern the processing of the message as it passes along a message path. The conventions describe how a message is assembled and what interactions SOAP nodes processing SOAP messages along the message path can perform.

A SOAP message is the basic unit of communication between SOAP nodes. It consists of a SOAP envelope that contains zero or more SOAP headers. The SOAP headers are targeted at any SOAP receiver that might be on a SOAP message path. The SOAP envelope also contains a SOAP body that contains the message payload or business information. A SOAP body might contain, for example, a service request and input data for the service to process. While processing a SOAP message, a SOAP node might generate a fault condition. If this happens, a SOAP node returns a SOAP message containing a SOAP fault. These nested elements are illustrated in Figure 4-1.

Figure 4-1. The nested elements of a SOAP message.

A SOAP node is an implementation of the processing rules described within the SOAP specification that can transmit, receive, process, or relay a SOAP message. Although the SOAP node implements the SOAP processing model, it can also access any services that underlying network protocols might provide. It does this through a SOAP binding that specifies the rules for carrying a SOAP message on top of some other underlying network protocol. These transport protocols might be other standards, such as HyperText Transport Protocol (HTTP), Simple Mail Transfer Prototol (SMTP), or Transmission Control Protocol (TCP). However, they might also include proprietary protocols, such as IBM WebSphereMQ.

SOAP nodes can send and receive SOAP messages. If a SOAP node transmits a message, it is called a SOAP sender; if it receives a message, it is called a SOAP receiver. Some SOAP nodes might both receive and transmit messages. In this case, they are called SOAP intermediaries. The SOAP sender that first builds the SOAP message is called the initial SOAP sender. The final destination of the message is called the ultimate SOAP receiver. This SOAP node is responsible for processing the payload of the message that is contained in the SOAP body.

Usually, a SOAP message passes through several SOAP nodes. An initial SOAP sender creates the message; the message then passes through various SOAP intermediaries before arriving at the ultimate SOAP receiver. This set of SOAP nodes is called a SOAP message path. In some cases, a SOAP message might not reach its intended ultimate SOAP receiver because the SOAP intermediary errs in processing the message. This is illustrated in Figure 4-2.

Figure 4-2. The SOAP message path.

4.2.2. The SOAP Processing Model

The SOAP message specification is expressed as an XML Infoset. This means that a SOAP sender has to create an Infoset that a SOAP receiver can reconstruct. To do this, the SOAP sender has to serialize the Infoset in a way that the SOAP receiver can use to reconstruct the original. The standard way of serializing is to use XML 1.0 syntax, but the specification allows other, potentially more optimized representations for more efficient network traffic. Any examples of SOAP messages used here employ the standard XML 1.0 syntax.

Let's start by looking at a basic SOAP message and its nested elements.

 <env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">   <env:Header>     <pns:qualityOfService xmlns:pns="http://example.org/qos">       <pns:priority>3</pns:priority>       <pns:timestamp>2004-02-25T01:00:00-00:00</pns:timestamp>       <pns:persist>true</pns:persist>     </pns:appHeaderBlock>   </env:Header>   <env:Body>     <bmns:businessPO xmlns:env="http://example.org/po">       <bmns:description>Widgets</bmns:description>       <bmns:quantity>100</bmns:quantity>       <bmns:price>20.5</bmns:price>     </bmns:businessPO>   </env:Body> </env:Envelope>

The outermost element is the env:Envelope that includes the namespace URL for SOAP. Enclosed within this are two subelements that SOAP defines. These are the env:Header and env:Body elements. SOAP does not define their contents. The elements are specific to the application that creates and processes the SOAP message. However, the SOAP specification does define how a SOAP node processes these elements.

The env:Header element is optional in SOAP, but it has been included in the sample to illustrate its use. The SOAP header is an extension mechanism that provides a way for information to be passed within a SOAP message that is not part of the business message payload. In the previous example, the env:Header includes an immediate child element that contains a set of quality of service parameters. This immediate child is called a header block within the SOAP specification. A header can contain many header blocks. The header block has its own XML namespace in which the priority, timestamp, and persist elements appear. The SOAP specification allows header blocks to be targeted at specific SOAP nodes for processing as the message travels along its message path. The SOAP headers control and process a message as it moves along a message path. They include information that controls messaging qualities of service such as security, reliability, and addressing. By specifying new headers, you can create interoperable protocols based on SOAP. These form the basis of the services architecture. This is shown in the following example.

 <env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope" xmlns:wsa="http://schemas.xmlsoap.org/ws/2003/03/addressing" xmlns:wssec="http://schemas.xmlsoap.org/ws/2002/04/secext" xmlns:wsrm="http://schemas.xmlsoap.org/ws/2003/03/rm">   <env:Header>     <wsa:ReplyTo> <wsa:Address>http://business456.com/User12</wsa:Address>     </wsa:ReplyTo>     <wsa:To>http://fabrikam123.com/Traffic</wsa:To>     <wsa:Action>http://fabrikam123.com/Traffic/Status </wsa:Action>     <wssec:Security>       <wssec:BinarySecurityToken         ValueType="wssec:X509v3"         EncodingType="wssec:Base64Binary">         dWJzY3JpYmVyLVBic.....eFw0wMTEwMTAwMD       </wssec:BinarySecurityToken     </wssec:Security>     <wsrm:Sequence> <wsu:Identifier>http:fabrikam123.com/seq1234</wsu:Identifier>       <wsrm:MessageNumber>10</wsrm:MessageNumber>     </wsrm:Sequence>   </env:Header>   <env:Body>     <app:TrafficStatus xmlns:env="http://highwaymon.org/payloads">       <road>520W</road>       <speed>3MPH</speed>     </app:TrafficStatus>    </env:Body>  </env:Envelope>

The SOAP processing model means that you can use different service specifications, each with its own header definitions, to assemble a message that has more complex qualities of service. For example, a message that has to be delivered reliably, encrypted, and acknowledged can be composed with three headers, each with its own unique namespace. One defines the reliable delivery, the second defines the security mechanism, and the third requests an acknowledgement from the messaging middleware. The extensible SOAP structure and its processing rules allow the services architecture to be composeable in such a flexible way.

The application or middleware designer must architect header blocks within SOAP messages unless one is being used that is defined by an existing Web service specification. Any header should have a formal specification stating what the subelements are and how a SOAP node should process them with an appropriate role. The header specification should also define fault conditions that can occur, together with what impact they have on application-level processing.

The env:Body element within the SOAP message is mandatory. It contains the payload of the message, which is the information that is being transferred from the initial SOAP sender to the ultimate SOAP receiver. The choice of what information goes into the env:Header and what goes into the env:Body elements is a matter of business application and system design. In a typical enterprise environment, middleware that supports a defined set of service policies mandates what headers are required in a SOAP message. The env:Body is then used to contain necessary application-specific information, which is processed by the ultimate receiver of the remote service implemention.

4.2.3. SOAP Roles

When a SOAP node processes a SOAP message, the node is said to act in one of several roles. A SOAP role identifies how a SOAP node should process a message. A URI identifies the SOAP role. It might be one of the three roles within the SOAP specification or one that systems designers assign to meet the needs of some applications. It appears as an attribute on the parent header block element. Consider the following example.

 <env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">   <env:Header>     <hb1:firstHeaderBlock xmlns:hb1="http://example.org/hb1"          env:role="http://example.org/Qos">       .....     </hb1:firstHeaderBlock>     <hb2:secondHeaderBlock xmlns:hb1="http://example.org/hb2"          env:role="http://www.w3.org/2003/05/soap-envelope/role/next">       .....     </hb2:secondHeaderBlock>     <hb3:thirdHeaderBlock xmlns:hb1="http://example.org/hb3">       .....     </hb3:thirdHeaderBlock>   </env:Header>   <env:Body>     .....   </env:Body>  </env:Envelope>

The hb1:firstHeaderBlock element in the example has a role attribute set to a value of http://example.org/Qos. The system designer assumes that the SOAP node that plays this role uses the information within the header block to manage message delivery quality of service in some specified way. The second header block hb2:secondHeaderBlock has its role attribute set to one of the roles defined within the SOAP specification. The specification defines three roles:

http://www.w3.org/2003/05/soap-envelope/role/none
http://www.w3.org/2003/05/soap-envelope/role/next
http://www.w3.org/2003/05/soap-envelope/role/ultimateReceiver

If a header block has a role set to the "none" URI, no SOAP node should process the contents of the header block. Nodes might need to examine the header contents if another header block references them, but they should not be processed.

Every SOAP node must be capable of processing a header block with its role attribute set to the "next" URI, because this is a role that every node should assume. A header block with a role set to the "next" URI is one that the next SOAP node in the message path should examine and possibly process. In the previous example, the hb2:secondHeaderBlock has its role attribute set to "next."

Finally, a SOAP node that assumes the role of an ultimate SOAP receiver processes a header block with its role attribute set to the "ultimateReceiver" URI. A header block that has no role attribute is targeted at the SOAP node that is acting as an ultimate SOAP receiver. In the example, the hb3:thirdHeaderBlock is targeted at the ultimate SOAP receiver because it doesn't have a role attribute.

The SOAP env:Body doesn't have a role attribute. This is because the body element is always targeted at the SOAP node that assumes the "ultimateReceiver" role. The SOAP specification says nothing about the structure of the env:Body element. However, it does recommend that good XML design practices are employed so that, for example, subelements of the body are qualified for the XML namespace.

Enforcing SOAP RolesThe "mustUnderstand" Attribute

Sometimes a SOAP node must process a particular header completely if it is acting in that SOAP role. The SOAP specification signals this condition by introducing a "mustUnderstand" attribute that can be added to a header block.

 <env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">   <env:Header>     <hb1:firstHeaderBlock exmlns:hb1="http://example.org/hb1"          env:role="http://example.org/Qos"          env:mustUnderstand="true">       .....     </hb1:firstHeaderBlock>     <hb2:secondHeaderBlock xmlns:hb1="http://example.org/hb2"          env:role="http://www.w3.org/2003/05/soap- envelope/role/next">       .....     </hb2:secondHeaderBlock>     <hb3:thirdHeaderBlock xmlns:hb1="http://example.org/hb3">       .....     </hb3:thirdHeaderBlock>   </env:Header>   <env:Body>     .....    </env:Body>  </env:Envelope>

In the modified example, the SOAP node that is targeted by the hb1:firstHeaderBlock element must process the header block because a "mustUnderstand" attribute is set to true. This is commonly referred to as a mandatory header block. The SOAP processing model states that processing of a SOAP message must not start until a SOAP node has identified all the mandatory header blocks targeted at it and is prepared to process them in accordance with the specification for those header blocks. If a header block has a "mustUnderstand" attribute set to false, or there is no such attribute, a SOAP node might choose to ignore and not process the header block, even though it might be targeted at it. If a header block has a "mustUnderstand" attribute and is targeted at a SOAP node, the SOAP node is obliged to generate and return a SOAP fault if it is unable to process the header block.

Passing HeadersThe "relay" Attribute

The SOAP processing model states that a node that processes a header must remove it from the message before passing it to another node along the message path. This is because the SOAP specification errs on the side of caution, making sure that an intermediary makes no assumptions about what will happen to the message header it has processed later in the message path. The SOAP specification does, however, allow a node to reinsert a header into an outbound message with its contents unchanged or altered in some way, but the default behavior of the node is to remove the header after processing.

Sometimes, however, a systems designer wants a particular header to be targeted at any or all nodes within a message path. To allow this, SOAP introduces the "relay" attribute. If this attribute is set to true, a SOAP node that detects a header targeted at itself can forward the header block to the next node if it chooses not to process it.

 <env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">   <env:Header>     <hb1:firstHeaderBlock xmlns:hb1="http://example.org/hb1"          env:role="http://example.org/Qos"          env:mustUnderstand="true">       .....     </hb1:firstHeaderBlock>     <hb2:secondHeaderBlock xmlns:hb1="http://example.org/hb2"          env:role="http://www.w3.org/2003/05/soap-envelope/role/next"          env:relay="true">       .....     </hb2:secondHeaderBlock>     <hb3:thirdHeaderBlock xmlns:hb1="http://example.org/hb3">       .....     </hb3:thirdHeaderBlock>   </env:Header>   <env:Body>     .....    </env:Body>  </env:Envelope>

In the previous example, the second header block is targeted at the "next" node in the message path. It also has the "role" attribute set to true. This means that a SOAP node that receives this message can process the header if it understands it. If it does so, the SOAP processing rules must be obeyed and the header removed before forwarding the entire message. A "role" attribute set to true means that the node, if it chooses to, can ignore the header block and forward it to the next node. Remember that if a header block also has the "mustUnderstand" attribute set to true, this over-rules a "relay," and the node must process the header block if it understands its meaning.

4.2.4. SOAP Faults

When an error occurs in processing a SOAP message, the specification provides a model for handling faults. The SOAP fault handling differentiates between the reasons that the fault occurred and the mechanisms that signal the presence of a fault. The signaling depends on the underlying transport mechanism. It is described in the SOAP binding specification.

SOAP fault information is placed within the env:Body element. All faults, both application and middleware generated, must use this structure. A sample SOAP fault is shown next.

 <env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"                xmlns:flt="http://example.org/faults">   <env:Body>     <env:Fault>       <env:Code>         <env:Value>env:Receiver</env:Value>         <env:Subcode>           <env:Value>flt:BadValue</env:Value>         </env:Subcode>       </env:Code>       <env:Reason>         <env:Text>A Fault occurred</env:Text>       </env:Reason>       <env:Detail>         <flt:MyDetails>           <flt:Message>Something went wrong at the Receiver</flt:Message>           <flt:ErrorCode>1234</flt:ErrorCode>         </flt:MyDetails>       </env:Detail>     </env:Fault>    </env:Body>  </env:Envelope>

SOAP faults are reported within a single env:Fault element that is the child of the env:Body. The env:Fault element must contain two child elements: env:Code and env:Reason. It might also contain three other optional elements: env:Detail, env:Node, and env:Role.

The env:Code subelement must contain an env:Value that matches one of the five SOAP fault codes defined in part 1 of the specification. These codes are as follows:

VersionMismatch The message does not match the SOAP versioning mode.
MustUnderstand The targeted node does not understand its header in the message containing a "mustUnderstand" attribute.
DataEncodingUnknown The targeted node does not understand the message's data encoding.
Sender The message was incorrectly formed when a processing node received it.
Receiver The receiving node or ultimate SOAP receiver could not process the message.

You can further expand the env:Code element by using the optional env:Subcode element.

The env:Reason element within the fault structure is intended as a human-readable description rather than an element for automatic processing. If required, the env:Text element might contain language attributes to allow alternative national languages to be used for the fault text message.

The optional env:Detail element can contain namespace-qualified elements to provide additional information about the generated fault. Finally, the optional env:Node and env:Role elements can identify the URI of the node that generated the fault, along with its role.

4.2.5. Documents and RPC

SOAP supports two programming models: document literal and remote procedure call (RPC). For document literal, the env:Body contains a business document such as a purchase order or airline reservation that the requesting service processes. After the service processes the document, it returns another document that might contain, for example, confirmation information that the order or reservation has been completed. For RPC, the env:Body on a request message contains a procedure name to be invoked in addition to a set of encoded arguments to the procedure. After the procedure has been invoked, a result and a set of return values are returned.

Web services have standardized on the use of the document literal model. For further information on the RPC model, look at the SOAP Primer [SOAP 1.2 Part 0].

4.2.6. Message Exchange Patterns

SOAP describes a one-way messaging model for transferring information between an initial SOAP sender and an ultimate SOAP receiver. The information is described in terms of a SOAP Infoset that is created by the initial SOAP sender and re-created by the ultimate SOAP receiver. For practical use, this simple one-way model can be extended to provide more useful interactions between Web services. These interactions are called message exchange patterns (MEPs).

Figure 4-3. Message exchange patterns.

Request/Response MEP

Most Web services operate using the request/response MEP. In this pattern, a requesting service sends a message to a provider. The provider then processes the message and returns a response to the original requester. Because of the stateless nature of Web services, no "session" state is preserved, as in other network protocols such as HTTP. Therefore, the requesting service needs some way to correlate the response to the request that caused it. There are two possible solutions to this:

Application-based correlation
Middleware-based correlation

In the first solution, the correlation of requests and responses is carried out at the application level. This relies on the design of the business messages that are to be carried in the SOAP env:Body element. For example, a purchase order application might be designed that includes a unique purchase order number as an element within its document schema. The initial SOAP sender application sets the value of this element and sends it to the purchase order service that acts as the ultimate SOAP receiver. When the purchase order service assembles its response, it inserts the purchase order number from the request into the document. The purchase order service then becomes the initial SOAP sender to return its response to the originating service, which then acts as an ultimate SOAP recipient to receive the response. The original requester can then, using the purchase order number inserted in the response document, tie together the request and response.

In the second solution, an env:Header element in the SOAP message contains correlation information. This might be a header designed specifically for a particular set of applications or the Message Information Header elements defined as part of WS-Addressing. If WS-Addressing is used, a request message might have the following information in its headers:

 <env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope" xmlns:wsa="http://schemas.xml.org/ws/2004/03/addressing"                xmlns:app="http://example.org/app">   <env:Header>      <wsa:MessageID>uuid:aaaabbbb-cccc-dddd-eeee-ffffffffffff</wsa:MessageID>     <wsa:ReplyTo>         <wsa:Address>           http://mybusiness.com/poRequest</wsa:Address         </wsa:Address>     </wsa:ReplyTo>     .....    </env:Header>   <env:Body>     .....   </env:Body> </env:Envelope>

The request message has a unique identifier that the wsa:MessageID element provides. It also has a wsa:ReplyTo element that identifies where response messages should be sent. The response message that the service provider generates is then structured as follows:

 <env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope" xmlns:wsa="http://schemas.xml.org/ws/2004/03/addressing"                xmlns:app="http://example.org/app">   <env:Header>     <wsa:MessageID>uuid:uuuuvvvv-wwww-xxxx-yyyy-zzzzzzzzzzzz</wsa:MessageID>     <wsa:RelatesTo>uuid:aaaabbbb-cccc-dddd-eeee-ffffffffffff</wsa:RelatesTo>     .....   </env:Header>   <env:Body>     .....   </env:Body> </env:Envelope>

In the response message, the wsa:RelatesTo element contains the wsa:MessageID of the request message that triggered the response, allowing the two messages to be related. The way that this correlation information is passed to the application layer depends on the interface between the Web services and application layers.

Long-Running Conversational MEP

Some business operations require more complex message exchanges between services than a single request/response. This can result in message exchanges that continue between two Web services for an extended period of time. These long-running conversational MEPs require additional correlation information to ensure that the state of the message is retained between the communicating services.

An example of a long-running conversational MEP might be a purchase order request and fulfillment process.

A purchaser requests a quotation for some items.
The supplier responds with a quotation.
The purchaser places an order against the quotation.
The supplier responds with a confirmation of the order.
Some time later, the supplier provides details of shipping information.
The purchaser acknowledges the receipt of the order to the purchaser.

Note that although most of the interchanges can be expressed as request/response MEPs, the supplier initiates some interchanges (such as the supplier providing shipping information).

Just as with the request/response MEP, the application or the Web service middleware layers can be assigned the task of ensuring that all the messages in a long-running conversational MEP are managed correctly. These layers might need to differentiate many instances of a long-running conversation between the same two services. Therefore, it might be helpful to use a conversation identifier within the business document inside the SOAP env:Body element or a separate header containing a conversation identifier that is inserted in each SOAP message that is part of the conversation.

4.2.7. SOAP Bindings

So far, this book has only looked at the SOAP envelope and processing model. It hasn't considered how the message is transmitted over a network. This is where the SOAP binding specifications are used. They allow a SOAP message to be transmitted over different network protocols such as HTTP, e-mail, and proprietary transports such as IBM WebSphereMQ. The purpose of a particular binding specification is to define a serialization of the SOAP Infoset such that it can be conveyed to the next node in a message path and the Infoset can be reconstructed without loss of information.

Figure 4-4. SOAP bindings.

A binding specification is valid only for a single hop between SOAP nodes, not the entire message path. A complete message path should be able to use the same binding specification, but it doesn't have to. The first hop might be to an HTTP server, so that will need the SOAP Infoset to be serialized and deserialized to and from HTTP. However, if the HTTP server is acting as an enterprise gateway, the SOAP message might continue along its message path using another network protocol such as IBM WebSphereMQ and a different binding mechanism. The important point is that the information that is held within the SOAP message Infoset is preserved as the message moves from node to node, regardless of how it is serialized at the network layer.

If the SOAP message is part of an MEP such as request/response, the request and response messages can be sent via different transport protocols. To extend the previous example, if the request is sent along a message path bound to HTTP for one hop and WebSphereMQ for another, the response can use another binding, such as e-mail. Remember that the information contained within the env:Body of a SOAP message is business application information and has nothing to do with the underlying network infrastructure. Therefore, a business scenario such as placing an order at a Web site and receiving an order confirmation by e-mail would match the example described previously.

SOAP and HTTP

The SOAP specification provides a normative binding to HTTP 1.1. In addition, it provides application designers with a SOAP Web method feature that supports the GET, POST, PUT, and DELETE operations described in the HTTP 1.1 specification. See the SOAP primer for a complete description of this binding.

SOAP and WebSphereMQ

This section shows how a nonstandard transport such as IBM WebSphereMQ can transport SOAP messages within a Web services infrastructure. It provides a reliable network transport mechanism for SOAP messages and has been implemented for either Apache Axis or Microsoft .NET environments.

Figure 4-5 shows how the WebSphere transport for SOAP fits into a Web services infrastructure.

Figure 4-5. WebSphereMQ as a SOAP transport.

Considering the single-hop case in which HTTP is used as the network transport between an initial SOAP sender and the ultimate SOAP receiver, the sending application passes details of the required service invocation to its SOAP layer, which prepares a SOAP message for transmission. This message is sent to the server system, where an HTTP server receives the request and passes it through the SOAP layer for processing by the ultimate SOAP receiver. The response can be returned to the service requester either synchronously or asynchronously.

The WebSphereMQ transport provides an alternative network transport to HTTP, as shown in Figure 4-5. It provides an enhanced transport mechanism and allows Web services to be invoked over an existing WebSphereMQ infrastructure. The transport is implemented as plug-in modules that connect to the SOAP layer. The SOAP layer forwards the message via the WebSphereMQ transport whenever the target URI contains a wmq: protocol prefix in the target endpoint URI. The WMQ sender writes the SOAP request message to a WebSphereMQ request queue. A WMQ listener retrieves messages from the request queue, invokes the required service, and then passes any response back to the service requester via a WebSphereMQ response queue.