RE: [wsrm] editorial updates for 0.93

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

Title: RE: [wsrm] editorial updates for 0.93

Iwasa: <JD>

-----Original Message-----
From: iwasa [mailto:kiwasa@jp.fujitsu.com]
Sent: Thursday, February 12, 2004 5:32 AM
To: Jacques Durand; WSRM (E-mail)
Subject: Re: [wsrm] editorial updates for 0.93

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

I think this can be in section 3.2.1-AckRequested element, since this
explicitly mention about element names.

<JD>
Agree. We should generalize:
- Section 3.2 should mention the mapping rules for GuaranteedDelivery agreement
(AckRequested elt), NoDuplicateDelivery (DuplicateElimination elt) and Ordering
(Message Order elt.) i.e. tell how their presence is affected based on enabling of these items.
- Section 3.1.2 should mention the mapping rules for GroupExpiryTime, GroupMaxIdleDuration.
- etc.
- In Section 3, for each "Table" figure that describes header elements/attributes,
we can add one more row: "Related RM Agreement Items", that will list the agreement item(s) that influence the presence/value of this header element.

</JD>

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

I think the difference for section1.7 , section1.9.1 and section 2.3-2.5
is not clear. I think thre definition of 1.9.1 can be move to section1.7 or
2.3-2.5.

<JD>
I believe there is indeed a few improvements we could do, along
 what you suggest:
- definitions for G.D., D.E., G.M.O. in 1.9.1 (which should be 1.8.1) should
NOT be moved to the "Terminology" section because they describe a core aspect
of the spec, and should be indeed consolidated with sections that describe these features.
- So we can remove the second part of 1.9.1 out of this section.
- In 1.9.2, when listing each of these 3 main features, we should refer to
later sections where they are detailed, not 1.9.1.
- At the beginning of each section taht describes a reliability feature
(e.g. 2.3 Guaranteed Delivery, 2.4 Duplicate Elimination, etc...)
we list the RM agreement items that pertain to this section, along with their
precise definition (or reference to def if already defined before)
So for 2.3 (or whatever new section # that would be, see one of my previous mail for this...)we would have:
2.3.1 "Relevant RM Agreement Items"
<list of items: GuaranteedDelivery, RetryMaxTimes, RetryMaxInterval, ExpiryTime>
2.3.2 "Definition"
<here, we give precise definition for GuaranteedDelivery, and explain their logic
as previously done>
- We do not mention anything *here* about how these agreement items map to header elements, as you suggest, but in the "Message Format" Section.

- Now remains a problem: we should NOT talk of header elements before they are
introduced in "Message Format" Section, but that is what we do in Section
"Group Termination and State Removal". But it is hard to "abstract" these
header elements. E.g. termination events must be triggered by presence
of status="end" attribute, etc.
- So I suggest that we move all these group termination rules in a new section
after "Message Format" Section, called like: "Operational Aspects and Semantics".
Because they are really about detailed operational semantics of group structures,
closer to  deployment concerns (same for WSDL and Poll subsections).
Then the current "Group Termination and State Removal" should be a subsection of it,
renamed: "Message Group Life Cycle".
- Another Editorial change I suggest, is to move the "Fault Processing" section
under "Message Format", as it really describes fault codes, a part of message format.
In fact, as it has a single subsection "Fault Codes for ...", I would
just make this subsection a sub of "Message Format". So get rid of Section 4.
- If I consolidate these suggested reorganization of the sections, with previous
ones (splitting former Section 2) then, we would have:
---------------------------
-Section 1 "Introduction"
... (only internal changes in 1.8)
- Section 2 "Messaging Model"
- 2.1 "Assumptions"
- 2.2 "Message Reply Patterns"
- 2.3 "Message Identification and Grouping"
- Section 3 "Reliability Features"
  (this section does not refer to protocol (header) elements, only to RM agreement items)
- 3.1 "Guaranteed Delivery"
- 3.1.1 "Relevant RM Agreement Items"
- 3.1.2 "Definition
- 3.2 "Duplicate Elimination"
- 3.1.1 "Relevant RM Agreement Items"
- 3.1.2 "Definition
- 3.3 "Message Ordering"
- 3.1.1 "Relevant RM Agreement Items"
- 3.1.2 "Definition
- Section 4 "Message Format"
 (same sections, will introduce how RM agreement items map to header elements/attributes)
- 4.6 "Fault Codes for Reliable Messaging Failures"
- Section 5 "Operational Aspects and Semantics"
- 5.1 "Message Group Life Cycle"
- 5.1.1 "Group Termination Rules"
- 5.2 "WSDL Operation Type"
- 5.3 "Poll Reply Pattern Semantics and Usage"
- 5.4 "Attachments"
- Section 6 "HTTP Binding"
...
</JD>

> 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

This is a simple question to make sure:
Would it be appropriate to use a word "model" here?

<JD> could be:
"This specification is making use of sequential numbers to
represent the..
</JD>

> 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:

I have updated with this text. But is there more appropriate word
instead of "header attributes"?

And the second attribute name in a SequenceNum is groupMaxIdleDuration
but not groupMaxIdleTime.

<JD> In fact, if we move these group termination rules after "Message Format" Section
as suggested, then the mapping rule between RM agreement items
GroupExpiryTime and GroupMaxIdleDuration, and their header attributes
counterparts, should be put in Section 3 as for all previous others.
(here, in 3.1.2 "Sequence Num Element").
</JD>

> 9. -------------------------

> The receiver RMP may implement a "response" ReplyPattern if a received
> message asks for it. "

I felt this sentence is a little bit strange, especially for "may implement"
and
"if a received message asks for it".

I think the current text is OK. *If* we want to describe it clearly,
how about the following sentence?

<JD> slight updates:
"The receiver RMP may send an Acknowledgment message or Fault message
within a SOAP envelope in an HTTP response, when either a "Response" or a "Poll"
ReplyPattern is requested."
</JD>

There are many comments remaining I couldn't implemented in the spec yet,
since I wanted to make sure the TC also agree with this.
So I would propose to list up the reaming comments
as review comments.

Thanks,

Iwasa