NEW Issue - WS-AT: Editorial comments

Protocol: WS-AT

Artifact: spec

Draft: WS-AT specification PR 01

Link to the document referenced: http://www.oasis-open.org/committees/download.php/20224/wstx-wsat-1.1-spec-pr-01.doc

Section and PDF line number: See description below.

Issue type: Editorial

Related issues: None

Issue Description:

1. Line 2: “The current set of Web service specifications [WSDL][SOAP11][SOAP12] defines protocols for”; Change “defines protocols” to “define protocols”.

2. Line 19: Change “When an application finishes,” to “When an application finishes working on a transaction,”.

3. Line 24: Change “Tentative actions visible to” to “tentative actions persistent and visible to”.

4. Line 30: Change “existing transaction processing systems to wrap their” to “existing transaction processing systems will use WS-AtomicTransaction to wrap their”.

5. Section 1.2 Terminology
> Namespace URIs of the general form "some-URI" represents some application-dependent or context dependent URI as defined in RFC3986 [URI].
This feature is never used in this specification. Remove text from the specification.

6. Section 1.4, replace line 72 with “The XML schema and the WSDL declarations defined in this document can be found at the following locations:”

7. Section 1.6 Normative References. Use correct SOAP version 1.2 link is http://www.w3.org/TR/soap12-part1/.

8. Section 2

a. Fix grammar:

i. Before: “which defines an activation and a registration service. “

ii. After: “which defines an activation service and a registration service. “

b. Line 148 – add a colon (:) at the end of the sentence.

9. Section 3

a. Line 161 - add a colon (:) at the end of the sentence.

b. Editorial:

i. Before: “the coordinator begins with Volatile 2PC then proceeds through Durable 2PC”

ii. After: “the coordinator begins with Volatile 2PC and then proceeds through Durable 2PC”

c. Line 178 – I’m not sure what precisely it means to have a security context, and yet we MUST have one. CKaler may want to review this.

10. Section 3.1
Lines 176-177 - Replace the two occurrences of MUST with SHOULD, since it is not always possible to expect the client to know all the server-side policies).
Lines 178-179 – Replace the sentence with the following: “If a secure exchange of messages is required, then the source and destination MUST have appropriate security credentials in order to protect the messages”.

11. Lines 209-210: Change “The 2PC protocol has two variants: Durable 2PC and volatile 2PC.” to “The 2PC protocol has two variants: Volatile 2PC and Durable 2PC.”

12. Line 216: Change “Once this has happened” to “Once the coordinator issues a Prepare”.

13. Line 224: Change “After receiving a” to “Upon receiving a”.

14. Line 226: “All participants registered for this protocol must respond”; change ‘must’ to “MUST”

15. Section 3.3.1

a. Line 213: must -> MUST

b. Line 214: may -> MAY

c. Line 219 nit – protocol is different color than other protocol.

16. Section 3.3.2

a. Line 223: must -> MUST? (Not sure about this one.)

b. Line 226 nit – again, the color.

c. Line 234: must -> MUST

d. Line 235: should -> SHOULD

e. Line 238: can -> MAY

f. Line 238: may -> MAY

g. Line 242: can -> MAY

h. Line 243: must -> MUST

i. Line 258 – Which 2PC protocol? Both?

17. Section 4 states: ““this specification defines a pair of Atomic Transaction policy assertions that leverage the WS-Policy framework”. But the specification defines only assertion. This quoted text should be modified as: “this specification defines an Atomic Transaction policy assertion that leverage the WS-Policy framework”.

18. Section 4.4
Line 318 should be “Lines (8-11) are a policy expression that includes an AT policy assertion (Line 9) to indicate”
Line 320 should be “Lines (13-19) are a WSDL [WSDL] binding. Line (16) indicates that the policy in Lines (8-11) applies”

19. Section 5

a. Line 331: Is it really correct to refer to [Reason] as “the English language reason element”? Suggestion: Change to “[Reason] a human readable explanation of the fault”.

20. Section 8. WS-AT section 8 refers to Section 3.3 of WS-A to construct a message to the [source] EPR, when appropriate, but there should be a similar statement when it’s using the EPR it had already obtained. Add “Notification messages are normally addressed according to Section 3.3 of WS-Addressing by both coordinators and participants using the Endpoint References initially obtained during the Register-RegisterResponse exchange.”

21. Line 513: Change “and probably fatal” to “and probably a fatal condition”.

22. Section 9 State tables. Change ‘ReadOnlyDecision’ to ‘Read Only Decision’.

23. Section A
Line 525: Jim Johnson (Microsoft) is missing in the acknowledgement section. Jim is one of the authors of the contributed AT specification. Add “Jim Johnson (Microsoft)”.
Line 525: Chris Kaler (Microsoft) is missing in the acknowledgement section. Chris is one of the authors of the contributed AT specification. Add “Chris Kaler (Microsoft)”.
Line 525: Replace “Max Feingold (Microsoft)” with “Max Feingold (Microsoft) (Editor)”.
Check with Peter Furniss to use the right affiliation description.

24. All bulleted items in the specification: Indent one level deep.

Proposed resolution: See issue description.

ws-tx message