- From: Charlton Barreto <cbarreto@adobe.com>
- Date: Tue, 19 Jul 2005 12:07:28 -0700
- To: wschor Group <public-ws-chor@w3.org>
- Message-id: <BBB21300-2534-4F92-BA50-08E7CA0F03D7@adobe.com>
Hi, Below are my editorial comments for the Primer. I am working on my set of semantic comments for the Primer which I hope to provide by mext weeks call at latest. Cheers, -Charlton. Charlton Barreto P 1.408.536.4496 cbarreto@adobe.com www.adobe.com Primer Editorial Comments Section 1.1, Paragraph 1, Sentence 2 I would suggest rewording this into something similar to: "The first three sections are intended for both audiences, while the last is intended primarily for software professionals." Section 1.1, Paragraph 1, Sentences 3 & 4 I would suggest inverting these two sentences, and simplifying into something similar to: "The first half of section 3 describes and example using UML diagrams; the second half walks through building a WS_CDL description of the example." Section 1.1, Paragraph 1, Sentence 5 I would suggest inverting the phrases in this sentence and reworking into something similar to: "The former is targeted at both audiences of this document, while the latter is primarily directed at software professionals, yet can be useful to business analysts for further context and understanding." Section 2, Paragraph 2, Sentence 2 This sentence may read better as: “The distinction between SOA and Web services is that the latter requires a Web Services Description Language (WSDL) interfaces, while the former may not have one.” Section 2, Paragraph 2, Sentence 3 Change "Web Service Services" to "Web Services" Section 2, Paragraph 3, Sentence 6 Suggest we revise this to read: "What WS-CDL allows one to do is describe the effective ordering constraints across the services and so describe the common rules and common behavior in order for the services to collaborate, which is why we call it “common collaborative behavior”." Section 2, Paragraph 4, Sentence 2 Suggest we revise this to read: "Instead, it describes as peers the entire collaborative observable behavior of all of the services, such that no one service can be said to exert control over any other service. In effect, it describes the services as a complete distributed application, in which each service plays a distinct role, and has distinct relationships with it’s peer services." Section 2, Paragraph 5, Sentence 2 Suggest we revise this to read: "The least interesting scenario, which WS-CDL can be used to describe, is a set of services that never synchronize at all; that is, there are neither any observable relationships and or any statement of an unobservable relationship between the services." Section 2, Paragraph 5, Sentence 3 Suggest we revise to read: "In this case, the services perform a choreography, but effectively on different stages, and thus need no form of coordination (e.g. a buyer and seller choreography for WalMart versus a Bloomberg Reuters choreography for the exchange of news items). In all other cases, the synchronization is what makes the interaction interesting (e.g. a buyer-seller choreography coupled with a seller credit check choreography or indeed a seller shipper choreography)." Section 2, Paragraph 6, Sentence 1 Suggest we revise the last part of this sentence to read: "(e.g. has the bartering choreography between buyer and seller “started”, or has it “finished”)." Section 2.1, Paragraph 1 Suggest we revise this to read: "WS-CDL is a description language, not an executable language - hence the term “Description” in it’s name. As it is a language that can be used to unambiguously describe observable service collaborations, we might also refer to this as business protocols within and across domains of control, that govern how the services interact." Section 2.1, Paragraph 2, Sentence 1 Suggest we revise this to read: "When WS-CDL is focused on describing collaboration within a domain of control, it is used to describe the internal workflows that involve multiple services (also called end- points) that constitute observable collaborative behavior." Section 2.1, Paragraph 2, Sentence 2 Would it be preferable to use "negotiated" rather than "agreed" in this sentence? Section 2.1, Paragraph 2, Sentence 4 Suggest we revise this to read: "You can think of it as a way of ensuring services are well-behaved with respect to the goals you wish to achieve within your domain." Section 2.1, Paragraph 3, Sentence 1 Suggest we revise this to read: "When the focus is across domains of control, WS-CDL is used to describe the business protocols that exist across domains...." Section 2.1, Paragraph 3, Sentence 2 Suggest we revise this to read: "These protocols have some form of XML data format definition and proceed to describe the ordering of message exchanges using a combination of prose and UML sequence diagrams." Section 2.1, Paragraph 3, Sentence 3 Suggest we revise this to read: "WS-CDL provides an unambiguous way of describing the ordering of message exchanges, and in so doing, ensuring that the services that participate in observable collaborations based on such vertical standards can be guaranteed to conform to the choreography description." Section 2.1, Paragraph 3, Sentence 4 Suggest we revise this to read: "You can think of it as a way to ensure that services are well-behaved with respect to their common goals across domains." Section 2.2, Paragraph 2 Suggest we revise the last part of the paragraph to read: "...services that participate in a choreography are well-behaved on a continuous basis." Section 2.2, Paragraph 3 Suggest we revise this to read: "Both these benefits translate into greater up-time, and so increase top line profits. At the same time, they translate into less testing time and so reduce cost of delivery which decreases bottom line costs." Section 2.3, Paragraph 1, Sentence 1 Suggest we revise this to read: "WS-CDL is a layered language that provides different levels of expressability to describe a choreography." Section 2.3, Paragraph 1, Sentence 2 Would it be preferable to use "illustrated" rather than "shown"? Section 2.3, Paragraph 5, Sentence 1 It would be preferable to replace "because" with "as". Section 2.3, Paragraph 5, Sentence 2 Suggest we revise this to read: "...rather, they observe visible interactions and use the observations to determine their state with respect to the other roles." Section 2.3, Paragraph 6, Sentence 1 Suggest we revise this to read: "Some business protocols are defined exposing specific business rules." Section 2.3, Paragraph 6, Sentence 2 Suggest we revise this to read: "These constitute shared knowledge between the concerned roles; for example, we may terminate an order completion between a buyer and a seller when we calculate that the items delivered match the original order." Section 2.3, Paragraph 6, Sentence 4 Suggest we revise this to read: "...which implies that state management is needed." Section 2.3, Paragraph 7, Sentence 1 Suggest we revise this to read: "...globally accessed – or at least accessed between roles - when needed." Section 3, Paragraph 1, Sentence 2 Replace "and" with "an". Remove extraneous "e". Section 3.1, Paragraph 1, Sentence 2 Remove "In this example" so that the sentence reads: "The buyer interacts with the seller...." Section 3.1, Paragraph 1, Sentence 3 Suggest rewording to: "When a price is acceptable to the buyer, the buyer orders the relevant goods based on it, whereupon the seller checks their credit worthiness." Section 3.1, Paragraph 1, Sentence 4 Suggest rewording to: "If this is acceptable, the seller requests a delivery date from the shipper." Section 3.1, Paragraph 1, Sentence 5 Suggest rewording to: "In the example, the shipper communicates directly with the buyer once an agreed delivery date has been achieved, and informs the buyer of the delivery details." Section 3.1, Paragraph 3, Sentence 1 Suggest rewording to: "The Normal Collaboration, illustrated in Figure 2, shows the buyer requesting a quote and the seller responding with a quote." Section 3.1, Paragraph 3, Sentence 3 Suggest rewording to: "As the buyer’s credit rating is acceptable, the seller then confirms the order with the buyer and requests from the shipper delivery details that are passed back to the seller by the shipper." Section 3.1, Paragraph 4, Sentence 4 Suggest rewording to: "The shipper will have picked up all that is necessary from the seller, which received it from the buyer...." Section 3.1, Paragraph 5, Sentence 1 Would it be preferable to use "illustrated" rather than "shown"? Also reword the last phrase to read: "...and the seller sending back a quote response with an associated timeout." Section 3.1, Paragraph 5, Sentence 2 Suggest rewording the last phrase to read: "...demonstrating a classic race condition between the parties." Section 3.1, Paragraph 6, Sentence 1 Would it be preferable to use "illustrated" rather than "shown"? Section 3.1, Paragraph 6, Sentence 2 Suggest rewording to read: "After the buyer requests the quote, the seller responds, the buyer accepts it, the seller then checks the credit rating for the buyer." Section 3.1, Paragraph 6, Sentence 3 Suggest rewording to read: "In this case, the credit check agency determines that the credit rating is low, and returns a credit rejection to the seller, who in turn sends a credit rejection to the buyer and terminates the collaboration." Section 3.1, Paragraph 7, Sentence 1 Would it be preferable to use "illustrated" rather than "shown"? Section 3.1, Paragraph 8, Sentence 3 Suggest rewording to read: "The seller may respond by accepting the quote, sending a quote response message back to the buyer." Section 3.1, Paragraph 8, Sentence 4 Suggest rewording to read: "If the seller does not respond, the buyers update is subject to a timeout in the same way as the sellers quote is valid for a specified duration." Section 3.1, Paragraph 8, Sentence 5 Suggest rewording to read: "In receipt of a quote response from the seller, the buyer may accept the quote (by so doing enter into the act of buying with the seller), may request a further updated quote, or simply do nothing at all – allowing the quote to timeout." Section 3.2, Paragraph 1, Sentence 1 Suggest rewording to read: "In this section we introduce the fundamental concept of an interaction, which underpins WS-CDL thus defining the roles, tokens, channels, relationships, participants and variables necessary to use an interaction in describing the example’s business protocol." Section 3.2.1, Paragraph 1, Sentence 1 Suggest rewording to read: "The difference between roles and participants will be detailed later on; for the time beingwe can consider them as synonymous." Section 3.2.1, Paragraph 2, Sentence 1: Suggest rewording to read: "A collaboration is message exchange between the swim lanes of a sequence diagram." Section 3.2.1, Paragraph 4, Sentence 1: Suggest rewording to read: "In the example, when the buyer accepts a quote, it does some extra things so that the seller, on behalf of the buyer, can pass certain contact details to a third party. This third party can then contact the buyer to inform the buyer of the delivery details." Section 3.2.1, Paragraph 4, Sentence 2: Suggest rewording to read: "The buyer sends a quote acceptance to the seller. " Section 3.2.1, Paragraph 4, Sentence 4: Suggest rewording to read: "The shipper then uses this additional information to directly respond to the buyer." Section 3.2.1, Paragraph 6, Sentence 1: Suggest rewording to read: "In order to describe our interactions, we shall have to define the channelTypes for the channelVariable in the interaction, and for the channelTypes that enable channels to be passed between roles." Section 3.2.1, Paragraph 12, Sentence 2: Suggest rewording to read: "This simply allows the interaction to be referenced." Section 3.2.1, Paragraph 12, Sentence 3: This sentence may not be necessary. If retained, though, I would suggest rewording it to read: "We have chosen a long name for the sake of illustration, but in practice, shorter program-code based names would be more likely." Section 3.2.1, Paragraph 14, Sentence 1: Suggest rewording to read: "At this point, we can start to see that channels are an important part of the structure of a choreography." Section 3.2.1, Paragraph 14, Sentence 3: Suggest rewording to read: "We can also see the importance of the operations in how they are defined and bound to the choreography." Section 3.2.1, Paragraph 16: Suggest rewording to read: "In our example, we can go further as the exchange element also describes the variable in which an instance of a "2BuyerChannelType" is held at the buyer - namely, the 'DeliveryDetailsC' variable - and where its exchange will be rendered – in this case, into a variable of the same type called 'DeliveryDetailsC' that resides at the seller. In the send variable and receive variable, the variables are accessed using a WS-CDL function which names the variable, and optionally the role at which the variable resides. It this case, the latter parameter is not used, and is inferred based on the context. The context itself is based on the two ends of the channel and direction of the interaction." Section 3.2.2, Paragraph 2, Sentence 2: Suggest rewording to read: "This is the core of collaboration - identifying common interaction between peers." Section 3.2.2, Paragraph 4, Sentence 2: Suggest rewording to read: "This solely provides a name for the type of role we are defining. In the case of the buyer, we name it "BuyerRoleType"; then the "BuyerBehavior" is a name used to bind the implementation of an "BuyerRoleType" at some service end point." Section 3.2.2, Paragraph 1, Sentence 3: Suggest removing "So" such that the sentence reads: "In our example...." Section 3.2.2, Paragraph 3, Sentence 2: Replace "althought" with "though". Section 3.2.6, Paragraph 8, Sentence 2: Suggest rewording to read: "Firstly, the buyer sends a message to the seller accepting the quote, then sends a further message to the seller with the details of a channel that it passes to the seller." Section 3.2.6, Paragraph 8, Sentence 4: Suggest rewording to read: "This is done so that the buyer can receive delivery details back from a third party of which it has no knowledge." Section 3.2.6, Paragraph 8, Sentence 5: Suggest rewording to read: "This is achieved through channel passing, where we add details to a channel allowing it to pass others of a particular type." Section 3.3, Paragraph 1, Sentence 1: Suggest rewording to read: "...we can now begin to consider describing the choreography itself." Section 3.3.1, Paragraph 2, Sentence 2: Suggest replacing "And we shall..." with "We shall also...." Section 3.3.1, Paragraph 5, Sentence 2: Suggest replacing "And variables have..." with "Variables also have...." Section 3.3.1, Paragraph 5, Sentence 7: Suggest rewording to read: "...in some way, which can only be done...." Section 3.3.1, Paragraph 6, Sentence 1: Remove the superfluous "the" ("The abstract syntax for a choreography...."). Section 3.3.3, Paragraph 2, Sentence 2: Would it be preferable to use "illustrated" rather than "shown"? Section 3.3.3, Paragraph 3, Sentence 3: Suggest rewording "If it is false..." to "If false...", rewording the last phrase to read "as the condition ("barteringDone") itself evaluated to true", and removing the following sentence (Sentence 4). Section 3.3.4, Paragraph 4, Sentence 1: Suggest rewording to read: "The body of the above workunit is a choice. " Section 3.3.5, Paragraph 2, Sentence 5: Replace "effect" with "affect". Section 3.3.6, Paragraph 1, Sentence 3: Replace "detail" with "details". Section 3.3.6, Paragraph 2, Sentence 3: Replace "effect" with "affect". Section 4.1, Paragraph 1, Sentence 4: Reword to read: "...and make it a blocking workunit." Section 4.1, Paragraph 3, Sentence 3: Reword to read: "...which means that the two workunits operate concurrently. " Section 4.1, Paragraph 3, Sentence 4: Reword to read: "Obviously the second, being dependent on the first, waits until it’s preconditions are met before proceeding." Section 4.1, Paragraph 4, Sentence 1: Reword to read: "...how we handle the credit checking response, by introducing another variable, 'creditRatingOk', at the seller role, that records, as a Boolean, the response from the credit check. "
Received on Tuesday, 19 July 2005 19:07:49 UTC