Building a Communications Framework with WS-Policy and WS-ReliableMessaging
by Thomas Erl

"The check's in the mail, I swear!" How can you argue with that? If someone tells you a document has been mailed, then all you can do is wait to see if it's true. And, if it doesn't arrive, you need to consider the possibility of it being lost in transit.

With a mechanism for guaranteeing the delivery of a message, though, business correspondence would be much more reliable. You would be assured that messages will either be delivered as expected, or that a notification would be sent out advising you of a failed delivery attempt.

WS-ReliableMessaging establishes standard processes for the acknowledgement of successful message deliveries and the notification of transmission failures. It can be used in conjunction with other specifications, such as WS-Security, WS-Policy, WS-Coordination, and WS-Transaction.

When discussing reliable messaging, the WS-Addressing specification is worth mentioning. It provides a standard way of representing Web service endpoints in messages, as well as numerous additional addressing characteristics. Typically, addressing information is determined or set by the transport technology used to transmit the message. WS-Addressing establishes a standardized addressing syntax, independent of the protocol used for transport. Other specifications, such as BPEL4WS, also utilize WS-Addressing.

The focus of the WS-ReliableMessaging framework is relatively narrow, when compared to other specifications. Its primary concern is the guaranteed delivery of SOAP messages. This relates to the actual arrival of a message at its intended destination, but can also involve a guarantee that messages are delivered in the order in which they are sent.

WS-ReliableMessaging establishes a standard method of notifying the message sender of the success or failure of the delivery. This notification is accomplished through an acknowledgement that is sent either as a separate message, or as an embedded construct within the response message generated by the original message recipient.

To implement a system for the reliable delivery of messages, WS-ReliableMessaging requires that SOAP header blocks be embedded with a number of message attributes hosted within a container called a sequence. The information within a sequence is used to identify and process messages.

WS-ReliableMessaging makes a distinction between the parts of a solution that are responsible for initiating a message transmission and those that actually perform the transmission. It further assigns specific descriptions to the terms "send," "transmit," "receive," and "deliver," as they relate differently to these solution parts. These differentiations are necessary to abstract the reliable messaging framework from the overall SOA.

An application source is the service or application logic that sends the message to the RM source, the physical processor or node which performs the actual wire transmission. Similarly, the RM destination represents the target processor or node that receives the message and subsequently delivers it to the application destination.


Delivery Assurances

To enforce certain polices relating to the required reliability guarantees, WS-ReliableMessaging uses delivery assurances. There are four types of delivery assurances that can be issued:


AtMostOnce

The AtMostOnce assurance guarantees that a message can only be delivered once or not at all.

In this scenario, the AtMostOnce delivery assurance allows the failed delivery of a message that is not followed up with another transmission attempt.


AtLeastOnce

The AtLeastOnce assurance allows a message to be delivered multiple times, but ensures that it is delivered at least once.

The AtLeastOnce assurance allowing a message to be sent twice.


ExactlyOnce

The ExactlyOnce delivery assurance requires that a message be delivered once only.

Here, a failed delivery is followed by another delivery attempt, which this time succeeds.


InOrder

The InOrder assurance can supplement any of the preceding by also guaranteeing that messages will be delivered in the sequence in which they were sent.

A set of messages being transmitted in a predefined sequence. In the previous example, the initial delivery of message 2 failed. It was then resent, as the sequence must be completed, as per the assurance rule.

For the receiver of a message to notify the sender as to whether the messages within a sequence were successfully delivered, it responds using acknowledgement messages.

One acknowledgement can be sent for each message received. Alternatively, you can opt to have the receiver wait until the sequence has completed, before responding with just one acknowledgement for all received messages within a sequence

Reliable messaging exists within SOAP header blocks, which are processed by SOAP receivers along a message path.

The parent Sequence construct implements reliable messaging information, as follows:

<wsrm:Sequence>
   <wsu:Identifier>http://www.examples.ws/</wsu:Identifier>
   <wsrm:MessageNumber>2</wsrm:MessageNumber>
   <wsrm:LastMessage/>
</wsrm:Sequence>

In the preceding example, our Sequence header construct uses the Identifier element to assign a unique URI to the sequence. The MessageNumber element determines the position of the current message within the overall sequence order. This number increments with each subsequent message sent as part of a sequence. Finally, the LastMessage element identifies this message as the last one to be delivered.

A Sequence construct also can contain an optional Expires element that limits the validity of the sequence to a date and time value. Note that there can be only one Sequence construct in a SOAP message.

Though this example establishes a fundamental sequence header, there is still one part we have not yet addressed: the delivery assurance. This characteristic is implemented as a policy assurance, and then associated with the message as part of a policy attachment. We therefore demonstrate this portion of the example in the "WS -Policy" part of this article.

Note that other policy assertions can be attached to a sequence message header, including:

• sequence expiration

• inactivity timeout

• retransmission interval

An acknowledgement construct can be sent in a separate message, or as part of a response message. The parent SequenceAcknowledgement element hosts the same Identifier value, as well as the AcknowledgementRange element. This construct tells the original sender which of the messages in the sequence were delivered successfully, by specifying a range that corresponds to the number of messages in the sequence.

<wsrm:SequenceAcknowledgment>
   <wsu:Identifier>http://www.examples.ws/</wsu:Identifier>
   <wsrm:AcknowledgmentRange Upper="6" Lower="1"/>
</wsrm:SequenceAcknowledgment>

In this example, all six messages were successfully delivered. If, however, one of the messages in the sequence failed to arrive, the SequenceAcknowledgement construct may need to host a number of the AcknowledgementRange elements to identify only those that were delivered. Gaps in the sequence are considered failed deliveries.

