Re: [ws-tx] Re: Groups - New Action Item #0057 Review use of RFC 2119keywords ...

["Monica J. Martin" <Monica.Martin@Sun.COM>]

Reference: wstx-wsat-1.1-spec-pr-01.rfc2119.pdf

Andrew,
We've reviewed the changes you proposed for Action #0057. In addition to 
the two comments already posted, our observations or comments herein are 
provided in three discernible parts:

   1. Those that appear to have been missed and may require changes
   2. Those that you proposed or we identified that may require further
      discussion
   3. Other editorial comments identified

=========
1. Those which were missed and may require changes (Fialli/Martin):

Section 3.
Change from: Volatile 2PC: Participants managing volatile resources such 
as a cache should register for this protocol.
Change to: Volatile 2PC: Participants managing volatile resources such 
as a cache register for this protocol.
Reason: Alleviate potential confusion by using active voice and deleting 
'should.'

Change from: Durable 2PC: Participants managing durable resources such 
as a database should register for this protocol.
Change to: Durable 2PC: Participants managing durable resources such as 
a database register for this protocol.
Reason: Alleviate potential confusion by using active voice and deleting 
'should.'

Change from: A participant can register for more than one of these 
protocols by sending multiple Register messages.
Change to: A participant must register for more than one of these 
protocols by sending multiple Register messages.
[add] A participant MUST register using one of the protocol identifiers 
defined in this section.
Reason: This would accommodate later references and alleviate the need 
for multiple MUST conditions.

Section 3.2.
Change from: A Completion protocol coordinator must be the root 
coordinator of an atomic transaction.
Change to: A Completion protocol coordinator MUST be the root 
coordinator of an atomic transaction.
Reason: Consistent with the probable intent of issue #047.

Section 3.3.1.
Change from: All participants registered for this protocol must respond 
before a Prepare is issued to a participant registered for Durable 2PC.
Change to: All participants registered for this protocol MUST respond 
before a Prepare is issued to a participant registered for Durable 2PC.
Reason: Clarify the behavior that is expected. Correspondingly, an 
equivalent constraint later in Section 3.3.2 (line 223) is proposed to 
upgrade to upper case MUST.

223 All participants registered for this protocol MUST respond Prepared 
or ReadOnly
224 before a Commit notification is issued to a participant registered 
for either protocol.

Change from: Further participants may register with the coordinator 
until the coordinator issues a Prepare to any durable participant.
Change to: Further participants MAY register with the coordinator until 
the coordinator issues a Prepare to any durable participant.
Reason: Consistency with preceding suggested change.

2. Those that may be require further discussion:

Section 2 (Wilkinson).
The Atomic Transaction coordination context MUST flow on all application 
messages involved with the transaction.
Change proposed in Line 145: Change "must" to "MUST".

Comment: In this section, this is insufficiently defined to propose a 
requirement. The specification has not yet defined how an "application 
message is involved in a transaction". This concept is not normatively 
introduced until Section 4.2. Appropriate normative statement is made on 
lines 267-269 on conditions that a AT coordination context flows with a 
request message.

Sections 3.2 and 3.3.3 (Wilkinson, Fialli/Martin).
Generally, suggest the TC make a decision as to the intent of Sections 
3.2 and 3.3.3, and whether the English prose relates specifically to the 
diagram, to the state tables that follow in Sections 9.1 and 9.2, or 
both, and be explicit about that association. The diagrams in both 
sections (first referenced) are high-level overviews. Yet, the prose 
that follows may indirectly reference them or the state tables. For 
example, it is difficult to infer the state that a notification is being 
processed within these sections. This could lead to confusion to 
potential adopters. This can be shown with two examples from Section 3.3.3:

 >>>>
Example 1:
231 The participant accepts:
232 Prepare
233 Upon receipt of this notification, the participant knows to enter 
phase 1 and vote on the outcome
234 of the transaction. If the participant does not know of the 
transaction, it MUST vote to abort. If
235 the participant has already voted, it MUST resend the same vote.

Comment: The diagram fails to illustrate receiving "Prepare" in the 
"None" state or resending the same vote if receiving the Prepare while 
the participant is in the Prepared or Aborting state.

Suggestion: The TC determine whether or not normative statements should 
be made OR the state that the notification was received must be stated 
for each normative statement. Previously, the TC discussed the normative 
nature of the state tables. These questions highlight whether or not 
that question may need
redress. It may be advised to explicitly identify these sections as 
non-normative and defer to appropriate state tables for guidance. For 
example, the "MUST" on line 235 is state dependent but one can only 
infer the state, because it is not explicitly stated. The state tables 
are more precise than prose in these sections (and is acknowledged in 
text in both sections).

Example 2:
240 Commit
241 Upon receipt of this notification, the participant knows to commit 
the transaction. This notification
242 MUST only be sent after phase 1 and if the participant voted to 
commit. If the participant does
243 not know of the transaction, it MUST send a Committed notification 
to the coordinator.

Comment: Term "voted to commit" introduces a problem for first MUST 
above. The term "voted to commit" includes participants that sent either 
Prepared or ReadOnly. (See lines 245-251 below.) It is uncertain if 
coordinator should send commit to a participant that voted to commit via 
notification of ReadOnly. ReadOnly is defined on line 249 as that 
participant both voting to commit AND it does not wish to participate in 
phase 2. The state table is clear that commit should not be sent to a 
participant that voted ReadOnly, just the above prose are unclear and 
could be misinterpreted.
Possible fix: Only send Commit to participants that notified by Prepared.
 >>>>

Section 8 (Fialli/Martin)
487 For example, in cases
488 where a Coordinator or Participant has forgotten a transaction that 
is completed and needs to respond to
489 a resent protocol message, the [source endpoint] property SHOULD be 
used as described in section 3.3
490 of WS-Addressing 1.0 – Core [WSADDR]

Comment: Consider whether a normative requirement is advised in a 
sentence that is 'for example'. Similar discussions have occurred in the 
TC past. Suggest this sentence be restructured to correlate to the 
paragraph in general and reworded.

3. Editorial corrections (Fialli/Martin):

Section 8.
Change from:
318 Lines (8-11) are a policy expression that includes an AT policy 
assertion (Line 10) to indicate that an
319 atomic transaction in WS-Coordination [WSCOOR] format MAY be used.

Change to:
318 Lines (8-11) are a policy expression that includes an AT policy 
assertion (Line 9) to indicate that an
319 atomic transaction in WS-Coordination [WSCOOR] format MAY be used.

Reason: Correct to say Line 9 (Line 9 has the wsp:Optional....).

Change from:
320 Lines (13-19) are a WSDL [WSDL] binding. Line (17) indicates that 
the policy in Lines (9-12) applies to
321 this binding, specifically indicating that an atomic transaction MAY 
flow inside messages.

Change to:
320 Lines (13-19) are a WSDL [WSDL] binding. Line (16) indicates that 
the policy in Lines (8-11) applies to
321 this binding, specifically indicating that an atomic transaction MAY 
flow inside messages.

Reason: Similar correction is required. Line 16 indicates that the 
policy in lines 8-11.

General.
In general, determine the case of each relevant noun is consistent for 
terms such as Commit, Prepare, etc. in the prose text.