Minor editorial comments
- Conformance to
OASIS template Date format is November 8, 2006, should be dd
month yyyy (AT and C are correct).
- Line 12 –
protocol should be plural (since there are more than one defined in the
spec – consistent with lines 45, 51…). Propose changing
the text from “To understand the protocol described in this
specification….” to “To understand the protocols described in this
specification….” since there are 2 coord types and 2 protocols
defined in WS-BA.
- Line 16 –
there are 2 BA coordination types defined. Propose changing:
“The specification provides the definition of a business activity
coordination type…” to “This specification provides the
definition of two business activity
coordination types…”
- Line 22 –
Change “Business Activities have the following
characteristics…” to “Business activities have the following characteristics….”
(lower case ‘a’ in activities). See line 26. Also
relates to comment 2 below (substantive comment ‘Inconsistent
reference to this specification”) This is another example of
where the use of Business Activity is confusing in the spec.
- Line 29 –
“Activity” should be lower case ‘activity’.
- Line 42 –
Reference link [WSCOOR] is missing (after WS-Coordination).
- Line 84 –
[RFC2119] is duplicated (four times)
- Line 98
– Change “Examples starting with <?xml contain
enough…..” to “Examples starting with “<?xml” contain enough….”.to be consistent with
representation for other terminology definitions.
- Line 100 –
move reference links next to specs. This is consistent with Coord,
however, it isn’t consistent with the usage in the rest of the
spec. Should it be changed from: “XSD schemas and WSDL
definitions are provided as a formal definition of grammars [XML-Schema1]
and [WSDL].” to “XSD schemas [XML-Schema1] and
WSDL [WSDL] definitions are provided as a formal definition of grammars.”?
- Lines 142-143
– WS-Addressing reference. “Web Services Addressing
(WS-Addressing), Web Services Addressing (WS-Addressing)
1.0, W3C Recommendation, http://www.w3.org/2005/08/addressing”
Duplicated spec name and link in name that is inconsistent with format
used in other references.
- Lines 150-152
– BPEL reference. This link doesn’t work inline
“Cannot open the specified file” error. However, it does
work when I cut and paste it into a browser: http://www.oasis-open.org/committees/download.php/16024/wsbpel-specification-draft-Dec-22-2005.htm. Is this
the right document to reference – it’s a CD from Dec 2005 (not
PR draft)?
- Line 195 –
Unclear antecedent to ‘It’. Suggest changing “For
example, it may specify….” to “For example, a coordination protocol type may
specify…”
- Line 316 –
incomplete sentence. “Received in response to a getStatus
request.” to “This message is received in response to a
getStatus request.”
- Lines 317, 499,
522, 527 – Inconsistent capitalization. These lines use:
Coordinator or Participant. The majority of occurrences follow the
convention of using lower case (see line 525): coordinator and participant.
- Lines 368 and
372 – inconsistent capitalization. Change “To enable a
web service…[line 378]” and “The BA policy assertions
are provided by a web service…[line 382]” to “Web service…”
- Lines 375 and
378 – capitalization of bullet items: Change
‘whether’ to “Whether”
at the start of each bullet item.
- Line 411 and 413
– missing article. Should “….the assertions have
Operation Policy Subject [line 411]” and “…points with
Operation Policy Subject [line 413] be changed to read “an Operation Policy Subject”?
- Line 466 –
use of SCT acronym. This is the first (and only) usage of the
term. Suggest the first usage be spelled out before the acronym.
- Line 519 and 524
- WS-A reference. “Notification messages are normally
addressed according to section 3.3 of WS-Addressing by both …[line
530]” and “…SHOULD be used as described in section 3.3
of WS-Addressing 1.0 – Core [WSADDR]….[line 535]”.
These should be consistent. Suggest making line 530 match the
reference description in line 535.
- Line 571-572
– spacing. Delete the spacing between the first and second
lines of the paragraph.
- State Tables
(C1-C4). The orientation and formatting is off when the tables are
printed. The line numbers overflow the print margins.
Substantive
editorial comments
- Abstract (page 1) calls
BusinessAgreementWithParticipantCompletion and
BusinessAgreementWithCoordinatorCompletion “two specific agreement
coordination protocols for the business activity coordination
type”. Shouldn’t this be agreement coordination
protocols for the Atomic Outcome and Mixed Outcome business activity
coordination types? No mention is made of the two coordination types
the specification defines.
- Inconsistent reference to this
specification. For example: Business Activity (lines 19, 45,
46, 50, 171, 174, 176, 200). In other places in the spec, it is
called WS-BusinessActivity (lines 14, 508). Given that Coordination
is consistently referred to as “WS-Coordination”, which is
also the pattern used for other WS-* specs, I suggest the
WS-BusinessActivity is the appropriate convention to reduce confusion
about generic business activities vs. this specification. For
example, lines 23-33 define the characteristics of business activities,
not WS-BA. But Lines 200-201 define the WS-BusinessActivity spec
coordination types, not generic “Business Activities”.
- Line 34 – “These
characteristics lead to a design point, with the following
assumptions:” It’s not clear to me what this sentence is
trying to accomplish. What is the distinction between the
characteristics outlined in lines 24-33 vs. what follows in lines
36-42?
- Lines 65 and 68 –
Antecedent for “It” at the beginning of each bullet is
unclear. The lead into the bullet list on line 50 states
“Business Activity Coordination protocols provide the following
flexibility”. ”It allows…..” doesn’t
make sense in that context.
- Unused references. Should
these be non-normative? The OASIS template includes a
“Non-normative References” section immediately following the
“Normative References”:
- Line 132 – [XML-ns]
- Line 136 – [XML-Schema2]
- Line 15 – [BPEL]
- When I print the spec, somehow
Word generates a duplicate section of preconditions around line 338
(copied and pasted below). I think this is related to the cross
reference on line 336 to section 3.1 (that’s where it’s
occurring). The link to section 3.1 works, so I’m not sure why
the print option is causing this to occur:
3.4 In addition to the notifications in Section 3.1
Preconditions
The correct operation of the
protocols requires that a number of preconditions must be established prior to
the processing:
1.
The source SHOULD have knowledge of the destination's
policies, if any, and the source SHOULD be capable of formulating messages that
adhere to this policy.
2.
If a secure exchange of messages is required, then the
source and destination MUST have appropriate security credentials (such as
transport-level security credentials or security tokens) in order to protect
messages.
BusinessAgreementWithParticipantCompletion
Protocol above, the Business Agreement with Coordinator Completion protocol
supports the following:
The coordinator accepts:
- Line 426 – Line
(6) in the assertion example “xmlns:wsat=http://docs.oasis-open.org/ws-tx/wsba/2006/06”
should be “xmlns:wsba=http://docs.oasis-open.org/ws-tx/wsba/2006/06”
- Lines 531-568
(Glossary) - The following are not included: Compensated, Closed,
Canceled, Cannot Complete, Failed, Exited, Not completed. While an
understanding of these can be derived from the existing definitions for
Compensate, Close, Cancel, Complete, Fail and Exit, it may not be clear to
the reader. One possibility would be to pair them: Cancel /
Canceled.
- Line 565-568
– Definition of Scope is inconsistent with what is used in line 52.
- Line 51:
“A business activity scope is a business task consisting of a
general purpose computation carried out as a bounded set of
operations…..”
- Line 566:
“A business activity instance….”
Business task vs. business
activity instance? This seems rather circular and unclear. The
glossary also uses the term ‘hierarchy of scopes’ while the test
around line 51 uses ‘nested scopes”.
10. There’s several
uses of the word transaction in the spec. Is that the accepted
terminology as opposed to activity (seems to be mixed in parts of the spec)
11. Notifications
- The CoordinatorCompletion
protocol specifies 2 additional notifications that the coordinator
accepts in addition to that of ParticipantCompletion. However, it
looks like the notifications are already defined in
ParticipantCompletion. The only difference is when the notifications are
allowed to be sent. I would strongly suggest that the paragraph
under CoordinatorCompletion point out this difference and this difference
only instead of repeating what was already said above. It’s
easy to miss and the section would make more sense with the suggested
change.
- State table
- Some notifications that make a
transition to the ‘Ended’ state have no ‘Action to
take’. Is the default action then to Ignore?
|