- From: Drew McDermott <drew.mcdermott@yale.edu>
- Date: Fri, 29 Jul 2005 23:09:32 -0400
- To: public-ws-chor-comments@w3.org
- CC: drew.mcdermott@yale.edu
Here are some proposed corrections to the latest draft of the Web Services Choreography Description Language (WS-CDL). URL: http://www.w3.org/2002/ws/chor/edcopies/cdl/cdl.html I've ordered them from "typos" to "stylistic infelicities." The typos are likely to be uncontroversial, but the later categories are probably too drastic to be useful at this stage. I'm sorry this took me so long. The notation for changes is [/pre/current/=>/suggested/post/] which means that the occurrence of pre-current-post should be changed to pre-suggested-post. If 'current' is empty, it means that 'suggested' should be inserted. If 'suggested' is empty, it means that 'current' should be deleted. Sometimes this notation is generalized to multiple 'current-suggested' pairs: [/p1/c1/=>/s1/p2/c2/=>s2/.../pK/] Typos In section 5.2, "Variables," and several other places, we have <ul> lists inside <ul> lists, and apparently the stylesheets to make them nest perspicuously are missing. [/Note that the Variable "OrderState" at the Buyer is a different Variable /to/=>/from/ the "OrderState" at the Seller//=>/.//] [/also used in this Choreography, thus sharing the Variable//=>/'/s information./] [/A perform activity MUST bind a free Variable defined in a/=>/n/ performed Choreography/] [/The OPTIONAL attribute free, when set to "false" specifies that /a/=>/the/ Variable is defined in this Choreography.] [/When this parameter is used, the /cureent/=>/current/ date information/] [/A Variable defined in a Choreography is visible for use in this Choreography and all its enclosed Choreographies/up-to/=>/up to/ the point that the Variable is /re-defined/=>/redefined/ as a/n/=>// non-free Variable, thus forming a Choreography Visibility Horizon for this Variable./] [/The OPTIONAL complete attribute /allows/=>/makes it possible/ to explicitly complete/] [/Alternatively, a Choreography in //=>/a /Successfully Completed State/] [/an exception causing activity is performed that has a /causeExeption/=>/causeException/ attribute value/] [/The actions/, including enclosed Choreographies that have not completed, within this Choreography/=>/ within this Choreography, including enclosed Choreographies that have not completed, / are completed abnormally before/] [/If more than one Finalizer Block/s are/=>/ is/ defined for the same Choreography/] [/Choreographies defined as requiring coordination must be/ing/=>// bound to a Coordination protocol./] In the CreditDecider example, the third comment is identical to the second; it should say "B" instead of "A" Grammatical Irregularities There are places in the document that are simply not legal English. I don't know how much that matters. Here is one-- [/By introducing this abstraction, a Choreography definition avoids referencing /directly the data types/=>/the data types directly/, as defined within a WSDL document or an XML Schema document.] Commas Misplaced Many sections of the document seem to follow German conventions for comma placement instead of English ones. For instance, in English, restrictive relative clauses must not be bounded by commas. It is almost never correct to separate subject and predicate by a comma. [/A Choreography in an Enabled State/,/=>// completes unsuccessfully/,/=>// when an Exception is caused in the Choreography/] [/The unsuccessfully completed Choreography/,/=>// enters the Closed State/] [/A Choreography in an Enabled State/,/=>// completes successfully when there are no more enabled activities within its body./] [/A Choreography/,/=>// in a Successfully Completed State/,/=>// enters the Closed State if no Finalizer Blocks were specified in that Choreography./] [/A Choreography/,/=>// in a Successfully Completed State with Finalizer Block(s) specified enters the Closed State/] [/When Choreography Coordination is not required, then the Choreography is not bound to a Coordination protocol/,/=>// and//=>/,/ since none of the above guarantees of agreement on the outcome apply//=>/,/ any required coordination should/] Stylistic Infelicities In this version all occurrences of <code> ...</code> are gone. This makes the document much less clear. I suppose this is some unfortunate W3C rule. [/The element roleType is used to identify/ the roleType of a party, being the type of the target of an information exchange, which is then used for statically determining where and how to send or receive information to or into the party. Each roleType is specified by the typeRef attribute of the roleType element. =>/a party (named by the typeRef attribute) that will be involved in an information exchange using this channel./] [/If two identity elements are specified within the same or different channelType elements, /that/=>/and they/ have the same set of named tokens in the same order, then they are considered to represent the same identity type./] [/This classification is used to indicate that this channel instance is correlated to a previous channel instance identity, and therefore//=> they are associated with/ the same choreography instance./] It's unfortunate that the word "capturing" is in the name of every kind of variable; since it's always there, it contains no information. Wouldn't it be cleaner to have "information-exchange variables," "state variables," etc.? In sect. 5.2, the paragraph starting "The value of Variables:" is extremely hard to understand. It's followed by three unordered lists, most of whose elements can't follow the initial phrase. In the first paragraph of section 5.4, we have "Variables contain values which MAY be populated or assigned...." What's the difference between being populated and being assigned? [/when an Exception is caused in the Choreography and its Exception Block/ is enabled, if present/=>/, if present, is enabled./] [/<li>/Other types of errors/=>/Some other kind of error occurs/, such as Protocol Based Exchange failures,/] [/The channelVariable attribute specifies the /Channel Variable containing information of a party, being the target of the Interaction, which is used for determining where and how to send and receive information to and into the party./=>/channel to be used to communicate during the interaction.//] (I _think_ this is the intended meaning; if not, then I have no idea what it means.) Why are so many of the examples laid out as single, overlong lines?
Received on Saturday, 30 July 2005 03:09:37 UTC