editorial updates for 0.93

[Jacques Durand <JDurand@us.fujitsu.com>]

Title: editorial updates for 0.93

Here is my suggested edits for spec 0.93, covering Sections 1 and 2.
-Jacques

1.--------------------------
Section 1.6: "Examples of Messages..."
This section should appear much further in the doc
after the protocol elements have been described in detail.
No reader will expect to see these examples here, or to understand them
that early...

2.--------------------------

Section 1.
(from Tue 3 meeting minutes)
RM Capability Text not yet put in the spec.

3.--------------------------

Section 2.1: "Overview of Messaging Model"
Propose to replace the subsection titles (e.g. "Request/Response Messaging Model")
with "Request/Response Signaling Pattern", because Messaging Model designates the
whole set of the three types of signaling described here (reusing the term
Messaging model to name parts of the "Messaging Model" is confusing.
Or we should at least title "Messaging Models". But I think "Model" should be
the whole set.).

Propose also to replace:
"There are three ways to send back Acknowledgment message or Fault message as
described as follows:"
with:
"There are three ways to do signaling, i.e. send back an Acknowledgment message or
a Fault message. They are called here "signaling patterns""
As well as at other places in this section.

4.--------------------------

Section 2.2 (beginning):
insert the middle sentence, for smoother reading:
"Every Reliable Message MUST contain a globally unique Message Identifier.
>>This Message Identifier relies on the notion of group<<. A message always
belongs to a group. "

5.--------------------------

Section 2.3: Guaranteed Delivery:

- Add at the beginning a reference to the RM agreement item that has been defined
more generally in Section 1:
"When the RM Agreement Item GuaranteedDelivery is enabled, the AckRequested header
element MUST be present in the Request element of the message header, for each
message under this agreement."
Doing so allows to relate all requirements (MUST) for this feature, to the
presence of this agreement item. So all these "MUST" are clearly conditioned
by the enabling of this agreement item: no abstract statement such as "when guaranteed
delivery is required... then header MUST..."
When in the future a representation of the RM agreement is proposed
(within this specification or outside), nothing in the spec body will need be changed:
it will be enough to define how the RM Agreement binds to this represenstation.

- Remove the current first sentence (no need to repeat the general definition given  for the agreement item.)

- The rule for stopping resending has actually 3 cases (not 2):
"If the RMP sending a Reliable Message does not receive an Acknowledgment for a sent message
that has not yet expired, it MUST resend the same message with same Message Identifier to the
receiver RMP until either one of the following occurs (whichever occurs first):
        . the sender gets an Acknowledgment message from the receiver,
        . the number of resend attempts specified by the RetryMaxTimes agreement item is exhausted,
      . the messages expires (ExpiryTime is past).

6.-----------------------

Section 2.4: Duplicate Elimination:

- Add at the beginning a reference to the RM agreement item that has been defined
more generally in Section 1:
"When the RM Agreement Item NoDuplicateDelivery is enabled, the header element DuplicateElimination
MUST be present in the Request element of the message header, for each message under this agreement."

- Replace the sentence about persistence of message IDs, with:
"In case the DuplicateElimination element is present, an RMP MUST check for duplicates of the message
over past messages that have not expired yet."

7.-----------------------

Section 2.5: Guaranteed Message Ordering:

- Add at the beginning a reference to the RM agreement item that has been defined
more generally in Section 1:
"When the RM Agreement Item OrderedDelivery is enabled,  the header elements MessageOrder,
AckRequested and DuplicateElimination MUST be present in the Request element, for each message
under this agreement."

- Sections 2.5 and 2.6 should be merged, as they are both describing aspects of
Guaranteed Message Ordering. The example for (1)(2)(3) should not be repeated
in both (even if for different purposes) but be consolidated in 1 example.
Sequence number mechanism should be succinctly introduced so that reader
understand what these numbers come from:
"This specification defines a model that uses sequential numbers to represent the
order of the messages in a sequence. The message header element SequenceNum holds this number as value.
Figure 3 illustrates how ordering is enforced. Assume the sender application submits three messages.
The sender RMP will number these messages in the order they have been submitted: (1)(2)(3) ..."

- I would add the following text to illustrate how ordering can be enforced,
and underlining that persistence is just an option (see Jun Tatemura mail):
"The way a receiver RMP can enforce the ordering depends on the implementation:
a common approach is to persist of out-of-order messages in a sequence,
until the missing messages are received.
How long the out-of-order sequence can be, is an implementation decision.
However, a lazy approach would
consist of simply ignoring the out of order messages, and of relying on the
resending mechanism to get these
messages later, with increased chance that missing messages are received in-between."

- We need to describe the failure case for ordering:
"Failure Case:
In case a message is missing and either (1) a received out-of-order message has expired,
or (2)  restoring an ordered delivery would require too much effort from an implementation
(e.g. the number of out-of-order messages is too large), the receiver RMP MUST abort
the ordered delivery. This means that only an ordered,
contiguous subset of the original sequence, starting from message "0", 
is allowed to be delivered.
The sender RMP knows what are the messages that have not been delivered yet,
as they are those with sequence numbers beyond the greatest number for which it
has received an Acknowledgement."

8.-----------------------

Section 2.5.1: Group Termination:
- Add at the beginning a reference to the RM agreement item that has been defined
more generally in Section 1:
(replace the 2 first sentences with:)
"There are two RM Agreement items - GroupExpiryTime and GroupMaxIdleDuration - that
can be used to determine when a group can be terminated. These two items can be
considered as controlling the persistence of group data.
To each of these agreement items, correspond respectively the message header attributes:
groupExpiryTime and groupMaxIdleTime. The following requirements pertain to these 
header attributes: "

- second bullet need be made more precise, similar to 1st bullet:
"If the first message has either one of the two group persistence parameter present
(either groupExpiryTime, or groupMaxIdleDuration) then the group will be subject to
termination rules t1, t2 or t3 described below"

9. -------------------------
Section 2.9:
Reword for more precision:
"*The current version of the WS-Reliability protocol does not support reliability
of WSDL response messages (the "output" messages in WSDL operations). 
It only supports reliability of the WSDL request ("input" messages).
** WS-I BP 1.0 disallows sending a SOAP envelope in HTTP response, so an RMP is
not required to support this.
However, this specification does not require an RMP to enforce this restriction
(i.e. WS-I BP compliance).
The receiver RMP may implement a "response" ReplyPattern if a received message asks for it. "