Home   Download   Links   Documentation

White Mesa SOAP Server: Intermediary Support


The SOAP 1.1 spec states

"Regardless of the protocol to which SOAP is bound, messages are routed along a so-called 'message path', which allows for processing at one or more intermediate nodes in addition to the ultimate destination".

The White Mesa SOAP Server offers support for controlling whether a SOAP service endpoint functions as an "intermediate" node or as the "ultimate destination" (or "ultimate receiver") in the message path.

How it works...

When a SOAP request is received by the server, the request URI is mapped to a service definition which is configured by the server administrator with a variety of properties and settings. Three important properties related to intermediary configuration are:

  • Roles
  • Next Hop URL
  • Node URI

"Roles" is list of URIs identifying the roles the service supports for the purpose of Header block processing. Header blocks are targeted at roles via their optional "actor" (SOAP 1.1) or "role" (SOAP 1.2) attributes. Only those Header blocks targeted at the service will be available for processing, any others are ignored. "Next Hop URL" specifies the location of the next node in the message path if the service is to act as a SOAP intermediary and is used to configure a service as part of a "statically routed" message path. The "Node URI" property is used to specify the HTTP URL used to access the service and is used by the SOAP processor when generating SOAP Fault messages for a service acting as an intermediary.

If the "Next Hop URL" property is empty, then the service is assumed to be the "ultimate receiver" of the message and the operation represented in the SOAP Body is executed locally and the response message returned to the sender. Otherwise, the service is assumed to be an intermediary, and the message will be forwarded to the URL specified in the "Next Hop URL" property.

If a node is an intermediary, the SOAP message will be reserialized after the request phase Header processing step. A socket will then be opened and the SOAP request message sent to the node designated by the next hop URL property. The resulting response message returned from the next node will be received and deserialized, in preparation for the response phase Header processing step at the intermediary.

Whether functioning as an intermediary or as the ultimate receiver, normal Header processing will occur before the request is executed or forwarded. Given this circumstance, additional flexiblility is achieved by allowing Header processors to alter the value of the "Next Hop URL" property dynamically while processing. This is possible since Header processors, when called, are passed an interface pointer to the COM object instance which encapsulates the parsed SOAP message along with some contextual information. The methods "GetNextHopURL()" and "SetNextHopURL()" are provided. This allows for the possiblility of dynamic message routing, based on the results of Header processing. This feature is exploited in the White Mesa implementation of the WS-Routing Protocol.

Static routing example:

Imagine that a message path is to be set up in which node "I" is to be an intermediary, and "D" the ultimate destination. A client "C" wishes to access a service "fooSvc", which is mapped to the HTTP request URI "/fooSvc" on both nodes "I" and "D". Using the control panel application to configure the service "/fooSvc", the configuration might look like this for node "I" located at "www.intermediary.com":

Intermediary service definition.

The configuration for node "D", located at "www.destination.com" might look like this:

Intermediary service definition.

The client "C", wherever it is located, would be configured to send requests to node "I" at URL "http://www.intermediary.com/fooSvc". In this case, node "I" represents the endpoint as far as the client is concerned, sometimes called a "surrogate" since it is not actually performing the method execution. Node "I" is configured as an intermediary, forwarding requests to "http://www.destination.com/fooSvc". This of course means the request will arrive at node "D", which is configured as an ultimate destination, with an empty Next Hop URL property. The SOAP operation will be executed here and the response message composed and sent back to the client "C", via node "I" of course. Since its configuration leaves the "SOAP Svc ProgID" item empty, node "I" is incapable of actually executing the operation. Node "D", however, specifies the ProgID "foosvc.foo1", which will be used to identify the COM component which will execute the SOAP operation.

Now, assume that the Header processor at node "I" whose ProgID is "authen.auth2" functions as an authentication service. It may be desirable to allow it to override the configured Next Hop URL and route the message elsewhere, contingent on the results of the authentication process. By means of a call to "SetNextHopURL()" the Header processor may dynamically route the message when it is called to process Header blocks. Note that node "I" is configured with the role URIs "http://example.com/tc" and "http://example.com/auth". These identify the roles supported by the node for the purpose of detemining which Header blocks are targeted at it. In this case the two roles are implemented by the two Header processors "transact.tc1" and "authen.auth2". Node "D", on the other hand, is configured with the role URI "http://example.com/actors/logger" which informs the SOAP processor that the service supports processing Header blocks targeted at that role. To that end the Header processor "logging.log3" is specified in the configuration to be called at runtime by the SOAP processor. It is important to note that since the service is acting as the "ultimate receiver", it will be the target of any Header blocks which carry no "actor" (or "role") URI attribute, or one whose value is the empty string (""). Such Header blocks are said to be targeted at the "default role", which is always played by the ultimate reciever in the message path.

Home   Download   Links   Documentation

Copyright 2003 by Robert Cunnings.   cunnings@whitemesa.com  Last modified: Feb 2, 2003