Re: [wsrm] editorial updates for 0.93

[Tom Rutt <tom@coastin.com>]

Jacques Durand wrote:

> 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...
>
How about at the end of section 3?

> 2.--------------------------
>
> Section 1.
> (from Tue 3 meeting minutes)
> RM Capability Text not yet put in the spec.
>
I thought we agreed to wait until resolution of wsdl annotation before 
adding the capability section.

> 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.).
>
Signaling pattern is a new term which would need to be defined.,  I 
prefer the plural  "models".  Signalling connotes telecom mechanisms, 
like ss7 to me.


> 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.
>
We already have the term Reply pattern.  Are you suggesting to change 
the name to signalling pattern?

> 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. "
>
>
>
>


-- 
----------------------------------------------------
Tom Rutt		email: tom@coastin.com; trutt@fsw.fujitsu.com
Tel: +1 732 801 5744          Fax: +1 732 774 5133