Web Services and Stateful Resources - Using the Endpoint Reference
(Page 5 of 5 )
The other important part of the WS-Addressing specification is the way in which the endpoint reference is used by requestors to form Web service messages. The WS-Addressing specification requires that each binding type associated with the Web service define a set of rules that dictate how the components of the endpoint reference must be used to form request messages to the Web service pointed to by the endpoint reference. The specification itself defines only the rules specific to SOAP binding.
The SOAP rules are simple: The contents of the Address field must appear in the SOAP message's To header, and the contents of the reference properties element must appear as headers in the SOAP message. Here's an example SOAP message that represents a registration request (see Chapter 4 for more details) to a StockAvailableNotification service, as pointed to by the endpoint reference we showed earlier:
<soap12:Envelope
xmlns:soap12="http://www.w3.org/2002/12/
soap-envelope"
xmlns:wsa="http://schemas.xmlsoap.org/ws/2003/
03/addressing"
xmlns:tns="http://www.skatestown.com/services/
StockAvailableNotification">
<soap12:Header>
<wsa:To> http://www.skatestown.com/services/
StockAvailableNotification
</wsa:To>
<wsa:Action> http://www.skatestown.com/services/
StockAvailableNotification#registration
<wsa:Action>
<tns:someProperty> ABC 123 </tns:someProperty>
<ns1:Expiration xsi:type="xsd:dateTime"
xmlns:ns1="http://www.skatestown.com/ns/
registrationRequest">
2004-01-30T05:00:00.000Z
</ns1:Expiration>
</soap12:Header>
<soap12:Body>
<ns2:registration ...
</soap12:Body>
</soap12:Envelope>
The way the reference properties flow (as SOAP header elements of the message) is important to establish context for processing the message. The WS-Resource Framework exploits this feature, as you'll see later in this chapter.
SOAP Headers Defined by WS-AddressingWS-Addressing also standardizes a collection of SOAP headers. You saw one of these SOAP headers in the previous example: the To header. The other headers are summarized in the Table 8.1.
Table 8.1 SOAP Headers Standardized by WS-Addressing
WS-Addressing SOAP Header | Description |
To | The destination header. WS-Addressing requires this header to appear on messages sent to a Web service pointed to by an endpoint reference. Its content is a copy of the contents of the Address element in the endpoint reference. |
Recipient | An optional header. It contains a copy of the endpoint reference of the Web service that is the intended recipient of the message. If this header appears, it may help middleware intermediaries to process and route the message. |
From | An optional header that contains an endpoint reference of the Web service that created the message. |
ReplyTo | An optional header that contains an endpoint reference of a Web service to which any reply to the message should be sent. If this header doesn't appear, the receiver of the message can use the From element to send reply messages. This aspect of WS-Addressing is useful for asynchronous messaging situations where the network transport protocol can't be relied on to target the response message. |
FaultTo | An optional header that contains an endpoint reference of a Web service to which any fault messages should be sent. If this header doesn't appear, the receiver of the message can use the ReplyTo or From element to send fault messages. |
Action | A mandatory element that contains a URI indicating the intent of the message. |
MessageID | An optional URI that uniquely identifies this message. |
RelatesTo | An optional collection of QName, URI pairs. This allows you to specify the relationship between this message and other messages in a domain-specific way. |
We consistently use only two of these headers: To and Action; the others are optional. For more information on the use of the headers specified by WS-Addressing, refer to the WS-Addressing spec at http://www.ibm.com/developerworks/ webservices/library/ws-add/.
Please check back next week for the continuation of this article.