<wsrm:SequenceAcknowledgment>
   <wsu:Identifier>http://www.examples.ws/</wsu:Identifier>
   <wsrm:AcknowledgmentRange Upper="3" Lower="1"/>
   <wsrm:AcknowledgmentRange Upper="6" Lower="5"/>
</wsrm:SequenceAcknowledgment>

In our revised example, the SequenceAcknowledgement construct uses two AcknowledgementRange elements to communicate that messages 1, 2, 3, 5, and 6 were delivered. By omission, the delivery of message number 4 is assumed to have failed.


Delivery Assurances with WS-Policy

Policies help organize and apply rules and properties of Web services within diverse application environments. The WS-Policy standard establishes a series of conventions that are further extended through the WS-PolicyAssertions and WS-PolicyAttachments specifications. Collectively, these standards form the WS-Policy framework.

Polices are defined through individual policy assertions. Each assertion can communicate a particular preference, rule, capability, or requirement of service logic. A policy assertion is implemented syntactically through a policy expression.

Whatever part of the service to which a policy expression is applied to is referred to as the policy subject. Policy attachments are used to bind policy expressions to policy subjects.

To demonstrate a use for WS-Policy, let's continue with the example from the WS-ReliableMessaging article.

The first message we assembled in the original example contained a sequence construct that provided information used for identification and sequencing purposes.

<wsrm:Sequence>
   <wsu:Identifier>http://www.examples.ws/</wsu:Identifier>
   <wsrm:MessageNumber>2</wsrm:MessageNumber>
   <wsrm:LastMessage/>
</wsrm:Sequence>

To this base set of reliable messaging data we now want to add one of the predefined delivery assurances.

Through the use of WS-Policy, WS-PolicyAssertions, and WS-PolicyAttachments features, we can:

1. establish a policy expression using the policy construct

2. establish the delivery assurance value as a policy assertion within this expression

3. attach the expression to the existing sequence construct as a policy attachment

Essentially, we need to establish a policy based on the chosen delivery assurance, and then attach it to the sequence header block we created in the WS-ReliableMessaging example.

We begin with the PolicyAttachment parent construct that hosts the policy assertion to be attached to our sequence.

<wsp:PolicyAttachment>
   <wsp:AppliesTo>
     <wsrm:SequenceRef>
       <wsu:Identifier>http://www.examples.ws/</wsu:Identifier>
     </wsrm:SequenceRef>
   </wsp:AppliesTo>
   <wsp:Policy>
     <wsrm:DeliveryAssurance Value="wsrm:AtLeastOnce"
       wsp:Usage="wsp:Required"/>
     </wsp:Policy>
   ...
</wsp:PolicyAttachment>

Here we identify the sequence to which we want to attach the delivery assurance, using the SequenceRef construct. The delivery assurance policy itself is then defined within the Policy construct.

SOA Design Patterns by Thomas Erl
Foreword by Grady Booch
With contributions from David Chappell, Jason Hogg, Anish Karmarkar, Mark Little, David Orchard, Satadru Roy, Thomas Rischbeck, Arnaud Simon, Clemens Utschig, Dennis Wisnosky, and others.
Web Service Contract Design & Versioning for SOA by Thomas Erl, Anish Karmarkar, Priscilla Walmsley, Hugo Haas, Umit Yalcinalp, Canyang Kevin Liu, David Orchard, Andre Tost, James Pasley
SOA Principles of Service Design by Thomas Erl
Service-Oriented Architecture: A Field Guide to Integrating XML and Web Services by Thomas Erl
Service-Oriented Infrastructure:On-Premise and in the Cloud by Raj Balasubramanian, Benjamin Carlyle, Thomas Erl, Cesare Pautasso
Next Generation SOA:A Real-World Guide to Modern Service-Oriented Computing by Pethuru Cheliah, Thomas Erl, Clive Gee, Robert Laird, Berthold Maier, Hajo Normann, Leo Shuster, Bernd Trops, Clemens Utschig, Torsten Winterberg
SOA with .NET & Windows Azure: Realizing Service-Orientation with the Microsoft Platform by David Chou, John deVadoss, Thomas Erl, Nitin Gandhi, Hanu Kommalapati, Brian Loesgen, Christoph Schittko, Herbjorn Wilhelmsen, Mickey Williams
SOA Governance:
Governing Shared Services On-Premise & in the Cloud
by Stephen Bennett, Thomas Erl, Clive Gee, Anne Thomas Manes, Robert Schneider, Leo Shuster, Andre Tost, Chris Venable
SOA with Java by Raj Balasubramanian, David Chou, Thomas Erl, Thomas Plunkett, Satadru Roy, Philip Thomas, Andre Tost
Modern SOA Methodology: Methods for Applying Service-Orientation On-Premise & in the Cloud by Raj Balasubramanian, David Chou, Thomas Erl, Thomas Plunkett, Satadru Roy, Philip Thomas, Andre Tost
Cloud Computing: Concepts, Technology & Architecture by Thomas Erl, Zaigham Mahmood, Ricardo Puttini
Cloud Computing Design Patterns by Thomas Erl, Amin Naserpour

For more information about these books, visit: www.servicetechbooks.com


Arcitura Education Inc.
Arcitura Education Inc. is a leading global provider of progressive, vendor-neutral training and certification programs, providing industry-recognized certification programs for a range of certifications.
For more information:
www.arcitura.com
SOA Certified Professional (SOACP)
The books in this series are part of the official curriculum for the SOA Certified Professional program.
For more information:
www.soaschool.com
Cloud Certified Professional (CCP)
The books in this series are part of the official curriculum for the Cloud Certified Professional program.
For more information:
www.cloudschool.com
Big Data Science Certified Professional (BDSCP)
The books in this series are part of the official curriculum for the Big Data Science Certified Professional program.
For more information:
www.bigdatascienceschool.com/