WS-Addressing language basics

Note

Only element descriptions are provided in this section. Concepts relating to WS-Addressing are covered in Chapter 7. If you have not yet read Chapter 7, it is recommended you do so before proceeding.

The most common implementations of WS-Addressing standardize the representation of service endpoint locations and unique correlation values that tie together request and response exchanges. However, additional features are available that allow for the design of highly self-sufficient SOAP messages. Specifically, WS-Addressing includes extensions that support endpoint references for pointing messages to specific instances of Web services and message information (MI) headers that outfit messages with various types of transportation details.

WS-Addressing is a core WS-* extension providing features that can be used intrinsically or alongside features offered by other WS-* specifications. Figure 17.1 shows how WS-Addressing relates to the other extensions covered by this chapter.

Figure 17.1. How WS-Addressing relates to the other WS-* specifications discussed in this chapter.

 

17.1.1. The EndpointReference element

The EndpointReference element is used by the From, ReplyTo, and FaultTo elements described in the Message information header elements section. This construct can be comprised of a set of elements that assist in providing service interface information (including supplementary metadata), as well as the identification of service instances.

The WS-Addressing elements described in Table 17.1 can be associated with an EndpointReference construct.

Table 17.1. WS-Addressing endpoint reference elements.

Element	Description
Address	The standard WS-Addressing Address element used to provide the address of the service. This is the only required child element of the EndpointReference element.
ReferenceProperties	This construct can contain a series of child elements that provide details of properties associated with a service instance.
ReferenceParameters	Also a construct that can supply further child elements containing parameter values used for processing service instance exchanges.
PortType	The name of the service portType.
ServiceName and PortName	The names of the service and port elements that are part of the destination service WSDL definition construct.
Policy	This element can be used to establish related WS-Policy policy assertion information.

Case Study

Following is a sample EndpointReference construct generated to express information specific to a RailCo Accounts Payable Service instance. Note the application-specific child elements added in the ReferenceProperties and ReferenceParameters constructs.

Example 17.1. A SOAP header containing the EndpointReference construct.

EndpointReference>
 Address>
 http://www.xmltc.com/railco/...
 Address>
 ReferenceProperties>
 
 unn:AFJK323llws
 
 ReferenceProperties>
 ReferenceParameters>
 
 22322447
 
 ReferenceParameters>
EndpointReference>

 

To see how this information is implemented within a SOAP header, skip to the next example.

 

17.1.2. Message information header elements

This collection of elements (first introduced as concepts in Chapter 7) can be used in various ways to assemble metadata-rich SOAP header blocks. Table 17.2 lists the primary elements and provides brief descriptions.

Table 17.2. WS-Addressing message information header elements

Element	Description
MessageID	An element used to hold a unique message identifier, most likely for correlation purposes. This element is required if the ReplyTo or FaultTo elements are used.
RelatesTo	This is also a correlation header element used to explicitly associate the current message with another. This element is required if the message is a reply to a request.
ReplyTo	The reply endpoint (of type EndpointReference) used to indicate which endpoint the recipient service should send a response to upon receiving the message. This element requires the use of MessageID.
From	The source endpoint element (of type EndpointReference) that conveys the source endpoint address of the message.
FaultTo	The fault endpoint element (also of type EndpointReference) that provides the address to which a fault notification should be sent. FaultTo also requires the use of MessageID.
To	The destination element used to establish the endpoint address to which the current message is being delivered.
Action	This element contains a URI value that represents an action to be performed when processing the MI header.

The following case study example describes a SOAP envelope containing a header block consisting of two MI Header elements.

Case Study

At the end of the Addressing section in Chapter 7, an example was provided in which RailCo and TLS exchanged messages across service pools. Following is a sample of the type of message issued by RailCo's Accounts Payable Service to TLS's Vendor Profile Service. The From, ReplyTo, and FaultTo elements contain endpoint reference information with different Address values.

Example 17.2. A SOAP header with WS-Addressing message information header elements, three of which contain Endpoint Reference elements.

Action> http://www.xmltc.com/tls/vp/submit Action> To> http://www.xmltc.com/tls/vp/... To> From> http://www.xmltc.com/railco/ap1/... unn:AFJK323llws 22322447 From> MessageID> uuid:243234234-43gf433 MessageID> ReplyTo> http://www.xmltc.com/railco/ap2/ unn:AFJK323llws 22322447 ReplyTo> FaultTo> http://www.xmltc.com/railco/ap-err/ unn:AFJK323llws 22322447 FaultTo>

...

 

Notice how in this header block, the WS-Addressing Address element is used, not the Address element from the utility schema used in the WS-Coordination examples from Chapter 16.

 

17.1.3. WS-Addressing reusability

The endpoint identification and message routing mechanisms provided by WS-Addressing establish a generic set of extensions useful to custom service-oriented solutions but also reusable by other WS-* specifications. As such, WS-Addressing can be viewed as a utility specification that further supports the notion of composability within SOA.

Although we don't discuss the WS-Notification or WS-Eventing languages in any detail, let's take a brief glimpse at their Header constructs for some examples of how WS-Addressing message information header elements are reused in support of other WS-* extensions.

... Notification Details ...

Alternatively, if the framework chosen had been based on the WS-Eventing specification, the SOAP Header area would be as follows:

Example 17.4. A sample WS-Eventing SOAP header for a notification message.

Action> http://www.example.org/oceanwatch/2003/WindReport Action> MessageID> uuid:568b4ff2-5bc1-4512-957c-0fa545fd8d7f MessageID> To> http://www.other.example.com/OnStormWarning To> ... Subscription Details ...

... Notification Details ...

(WS-Addressing elements are bolded in each of the preceding examples.)

Notice how the WS-Eventing SOAP header places subscription details in the Header construct and notification information in the Body area, while the WS-Notification header structure locates the bulk of the notification information in the Body construct.

Case Study

At the end of Chapter 7 RailCo sets itself up to receive notification messages from TLS's System Notification Service. If this publish-and-subscribe model had been based on the WS-Notification framework, the SOAP Header construct of a notification message would look something like the following example:

Example 17.3. A sample WS-Notification SOAP header for a notification message.

Action> http://www.ibm.com/xmlns/stdwip/web-services/ WS-BaseNotification/Notify Action> To> http://www.xmltc.com/tls/endpoint1 To>

 

Examples 17.3 and 17.4 demonstrate that while WS-Notification and WS-Eventing establish the same basic messaging model using very different approaches, each relies on WS-Addressing to structure its SOAP header. This commonality is a tribute to the movement toward open standards that are universally accepted. In fact, each of the remaining specifications covered in this chapter also utilize WS-Addressing message information header elements.

SUMMARY OF KEY POINTS

• WS-Addressing provides a collection of message header elements that can supplement a message with various (mostly routing-related) meta information.
• The WS-Addressing specification defines a set of reusable extensions that are becoming intrinsically commonplace among other WS-* specifications.
• It is worth remembering that some of the message information header elements established by WS-Addressing are of type EndpointReference and can therefore contain a variety of endpoint metadata.