RE: [wsrm] editorial updates for 0.93

Title: RE: [wsrm] editorial updates for 0.93

Iwasa: <JD>

-----Original Message-----

From: iwasa [mailto:]

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