editorial comments on V0.991 with "history"

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

Title: editorial comments on V0.991 with "history"

Editorial comments on V0.991, attached.

Also attached, a review of the editorial impact of introducing a "Reliability" wrapper element
for all RM main elements (like WS-Security is doing with "Security" unique SOAP header block for WSS.)

Jacques

<<EditorialComments-WSR0991-spec.txt>> <<ReliabilityContainer-editorial.txt>>

Comments on Spec 0.991, PDF version  "with history" (lines # are different than without history)
-------------------------------------

L81:  does not presume -> does not attempt

L87: append the following question: "How could these quantitative parameters adjust to resource 
availability - memory, storage, computing - which depends on the communciation system (mobile
 device, messaging hub, etc.)?" 

L89: replace :
"should reliability also include synchronization between sender and receiver applications"

L79: Section 1.2:
Start by defining positively what reliability is:
bring-up lines 109-116 at the beginning.
Then Lines 102-105.
Then introduces an "out-of-scope" list, using two 1st bullet items of 1.3.
(Section 1.3 could diappear, as 3rd bullet (security) really is repeated in 1.5,
and the "mechanisms" bullet list really belongs to 1.2)
Then move down the "unaddressed questions" at the end (L81-92).

L131: Replace: (we need to be more specific about this.)
"Routing features. They can be used in conjunction with an implementation of this specification."
with:
"Routing features. This specification addresses end-to-end reliability, and is not concerned 
with intermediaries. The mechanisms described are othogonal to routing techniques, and can
 be used in combination with these."

L133: Replace: (we need to be more specific about this.) In fact, this one should be
merged with 1.5 and not appear here.
"Security Features. They can be used in conjunction with an implementation of this specification."
with:
"Security Features. This specification defines reliability independently from security, each of 
these features mapping to different SOAP header extensions. Although both features can be 
used in combination,  the specification does not attempt to compose them in a more intricate 
way, nor does it attempt to profile their combination."
 
L220: Just after Example 1, a few lines should give a first general understanding:
"The message above uses the Request reliability element, which specifies among other things, 
that all three features should be used: Guaranteed delivery ("AckRequested" element), 
No Duplicate Delivery ("DuplicateElimination" element) and Ordered Delivery ("MessageOrder" 
element)."
Same for Examples 2, 3 and 4.

L296:
Add these definitions to the terminology section:
- Message Identifier: (does not need to detail header attributes level here, but to show general
 meaning. Sufficient to define Duplicate.)
"A message identifier is a value or a combination of values in the message header, that uniquely 
identifies reliable messages. This identifier is only meaningful to the reliability features described 
here."
- Duplicate Message: (need this ne introduced before sec 3.5)
"A message is duplicate of another message if it has same message identifier."
Rationale: other RM artifacts are defined there (Ack, Fault, Poll...) and that needs to be 
introduced before section 3.5 (and NOT just  in section 3.5, as references to dups are pervasive
 throughout the spec.

L434: In 1.8.3: GuaranteedDelivery and NoDUplicateDelivery RM agreement items should 
be moved from Message scope to Group scope, because in Sec 4.2 (L681) does not allow 
different values for different messages in a group.

L525: remove "A" at beginning of sentence.

L582: Start the paragraph with: "In the example illustrated by Figure 4, when the sender...", and 
remove "In Fgure 4" from 2nd sentence.

L602: "Failure Case" subsection. Move it up before 3.3.1 because this is part of the general 
Guaranteed Ordering  mechanism and contract, and does not need details of the 
"Sequence Number". Also, replace "message" by "payload" when talking of delivery.

L590:  Section 3.3.1:  
The sentence starting L598 is unnecessary (repeating the mechanism described in 3.3): 
"the receiver RMP will wait...".
The sentence starting  L599 ("This behavior...")  is general statement unrelated to Sequ numb. 
Should belong to the Failure Case subsection.
A suggestion: "Sequence Number" could be numbered  3.4, outside 3.3, as this mechanism 
has also a rationale for Duplicate elimination and efficient representation of IDs.

L669:
Sentence is wrong, based on definition of "reliable message" in Terminology. 
"In a reliable message, the following three elements are direct children of SOAP Header:"
with:
"Any of the following three elements can be direct child of the SOAP Header:"

L734: sentence starting that line "In other words..." is useless, repeat of explanations already 
given in the Message Ordering section 3.3. Instead, it is enough to refer to 3.3:
 "When the MessageOrder element is present, the Message Ordering semantics as described
 in 3.3 applies."  

L739: Replace:
"In particular, the sender MUST include both an AckRequested element and a 
DuplicateElimination element, as well as the MessageOrder element for Guaranteed Message 
Ordering. "
with:
"In other words, an AckRequested element and a DuplicateElimination element MUST be 
present when the MessageOrder element is present."

L806: "The last message in a group SHOULD contain <status>..." We cannot recommend 
this: this is application-dependent. Should be a MAY.

L819: The NOTE is unclear. It should not sound as a disclaimer, but rather be reworded as a 
warning, pointing to what may affect the order: "When an application is receiving messages from
 an RMP, the actual order of delivered payloads may be affected by subsequent operations after 
the "deliver" operation has been invoked. For example, the actual order of delivery to the 
application may be affected by queuing taking place between the RMP and the application - and 
by the way the application reads such a queue - which would be out of scope of this specification."

L824: "A RMP -> An RMP.

L849 (sec 4.2.3) "Application-level MEP" has never been defined. Such MEPs should explicitly 
refer to WSDL operation types.

L851: Why is callback not applicable to req-resp MEPs? Do we have any reason to prevent 
usage in that case (even though callback seems better justified in case of one-way)?

L871: Sentence should not start with "And..." (casual)

L878: "If the sender includes the Message Order..." sentence is redundant, this has been said 
before at least twice.

L879: Replace:
"This element is used for... send back an Acknowledgement or Fault message for the message sent."
with:
"This element is used for... send back an Acknowledgement if the message sent was delivered,  
or else a Fault message."

L882: add at the end " [,,, message is a duplicate], and if it has already been previously delivered."

L890: no need to remind of the definition of duplicate: given previously in Terminology, as
 proposed earlier. No need to remind the dup elim requirement in case of Ordering.

L898: replace "...in the message" with "in every message".

L901: (sec 4.2.6)  the two sentences starting with ("When the sender request MessageOrdering..." 
are exact duplicate from the two sentences in L738 (sec 4.2.1.1). We should not have to remind 
this.


------------- stop review at section 4.3
Where would spec 0.991 be affected if we wrap all reliability elements inside a single
"Reliability" child element of the SOAP Header:
-------------------------------------------------------------------------------------------------------------------------

Examples 1, 2, 3, 4:
Wrap "Request" - and every other rel element -  within a common "Reliability" element.

Fig 5 and 6:
Add the Reliability element wrapping all RM elements.

L669: 
Sentence is wrong, based on definition of "reliable message" in Terminology. 
Replace:
"In a reliable message, the following three elements are direct children of SOAP Header:"
with:
"In a message, header elements related to reliability features are always contained in a 
Reliability element.  The Reliability element is a direct child of the SOAP Header. 
Any of the following three elements can be direct child of the Reliability element:"

L1161: Examples 9, 10, 11, 12, 14, 15, 16: 
Add the Reliability element for wrapping Response or Request, etc. elements.

L1393:
"The first MIME part MUST... include SOAP Envelope with the Reliability element."

Change the Schema.