WS-ReliableMessaging language basics

Note

Only element descriptions are provided in this section. Concepts relating to WS-ReliableMessaging are covered in Chapter 7.

WS-ReliableMessaging introduces critical quality of service features for the guaranteed delivery or failure notification of SOAP messages. It also positions itself as a fundamental WS-* extension, as shown in Figure 17.2.

Figure 17.2. How WS-ReliableMessaging relates to the other WS-* specifications discussed in this chapter.

When message exchanges are governed by a WS-ReliableMessaging-capable communications framework, the concepts of sequences and acknowledgements become paramount to just about every message transmission.

Coming up are descriptions for the following key WS-ReliableMessaging language elements:

• Sequence element
• MessageNumber element
• LastMessage element
• SequenceAcknowledgement element
• AcknowledgementRange element
• Nack element
• AckRequested element

Further supplementing these descriptions is a quick reference table containing brief descriptions of the following additional elements and assertions: SequenceRef, AcknowledgementInterval, BaseRetransmissionInterval, InactivityTimeout, Expires, and SequenceCreation.

17.2.1. The Sequence, MessageNumber, and LastMessage elements

As explained in Chapter 7, the delivery of messages within a WS-ReliableMessaging framework can be guaranteed to occur in a specific order. The Sequence construct resides in the SOAP message header to represent the location of the current message in relation to the overall sequence of messages within which it is being delivered.

To accomplish this, the Sequence construct relies on a set of child elements. The Identifier element is used to contain an ID value associated with the sequence itself, while the MessageNumber element contains a number that is the position of the message within the overall sequence order.

Finally, the LastMessage element can be added to the Sequence construct to communicate the fact that the current message is the final message of the sequence.

Case Study

As explained in the case study example at the end of the Reliable messaging section of Chapter 7, RailCo is required to use WS-ReliableMessaging to perform bulk invoice submissions.

The sample SOAP message below contains the header used by RailCo during the transmission of the last of a series of invoice message submissions.

Example 17.5. A Sequence construct with a LastMessage element, indicating that this is the final message in the sequence.

Sequence> http://www.xmltc.com/railco/seq22231 MessageNumber> 12 MessageNumber> LastMessage/> Sequence>

...

 

17.2.2. The SequenceAcknowledgement and AcknowledgementRange elements

Upon the arrival of one or more messages within a sequence, the recipient service may issue a message containing the SequenceAcknowledgement header construct to communicate that the original delivery was successful. This construct again uses the Identifier element to identify the sequence, but it also needs an element to convey which of the messages within the sequence were received and which were not.

It accomplishes this through the use of the AcknowledgementRange element, which contains the Upper and Lower attributes that indicate a range of messages that were received. This range is based on the MessageNumber values of the messages, which, when they are first generated, are incremented. So one AcknowledgementRange element communicates each consecutive set of messages received. Therefore, a message that is not received is not accounted for within the ranges specified in the AcknowledgementRange elements.

If this sounds a bit confusing, have a look at how the SOAP header is structured in Example 17.6.

Case Study

The markup code below shows the SOAP message returned from TLS after receiving the final invoice submission from RailCo.

Example 17.6. A SequenceAcknowledgement construct indicating that 11 out of a sequence of 15 messages were received.

SequenceAcknowledgement> http://www.xmltc.com/tls/seq22231 AcknowledgementRange Upper="4" Lower="1"/> AcknowledgementRange Upper="8" Lower="6"/> AcknowledgementRange Upper="12" Lower="11"/> AcknowledgementRange Upper="15" Lower="14"/> SequenceAcknowledgement>

...

Apparently, RailCo's bulk invoice submissions didn't go too well. The sequence acknowledgement message it receives uses four AcknowledgementRange elements to communicate the fact that out of the 15 messages it was expecting, only 11 were received.

Specifically, the AcknowledgementRange elements state that:

• messages with MessageNumber values 1 to 4 were received
• messages with MessageNumber values 6 to 8 were received
• messages with MessageNumber values 11 to 12 were received
• messages with MessageNumber values 14 to 15 were received

In other words, messages with MessageNumber values of 5, 9, 10, and 13 did not make it.

 

17.2.3. The Nack element

Communicating the delivery failure of a message can, alternatively, be accomplished using the Nack (negative acknowledgement) element. Instead of identifying which messages with MessageNumber values were received, it shows which were not.

Case Study

TLS also could issue negative sequence acknowledgement messages such as the one that follows, where only those messages not received are indicated.

Example 17.7. A SequenceAcknowledgement construct containing a Nack element that indicates that the fifth message was not received.

SequenceAcknowledgement> http://www.xmltc.com/tls/seq22231 Nack> 5 Nack> SequenceAcknowledgement>

...

 

17.2.4. The AckRequested element

RM destinations typically issue SOAP messages with SequenceAcknowledgement headers at predefined times, such as upon the receipt of a message containing the LastMessage element. However, an RM source service can request that the RM destination send out a sequence acknowledgement message on demand by using the AckRequested header construct.

This construct simply contains a standard Identifier element to pinpoint the sequence for which it is requesting an acknowledgement message. It also can include a MessageNumber element that gives an indication as to which message receipt the RM source is most interested in.

Case Study

RailCo tries another bulk invoice submission. Because of the poor delivery ratio experienced during the previous attempt, RailCo this time requests acknowledgement messages from TLS prior to the arrival of the last message in a sequence.

Following is an example of the acknowledgement RailCo issues after the transmission of every second invoice message within a sequence.

Example 17.8. The AckRequested header construct indicating that the RM source would like to receive a sequence acknowledgement message.

AckRequested> http://www.xmltc.com/tls/seq22232 AckRequested>

...

 

17.2.5. Other WS-ReliableMessaging elements

Table 17.3 provides an overview of additional elements that are part of the WS-ReliableMessaging language.

Table 17.3. Additional WS-ReliableMessaging elements.

Element	Description
SequenceRef	This construct allows you to attach policy assertions to a sequence, which introduces the ability to add various delivery rules, such as those expressed in the delivery assurances explained in Chapter 7.
AcknowledgementInterval	Specifies an interval period that an RM destination can use to automatically transmit acknowledgement messages.
BaseRetransmissionInterval	An interval period used by the RM source to retransmit messages (for example, if no acknowledgements are received).
InactivityTimeout	A period of time that indicates at what point a sequence will time out and subsequently expire.
Expires	A specific date and time at which a sequence is scheduled to expire.
SequenceCreation	Sequences are generally created by the RM Source, but the RM Destination may use this element to force the creation of its own sequence.

 

SUMMARY OF KEY POINTS

• WS-ReliableMessaging introduces a set of elements that govern the processing of message sequences and subsequent delivery acknowledgements.
• WS-ReliableMessaging establishes the concept of a sequence, as implemented via the Sequence construct. This represents a group of messages to which additional delivery rules can be applied.
• WS-ReliableMessaging further introduces the concept of acknowledgements, as established by the SequenceAckowledgement and Nack elements, which provide an inherent mechanism for a guaranteed notification of successful and failed deliveries.