Web Services Reliable Messaging
TC WS-Reliability (Section
Changes)
Document
identifier:
wd-Web Services
Reliable Messaging TC-WS-Reliability-0.94
Location:
http://www.oasis-open.org/committees/wsrm/documents/specs/1.1/ws-reliability1.1.pdf
Editor:
Kazunori Iwasa, Fujitsu Limited
<kiwasa@jp.fujitsu.com>
Abstract:
Web
Services Reliability (WS-Reliability) is a SOAP-based protocol for exchanging
SOAP messages with guaranteed delivery, no duplicates, and guaranteed message
ordering. WS-Reliability is defined as SOAP header extensions, and is
independent of the underlying protocol. This specification contains a binding to
HTTP.
Status:
This
document is updated aperiodically on no particular schedule.
Committee
members should send comments on this specification to the wsrm@lists.oasis-open.org list. Others should subscribe to and send comments to the wsrm-comment@lists.oasis-open.org list. To subscribe, send an email message to wsrm-comment-request@lists.oasis-open.org with the word "subscribe" as the body of the
message.
For information
on whether any patents have been disclosed that may be essential to
implementing this specification, and any offers of patent licensing terms,
please refer to the Intellectual Property Rights section of the Web Services
Reliable Messaging TC web page (http://www.oasis-open.org/committees/wsrm/).
The
errata page for this specification is at http://www.oasis-open.org/committees/wsrm/documents/errata/1.1/index.html.
Table of Contents
1 Introduction 4
1.1Purpose of WS-Reliability 4
1.2Scope and Definition of Reliable Messaging 4
1.3Limits of Scope 5
1.4Notational Conventions 5
1.5Relation to Other Specifications 6
1.6Examples of Messages Compliant with WS-Reliability 6
1.7Terminology 9
1.8The Reliability agreement 12
2 Messaging Model 15
2.1Overview of the Messaging ModelMessaging Context 15
2.2Message Reply Patterns 15
2.3Groups of Messages and Message IdentityMessage Indentification and
Grouping 16
3Reliability Features 17
3.1Guaranteed Delivery 17
3.2Duplicate Elimination 17
3.3Guaranteed Message Ordering 18
4 Message Format 20
4.1 Structure 20
4.2MessageHeader Element 23
4.3Request Element 29
4.4PollRequest Element 31
4.5Response Element 33
4.6Fault Element 35
4.7Fault Codes For Reliable Messaging
Failures 36
5Operational Aspects and Semantics 41
5.1Message Group Life Cycle Group Termination and State Removal
Criteria 41
5.2WSDL Operation Type 45
5.3 Poll Reply Pattern Semantics and Usage 46
5.4 Attachments 46
6 HTTP Binding 49
6.1Reliable Messaging with “Response” binding pattern 49
6.2Reliable Messaging with “Callback” binding pattern 51
6.3Reliable Messaging with “Poll” binding pattern 54
7 References 57
7.1Normative 57
7.2Non-normative References 58
Appendix A. Schema 59
Appendix B. Acknowledgments 65
Appendix C. Revision History 67
Appendix D. Futures List 76
Appendix E. Notices 77
Introduction
Messaging Model
Reliability Features
Message Format
Operational Aspects and Semantics
Message Group Life Cycle
1.
Group Termination
Being able to know when a group may be terminated,
is essential for efficient management of the persistent store of an RMP. As
groups may last a long time and their state requires persistence, it is
important to know when their persistent image can be reclaimed. The termination
cases described in this section may seem numerous. This plurality results from
the flexibility given to users in specifying various ways a group can be
terminated, which in turn depends on application needs. However, in spite of
this plurality, the termination logic is straightforward to implement and
shares the same basic mechanisms across termination cases.
Termination of a group in the Sender RMP and in the Receiver RMP are two
distinct events not synchronized by any special message, but instead occurring
as the result of rules applying separately to the Sender RMP and to the
Receiver RMP. As a consequence, the termination of a group may occur at quite
different times on sender and receiver sides. However, this lack of
synchronization allowed by these termination rules is not consequential.
We will define the following states for a group, whether managed on sender
or receiver side:
Group Closed:
·
A group is considered closed in the Sender RMP,
when all its messages have been sent and the last sent message has an ending
marker (SequenceNum/@last="true"). Note that closure occurs even if
not all messages have been either acknowledged or faulted (in case
GuaranteedDelivery is enabled.)
·
A group is considered closed in the Receiver
RMP, when a last message with an ending marker has been received, and all
previous messages for this group have also been received, (no number
missing in the sequence) although not necessarily delivered.
Group Disabled:
·
When a group is disabled in the Sender RMP, no
new message is expected to be sent by the RMP for this group. However, messages
MAY still be resent in case GuaranteedDelivery is enabled. If a new message is
submitted for a disabled group, the Sender RMP MUST notify the submitting
application that the group is disabled and MUST NOT send
the message.
·
When a group is disabled in the receiver RMP, no
new message is expected to be received for this group anymore. After a group is
disabled, and before the group is "removed" (see definition), a
Receiver RMP MUST NOT deliver messages received with this group ID, whether
they are duplicates or not of previous messages, and regardless whether they
result from a resending of previously failed messages initiated before closing
on the Sender side (in case GuaranteedDelivery is enabled).
Note: A group may be disabled without
being closed, due to timeout
Group Removed:
Group removal occurs at the time the group is disabled, or after.
Intuitively, a group is removed once all its messages have expired.
·
When a group is removed in the Sender RMP, the
RMP is not required to verify that future messages that are submitted are not
associated with the removed group, and MAY treat these as belonging to a new
group. However, in case the Sender RMP is in charge of generating group IDs, it
MUST NOT reuse the group ID of a removed group, when initiating a new group.
·
When a group is removed in the Receiver RMP, the
RMP is no longer supposed to remember anything about this group. In particular,
the group ID is discarded from the RMP state. When receiving a message with
same group ID as a removed group, a Receiver RMP is not required to verify if
this group ID value has already been used. Such a message MAY be treated as
belonging to a new group.
2.
Timeout
Parameters for Group Termination
There are two RM Agreement items - GroupExpiryTime and GroupMaxIdleDuration
that can be used to determine when a group can be terminated by timeout.
To each of these agreement items, correspond respectively the message header
attributes: groupExpiryTime and groupMaxIdleDuration. The following
requirements pertain to these header attributes:
a) the First message in a group (the one with
Request/MessageId/SequenceNum/@number
= 0) MUST be used by the sender to indicate that timeout parameters are in use
for the group.
·
If the first message in the sequence of a group
has neither group timeout parameter present, the group will be terminated
according to condition t3, t4 or t5.
·
If the first message has either one of the two
group timeout parameters present (either groupExpiryTime, or groupMaxIdleDuration)
then the group will be subject to termination rules t1 or t2 described below.
·
A fault MUST be returned if both group
persistence parameters are present in any request message. An
InvalidGroupParameter fault shall be sent in this case..
·
If groupExpiryTime is in use, the sender must not send a
message in that group with an ExpiryTime greater than the groupExpiryTime.
b) The group timeout parameter which was sent on the first message in the
group MUST be used on all subsequent messages in that group, and MUST be
assigned a value.
c) The Sender RMP MAY modify the value by sending a subsequent message with
a new value. When applying termination rules, the Sender MUST use the value in
the message with the highest sequence number sent for the group. The Receiver
RMP MUST use the value from the message with the highest sequence number
received for the group.
d) A new value for groupMaxIdleDuration can either be increased or decreased.
The protocol allows change (up or down) of groupExpiryTime, as long as it is never
less than max(ExpiryTime) of messages received so far
for the group.
An InvalidMessageParameters Fault MUST be returned if the value of
groupExpiryTime is decreased to be less than the max(ExpiryTime)
of messages received for the group.
3.
Termination Rules
Termination is the process by which an RMP discontinues the use of a group,
allowing the RMP to dispose of state information about the group. Termination
typically involves two steps that may not occur at the same time: disabling and
removal.
Because the ending marker is not mandatory for the last message of a group,
a group is not always closed before it is disabled. After a group is disabled,
a Receiver RMP has no duty regarding subsequent messages received for this
group - meaning it could ignore them - except for one aspect: when duplicate
elimination is required, no duplicate should be delivered for the group, no
matter how late it is received after the disabling. In order to accommodate
this requirement, the termination rules will phase the "disabling"
step and the "removal" step of a group, so that it will still be
possible to filter-out potential duplicates during the time these duplicates
have not expired. After the removal of a group, there will be no risk to
deliver a duplicate, simply because they all have expired.
As a summary, there are two general indicators an RMP will use to terminate
a group:
(a) Message marker: Information within a message (either ending marker, or
maximum sequence number) that indicates a last message for the group. This is
used by termination rules T3, T4.
(b) Timing: Either the group lifespan expired, or its idle time exceeds a timeout.
This is used by termination rules T1, T2, T5.
In all termination cases (t1, t2, t3, t4, t5) described in this section, it
is not necessary to remember the ExpiryTime of all messages of a group, as only
the max(ExpiryTime) of messages received for the group
is needed.
These termination rules apply to both ordered and unordered groups. However,
these rules do NOT apply to singleton groups, which contain a single message
with no sequence number.
I.
Termination by expiration (t1):
Context:
The group had groupExpiryTime specified.
Receiver side:
Triggering event: groupExpiryTime is over.
The RMP MUST disable and remove the group.
Sender side:
Triggering event: groupExpiryTime is over.
The RMP MUST disable and remove the group.
II.
Termination by idle timeout (t2):
Context:
The group had
groupMaxIdleDuration specified.
Receiver side:
Triggering event:
the time since the last received message for the group is over groupMaxIdleDuration.
The group MUST be disabled. But unlike (t1), some of its past messages may
not have expired yet, and therefore should not be accepted as from a new group.
In order to make sure all potential duplicates for the group will not be
delivered, in case Duplicate Elimination is required the RMP MUST wait until
all messages received for the group have expired. If we define max(ExpiryTime) as the maximum of all ExpiryTime values of
messages received for a group, an RMP MUST NOT be remove until max(ExpiryTime)
is reached, in case Duplicate Elimination is required.
Sender side:
Triggering event: the time since the last sent message for the group is over groupMaxIdleDuration.
The group MUST be disabled and removed.
III.
Termination by closing (t3):
Context:
No specific context.
Receiver side:
Triggering event: The RMP receives a message marked last (Request/MessageId/SequenceNum/@last=”true”),
which closes the group, assuming that all
previous messages for the group have been received. Or, assuming that
the message with ending marker has already been received, the RMP receives the
last missing message in the group.
The group MUST be disabled. However, its removal is done according to (t1)
or (t2), depending which timeout parameter was specified for the group. If no
timeout parameter was specified, the group is removed once all its messages
have expired: i.e. the date max(ExpiryTime) is passed.
Sender side:
Triggering event: The RMP sends a message marked last.
All messages of the group have been sent. The group MUST be disabled. If
Guaranteed Delivery was required, the group MUST be removed once all sent
messages have either been acknowledged, or their delivery failure notified. If
no Guaranteed Delivery was required, the group MUST be removed immediately.
Note: in case a message is received with an ending marker, but not
all previous messages have been received, then the group remains active. No
termination process is initiated yet.
IV.
Termination by sequence exhaustion (t4):
Context:
No specific context.
Receiver side:
Triggering event: The RMP receives a message with a sequence number with
maximum value, assuming that all previous
messages for the group have been received. Or, assuming that the message
with maximum sequence number has already been received, the RMP receives the
last missing message in the group.
The group disabling and removal follows the rules in t3, the message with
maximum sequence number acting as a message with ending mark.
Sender side:
Triggering event: The RMP sends a message with a sequence number with
maximum value.
The group disabling and removal follows the rules in t3, the message with
maximum sequence number acting as a message with ending mark.
Note: in case a message is received with with maximum sequence
number, but not all previous messages have been received, then the group
remains active. No termination process is initiated yet.
V.
Termination by ordering failure (t5):
Context:
The group is under Guaranteed Message Ordering
reliability requirement. Not all received messages for the group have been
delivered (some message is missing).
Receiving side:
Triggering event: In an ordered group, a message expires before delivery in
an out-of-order sequence.
The group MUST be disabled. The group is removed according to rule t3.
Sender Side:
Triggering event: In an ordered group, a non-acknowledged message expires.
The group MUST be disabled. The group is removed according to rule t3.