I've been cataloging the GXA specifications and trying to provide my own roadmap to what's happening in that area. I've created an index to the articles under "Global XML Web Services Architecture." Today, the topic is the web service referral specification.

Microsoft describes the WS-Referral, or web services referral in this specification. WS-Referral is meant to be used in conjunction with the WS-Routing, the web services routing specification. Both of these specification anticipate and describe the behavior of pieces of software called "SOAP routers" that route SOAP messages along a path from their origin to their intended recipient. WS-Referral describes the format of messages that can be used to add or delete routes in these routers. Unlike the other specifications I've discussed, it does not appear in the message itself, but affects how the message is rewritten along the path.

To see how they work, let's walk through a sample routing of a message. This example, and the code is from the specification, although I've put it together into more of a narrative.

Consider the following simple configuration of two SOAP routers A and B:

We could use the following SOAP message, which contains a <path/> element signifying a WS-Routing directive to send the message along this path.

<S:Envelope xmlns:S="http://www.w3.org/2001/09/soap-envelope">
  <S:Header>
    <m:path xmlns:m="http://schemas.xmlsoap.org/rp/">
      <m:action>http://www.notification.org/update</m:action>
      <m:to>soap://b.org</m:to>
      <m:from>soap://a.org</m:from>
      <m:id>mid:1000@a.org</m:id>
    </m:path>
  </S:Header>
  <S:Body>
    ...
  </S:Body>
</S:Envelope>

Now suppose that before sending the SOAP message shown above, we send the following referral to A:

<r:ref xmlns:r="http://schemas.xmlsoap.org/ws/2001/10/referral">
  <r:for>
    <r:prefix>soap://b.org</r:prefix>
  </r:for>
  <r:if>
     <r:ttl>43200000</r:ttl>
  </r:if>
  <r:go>
    <r:via>soap://c.org</r:via>
  </r:go>
  <r:refId>mid:1234@some.host.org</r:refId>
</r:ref>

This referral message tells node A: for any message that is going to node B, if the referral is less than 12 hours (43,200,000 milliseconds) old then the message should go via node C. This creates the situation shown below:

Note that this is only true for message that meet the for and the conditions in the if.

Now, assume that we send the original SOAP message again. Node A will insert a <via/> element into the <path/> element to create this message:

<S:Envelope xmlns:S="http://www.w3.org/2001/09/soap-envelope">
  <S:Header>
    <m:path xmlns:m="http://schemas.xmlsoap.org/rp/">
      <m:action>http://www.notification.org/update</m:action>
      <m:to>soap://b.org</m:to>
      <m:fwd>
        <m:via>soap://c.org</m:via>
      </m:fwd>
      <m:from>soap://a.org</m:from>
      <m:id>mid:1001@a.org</m:id>
    </m:path>
  </S:Header>
  <S:Body>
    ...
  </S:Body>
</S:Envelope>

Note that this is what the message looks like when it leaves node A, headed for C. Node C will accept the message and route it to B.

There are other ways to use referral statements. They can be used, for example, to delete routes or to insert proxies for certain parts of a namespace on a node. The specification, of course, is much more involved than what I've shown, but this will give a general idea of the way WS-Referral is used and what the messages look like.