Most of the Web service examples that we have discussed thus far have involved simple point-to-point SOAP messaging scenarios. However, in real- world applications, your Web service might need to implement a more complex message-routing scenario, such as dynamic, decision-based routing; routing through firewalls or intermediaries; or even using multiple transport protocols. For example, consider a Web service application that has been scaled out to run on multiple Web servers and behind a firewall. In such a scenario, a load- balancing application could be used to route request messages to whichever Web server was best able to handle the load. For example, such an application might determine, based on relative loads, whether to route a request to a processing center located on the East Coast or one located on the West Coast. In a multiple-message transaction, it would then be important that all future requests be sent directly to the application center where the original request was being handled. If this level of specificity for addressing is not supported in the message itself, then the routing application would need to do extra work to determine which processing center should handle all subsequent incoming messages from the client and would likely require the expense of having to maintain a server-side process that includes state information.
In a scenario like this, it is important to have an addressing mechanism that transcends the simple point-to-point functionality provided by the message transports. Among other benefits, such a mechanism would enable any intermediary Web services, such as routers, to have all of the addressing information that they need to ensure that the messages end up in the right place. To provide this consistent addressing for Web services, the WS-Addressing specification defines two constructs for conveying message addressing information: endpoint references and message headers. In this definition, an endpoint is simply an addressable resource to which a SOAP message can be sent; the resource can be a Web service or client application, a SOAP router, or any other SOAP-aware entity.
In the reliable messaging model, SOAP messages are sent between and via endpoints. To address a messaging endpoint, we need to be able to explicitly, uniquely, and consistently reference such endpoints. As an additional hurdle , endpoint references must be discoverable so that messages can be addressed dynamically. Of course, as with Web Services Description Language (WSDL), before an endpoint reference can be consumed it must first be described. WS- Addressing introduces a mechanism for describing endpoint references.
From a WSDL standpoint, endpoint description information would most logically be defined within the Service element of a WSDL document; however, WSDL 1.1 does not allow for the extensibility of this element. To get around this limitation, WS-Addressing defines a new typed EndpointReference element that can be used within a Web service description document, such as WSDL, to describe a referenced endpoint. The EndpointReference element supports the following child elements:
Address Provides the Uniform Resource Identifier (URI) of the endpoint, which can be a network or logical address.
ReferenceProperties Provides application-specific information that must be supplied when addressing messages to a particular endpoint.
PortType Specifies the WSDL port type of the referenced endpoint.
ServiceName Specifies the WSDL service that defines the referenced endpoint. This element can also include a PortName attribute that references the name of the WSDL port definition for the endpoint.
Policy Can contain one or more policy assertions, which can be used to describe the policies that are enforced at an endpoint.
The following is an example of an endpoint reference for the CollectionService Web service:
In this example, the Policy element would contain a policy assertion element, which I ll describe along with a detailed discussion of Web service policies in Chapter 6. By adding this endpoint reference to the WSDL file that describes the CollectionService Web service, you can dynamically assign a policy behavior to the endpoint. In addition to being used in description documentation, the EndpointReference element is also the base type used when describing an endpoint in one of the SOAP message headers defined by WS- Addressing.
In addition to defining a mechanism for referencing message endpoints, WS- Addressing also specifies a set of message headers that can be used during transport to define the endpoints on the message path . When endpoint information is transported in SOAP headers, this information can be accessed by messaging intermediaries when they need to make intelligent routing decisions. The following SOAP message header elements, which are child elements of the Header element, are defined by WS-Addressing:
To Contains information about the immediate message recipient in the form of a URI.
From Contains information about the message sender in the form of the endpoint reference type.
ReplyTo Contains information about the endpoint to which a reply message should be sent in the form of the endpoint reference type.
Recipient When a message is being routed via one or more intermediaries, can be used to specify an intended ultimate message recipient and is in the form of an endpoint reference type.
FaultTo Contains information about the endpoint to which any fault response messages generated by the request should be sent, in the form of the endpoint reference type.
Action A URI that represents the action for the message, which can be the same as the value of SOAPAction in an HTTP message header.
MessageID A URI that is used to uniquely identify a message.
RelatesTo Used to relate a message to another message by relationship type. This optional element contains a URI that is the MessageID value of the related message. The relationship type is specified using the element s RelationshipType attribute, where at this point the only accepted value is Response .
The following SOAP request message to the DocumentService shows the use of WS-Addressing message headers.
In this example, the URI value in the From element that defines the endpoint of the requesting party is http://schemas.xmlsoap.org/ws/2003/03/addressing/role/anonymous . This URI is used when a fixed URI cannot be assigned to the Address value of an endpoint. Of course, this anonymous URI value cannot be used with the To element, and if the value is specified in the ReplyTo or FaultTo element, there must be an alternative mechanism for communicating this information.
WSE supports the headers defined in WS-Addressing and, by default, generates a set of addressing headers for all outbound SOAP messages. Also, when incoming messages contain addressing headers, the WSE input filters read these headers and generate the relevant programming objects. As I ll show later in this chapter, the WSE API can be used to add or change the values of these message headers or to access the addressing information for incoming messages.