12.1 Message Routing

As discussed in Chapter 5, SOAP is a lightweight wire protocol that defines a processing model but doesn't describe a message path . Using the simplicity of the protocol and extensibility through modularity, it's possible to construct rich messaging semantics; actor (defined as role in the SOAP 1.2 specification) and mustUnderstand attributes provide necessary mechanisms for describing nodes targeted for specific processing (intermediaries or ultimate destination). Intermediaries are nodes that lie between initial sender and ultimate receiver and act as both sender and receiver of SOAP messages; they are central to SOAP. The SOAP message model provides a distributed processing mechanism in which the SOAP actor attribute can indicate which part of a message is intended for a given SOAP receiver.

12.1.1 Web Services Routing Protocol (WS-Routing)

The Web Services Routing Protocol specification can be found at:

http://msdn.microsoft.com/library/en-us/dnglobspec/html/ws-routing.asp

It describes a simple, stateless, SOAP-based protocol for routing SOAP messages in an asynchronous manner over a variety of transports, including HTTP and TCP. The WS-Routing specification was developed by Microsoft and supersedes SOAP Routing Protocol (SOAP-RP) specification.

In addition to the processing model defined by the SOAP specification ("when message gets to node A do this, and when it gets to node B do that"), WS-Routing defines a message path ("to get to node A, message must travel through nodes C and D").

To express routing information, WS-Routing defines a single header element path and several subelements within that header:

• A to element for ultimate recipient of the message

• A fwd element for forward path specification

• A rev element for reverse path specification

• id and relatesTo elements for optional message correlation

The communication model described in WS-Routing is very simple: the sender of the message (specified by an optional from element) indicates the ultimate receiver of the message (using the to element) and forward path through zero or more intermediaries (using a fwd element). Even though intermediaries may insert additional nodes in the forward message path, they must not modify the to element. Here is a simple example that includes to and fwd elements:

 <m:path xmlns:m="http://schemas.xmlsoap.org/rp/">  <m:to>http://www.oreilly.com/books</m:to>  <m:fwd>     <m:via>http://www.oreilly.com/logger</m:via>   </m:fwd>   <m:id>uuid:12345678-9999-0000-aaaa-5b760641c1d6</m:id> </m:path> 

The via element indicates an intermediate receiver of the message and can be either empty or an absolute URI.

It's important to emphasize that while the value of to and fwd (or more precisely via ) elements are URIs, they represent only a role name (an intermediary, which is a SOAP node, can act in one or more roles), and there are no routing or message exchange semantics associated with the role name . In other words, a message addressed to http://www.oreilly.com/books can be processed by any node that thinks it should act in this role (and may have nothing to do with the physical location expressed by the same URI).

So, how does the sender learn the physical address where the message has to be sent? Because WS-Routing allows dynamic modification of the message path, there is no requirement that the complete message path has to be known when the message leaves the initial sender. All the sender has to know is the ultimate destination and the SOAP node next to itself in the message path (perhaps a SOAP router, which is a special kind of intermediary that knows how and where to send the message next). All the intermediary has to know is the next SOAP processor in the message path. As a result, it decouples the SOAP-based framework not only from the physical structure of the network, but also from the transport protocols that deliver the message.

Optionally, the reverse path of the message can be specified by the rev element. The reverse path is built dynamically as a message flows in the forward direction, but only when the initial sender inserts a rev element in the header. The purpose of the reverse path is to indicate a possible path that can send the message back to the initial sender; there's no requirement that the reverse path actually be used.

The capability to identify the message and to correlate that message with other messages is essential to the ability to establish a rich message exchange pattern. It might be used to correlate between request and response messages, between fault and faulty messages or between any other somehow related messages. The value of the id element is a unique identifier that identifies the message and the relatesTo element can be used to refer to that message. Note that the relatesTo element doesn't describe how messages are related, it merely states the fact of the relationship; semantics of the relationship are expected to be defined somewhere in the message or transferred out of band .

Being self-describing (all routing information is carried entirely within a message itself), WS-Routing is relatively transport-independent and defines bindings to several transport protocols: HTTP, TCP, UDP, and DIME.

All this functionality allows implementation of three key scenarios: message forwarding through known intermediaries, message resolution using dynamic modification of forward path, and reverse path routing through building a reverse path.

12.1.2 Web Services Referral Protocol (WS-Referral)

The Web Services Referral Protocol specification can be found at:

http://msdn.microsoft.com/library/en-us/dnglobspec/html/ws-referral.asp

It describes a SOAP-based, stateless protocol for inserting, deleting, and querying routing entries in a SOAP router.

Why the need for one more specification that describes message routing? WS-Routing specification defines a message path and allows sender or intermediary to specify how a message will travel, but it doesn't answer how a SOAP router gets this information. WS-Referral answers that question by introducing a simple model of a SOAP router being able to delegate a URI space or a part thereof to another SOAP router by manipulating its routing entries. Varying the amount of information known by the router, it's possible to support various scenarios:

• Dynamic configuration of SOAP routers and allowing them to learn about SOAP intermediaries

• Outsourcing of URI space and load balancing

• Progressive discovery of resources

The WS-Referral's basic unit is the referral statement (defined as a ref element), which includes five elements:

• A for element to indicate the actor or role for which the referral is intended.

• An if element to specify a set of conditions that the recipient of the referral must understand in order to use it. Only two mandatory if conditions are defined in the specification: invalidates to cancel previously registered referrals and ttl to set a time-to-live limit on the validity of a referral.

• A go element to specify one or more SOAP routers where the message has to be sent when for and if conditions are satisfied.

• A desc element to include additional information the recipient may use, but doesn't need to understand in order to use the referral. For example, it can be used to carry a hint of which router to choose when the go element specifies more than one.

• A refId element to uniquely identify the referral, so that SOAP routers can refer to a specific representation of a referral statement, for example, in operations that invalidate the referral.

This pseudocode describes the possible interpretation of a referral statement:

for actor or role name matching any of the names listed in the for element

if the set of conditions listed in the if element is satisfied

go via one of the SOAP routers listed in the go element

Here's an example that uses exact and prefix matching of an actor or role and specifies what one SOAP router may look like this:

 <r:ref xmlns:r="http://schemas.xmlsoap.org/ws/2001/10/referral">   <r:for>     <r:exact>http://www.oreilly.com/books/authors</r:exact>     <r:prefix>http://www.oreilly.com/books/orders</r:prefix>   </r:for>   <r:if/>   <r:go>     <r:via>http://www.oreilly.com/mirror</r:via>   </r:go>   <r:refId>uuid:11111111-2222-3333-4444-5567895432d6</r:refId> </r:ref> 

The WS-Referral specification describes not only the structure of the referral statement but also the mechanism by which messages are exchanged. There are three referral messages:

Register referral messages

Instructs the SOAP router to insert or delete the enclosed referral statement. It provides a "push" method of router configuration.

Query referral message

Queries the SOAP router for referrals. It provides a "pull" method that allows router and intermediaries to learn about existent message path.

Referral header messages

Can be any SOAP message that carries a referral header and includes one or more ref elements that carry referral statements. It allows a message to piggyback referrals on an existing message exchange path.

Note that despite the references to WS-Routing, WS-Routing and WS-Referral specifications to provide orthogonal services allowing WS-Referral to be used with other message path models if so desired. In a similar fashion, WS-Routing can be used with configuration mechanisms other than WS-Referral. Here is how they all work together:

• SOAP enables distributed processing but doesn't specify a message path.

• WS-Routing enables messaging via a message path but doesn't include a configuration.

• WS-Referral provides a configuration; it tells how to navigate through the path provided by WS-Routing.