[jbossts-issues] [JBoss JIRA] Closed: (JBTM-780) Integrate feedback from Andrew Dinn

Integrate feedback from Andrew Dinn ----------------------------------- Key: JBTM-780 URL: https://jira.jboss.org/browse/JBTM-780 Project: JBoss Transaction Manager Issue Type: Sub-task Security Level: Public(Everyone can see) Reporter: Misty Stanley-Jones Fix For: 4.13.0 Title Page 'Web Services Transactions' ought to capitalize it's 'T' here since this use identifies a category of transaction rather than a collection of them. Also can we lose the prefix and just call this the XTS Programmer's Guide? XTS stands for XML Transactions Service (which is a pretty dumb name but that's legacy for you) so the full shebang expands (to those who know what it means) to something even more meaningless than the qualified acronym. And it's rather a mouthful. I think the real problme is that there is no such thing as a Transactions XTS Programmer but there is such a thing as an XTS Programmer. Epithet transfer is a horrible phenomenon. P.1 "About This Guide" The original text here is virtually incoherent to anyone who does not already know what XTS is (not that it stands out much from much of what follows in that regard). It really needs replacing entirely "The XTS Programmer's Guide explains how to use Web Services Transactions to ensure that distributed business processes based on web services can be made resilient to system or network failures. XTS (XML Transaction Service) is JBoss's implementation of Web Services Transactions. It supports development and deployment of transaction-aware web services. It also enables web service clients to create and manage web service transactions from which they can then invoke transactional web services. XTS ensures that the client and web services achieve consistent outcomes even if the systems on which they are running crash or temporarily lose network connectivity. "XTS is compliant with the WS-Coordination, WS-Atomic Transaction and WS-Business Activity specifications. The implementation supports web services and clients which are based on the JaxWS standard; indeed, XTS is itself implemented using services based on JaxWS. While this guide discusses many Web Services standards like SOAP and WSDL, it does not attempt to address all of their fundamental constructs. However, basic concepts are provided where necessary." P.1 Prerequisites "Web services" This really ought always to be capitalised on both words as Web Services when it refers to the category or lower case on both words when it refers to one or more specific web services. "XML, SOAP, WSDL and UDDI" Drop UDDI as it is not mentioned and not needed "WS-C, WS-Atomic Transaction" Here and elsewhere WS-C should be spelled out as WS-Coordination whenever WS-AT or WS-BA is also spelled out. P. 3 Introduction para 2 "The JBoss Transaction Service Web Services API supports ..." Afraid that actually has to read "The JBoss Transaction Service Web Services Transactions API supports ..." It is misleading to suggest that JBossTS provides a Web Services API -- that's done by JBossWS. Perhaps "XTS API" might be better here? P.3 Protocols included in XTS XTS also automatically implements version 1.2 of these specs since they are functionally equivalent to 1.1. Perhaps this coudl also go in the note. P 3. para after note "These standards-based communication technologies customers, suppliers, and ..." should be "These standards-based communication technologies allow customers, suppliers, and ..." 2.2 Servlets 2nd para "In XTS, the active component is achieved through deployment of JaxWS endpoints. Each XTS endpoint that can be communicated with via SOAP/XML is published via JaxWS. Fortunately for the developer, this occurs transparently. The only drawback is that transactional client applications and transactional web services must reside within a domain capable of hosting JaxWS endpoints, such as an application server. In the case of Enterprise Application Platform, JBoss Application Server provides this functionality." The note should then read "The XTS 1.0 protocol implementation is based on servlets". 2.3 SOAP Para 2 This is not worth stating. Section 3: I think this is too much theory too early on. However, I'm not going to address the fact that this is not example based just now. That's a big job which I will need to think about a lot more befor e|I can remedy it. I'll merely try to make what is here more readable. P.7 Diagram "Application" probaby ought to be labelled "Client" or "Application Client" and "Application Service" ought to be "Web Service" or "Application Web Service" since client and web service ar eused everywhere else in the guide to refer to these two parties to the (distributed) application. The label "UDDI/WSDL" shoudl really jsut be "WSDL" since UDDI is a long dead pipe-dream. P.8 3.1 The Coordinator 1st para "The coordinator may be implemented as a separate service or may be co-located with the user for improved performance ..." Best to replace whole para with: "Every transaction is associated with a coordinator, which is responsible for governing the outcome of the transaction. When a client begins a Web Service transaction it posts a create request to a coordination service which creates the coordinator and returns its details to the client. This service may be located in its own container or may be colocated with the application client or with one of the transactional web services for improved performance. The coordination service is typically responsible for managing many transactions in parallel so each coordinator is identified by a unique transaction identifier. P.8 3.1 The Coordinator 2nd and 3rd para Change whole thing to "The coordinator is responsible for ensuring that the web services invoked by the client arrive at a consistent outcome. When the client asks the coordinator to complete the transaction the coordinator ensures that each web service is ready to confirm any provisional changes made it has made within the scope of the transaction. It then requests them all to make their changes. If any of the web services indicates a problem at the confirmation stage the coordinator ensures that all web services reject their provisional changes, reverting to the state before the transaction started. The coordinator also reverts all changes if the client asks it to cancel the transaction. "The negotiation between the coordinator and the web services is organised so as to ensure that all services will make their changes or all of them will revert to the previous state even if the coordinator or one of the web services crashes part way thorugh the transaction." 3.2 The Transaction Context "... known as the Context. ... it is still helpful ...". Scrub what lies in the middle and reword as "The coordination service hands a context back to the application client when it begins a transaction. This context is passed as an extra, hidden parameter whenever the client invokes a transactional web service. The XTS implementation saves and propagates this context automatically with only minimal involvement required on the part of the client. However, it is still helpful ..." 3.3 Participants "When a service begins performing work ... to follow." "When a web service receives its first service request in some given transaction it enrols with the coordinator as a participant, specifying the participant model it wishes to follow. As we have seen, the context helpfully contains a URL for the endpoint of the coordination service which handles enrollment requests" P.19 4.1.1 Activation para 1 This needs changing because the 1.1 servise is not asynchronous. The first para should be as follows "The WS-C framework exposes an Activation Service which supports the creation of coordinators for specific coordination protocols and retrieval of associated contexts. Activation services are invoked synchronously using an RPC style exchange. So, the service WSDL defines a single port declaring a CreateCoordinationContext operation. This operation takes an input specfying the details of the transaction which is to be created including the type of coordination required, timeout etc. It returns an output containing the details of the newly created transaction context i.e. the transaction identifier, coordination type and registration service URL." The WSDL text in the box should be as follows <!-- Activation Service portType Declaration --> <wsdl:portType name="ActivationCoordinatorPortType"> <wsdl:operation name="CreateCoordinationContext"> <wsdl:input message="wscoor:CreateCoordinationContext"/> <wsdl:output message="wscoor:CreateCoordinationContextResponse"/> </wsdl:operation> </wsdl:portType> And the note at the top of p. 20 should say "The 1.0 Activation Coordinator service employs an asynchronous message exchange comprised of two one way messages, so an Activation Requester service is also necessary." p 20 4.1.2 Registration This also needs changing as 1.1. is not asynchronous First para replace "The context returned by the activation service includes the URL of a Registration Service. When a web services receieves a service request accompanied by a transaction context it contacts the Registration Service to enrol as a participant in the transaction. The registration request includes a participant protocol defining the role the web service wishes to take in the transaction. Depending upon the coordination protocol, more than one choice of participant protocol may be available. "Like the activation service, the registration service assumes synchronous communication. Thus, the service WSDL exposes a single port declaring a Register operation. This operation takes an input specifying the details of the participant which is to be registered including the participant protocol type and returns a corresponding output response." The WSDL text in the box should be as follows <!-- Registration Service portType Declaration --> <wsdl:portType name="RegistrationCoordinatorPortType"> <wsdl:operation name="Register"> <wsdl:input message="wscoor:Register"/> <wsdl:output message="wscoor:RegisterResponse"/> </wsdl:operation> </wsdl:portType> The note at the bottom of p. 20 should say "The 1.0 Registration Coordinator service employs an asynchronous message exchange comprised of two one way messages, so a Registration Requester service is also necessary." P. 21 4.2 WS-Transaction Before lauching into this we should probably re-iterate the definition of WS-T provided on page 3 "WS-Transaction (WS-T) comprises the pair of transaction coordination protocols, WS-Atomic Transaction (WS-AT) and WS-Business Activity (WS-BA), which utilize the coordination framework provided by WS-Coordination (WS-C). WS-Transactions was developed to unify existing traditional ..." P. 21 4.2.1 WS Coordination Foundations The title here should really be "WS-Transaction Foundations" since this is what is being described. Also, the subsequent text needs reorganising. "An important aspect of WS-Transaction that differs from traditional transaction protocols is that a synchronous request/response model is not assumed. This is because WS-Transaction is layered upon the WS-Coordination protocol whose own communication patterns are asynchronous by default, as shown in ..." The 'because ...' reason provided here is not only no longer true it is also not a valid rationale for the choice of asynchronous communications. This should be changed to "WS-Transaction is layered upon the WS-Coordination protocol, as shown in ..." The content in the original opening line needs to be relocated to the end of section 4.2.1 after numbered list item 2. "An important aspect of WS-Transaction that differs from traditional transaction protocols is that a synchronous request/response model is not assumed. Sequences of one way messages are used to implement communications between the client/participant and the coordination services appropriate to the transaction's coordination and participant protocols. This is significant because it means that the client and participant containers must deploy XTS service endpoints to receive messages from the coordinator service." "This requirement is visible in the details of the Register and RegisterResponse messages declared in the Registration Service WSDL above (example 4.2). The Register message contains the URL of an endpoint in the client or web service container. This URL is used when a WS-Transaction coordination service wishes to dispatch a message to the clinet or web service. Similarly, the RegisterResponse message contains a URL iendtifying an endpoint for the protocol-specific WS-Transaction coordination service for which the client/web service is registered, allowing messages to be addressed to the transaction coordinator." P. 22 Section 4.2.2 Opening para Use of the bare word 'service' here is highly ambiguous since we have just been talking about all sorts of services implemented by XTS. It actually refers to an application web service. The main distinction which the original author was trying to make is between the transactional web service per se, i.e. acting as a web service executing business-logic, vs the transactional web service acting as a participant in the transaction, i.e. communicating with and responding to its transaction coordinator (via the transaction coordination service). It's about as clear as mud to anyone who does not already understand it. I would rewrite the first para as follows: "WS-Transaction distnguishes the transaction aware web service per se, i.e. in its role executing business-logic, from the web service acting as a participant in the transaction, i.e. communicating with and responding to its transaction coordinator. Transaction-aware web services deal with application clients using business-level protocols, while the participant handles the underlying WS-Transaction protocols, as shown Figure 4.4, “WS-Transaction Global View”." Then in the next two paras each occurence of 'service' need to be changed to 'web service'. In the following paragraph (1st on p 23 after fig 4.5) the reference to JAXTX needs to be got rid of as this is a dead specification. Also, the explanation is rather cack-handed and attributes responsibility to the wrogn agents. It neds rewording as follows: "The transaction-aware web service employs a back end database accessed via a JDBC driver which sends SQL statements to the database for processing. However, those statements should only commit if the enclosing web service transaction does. For this to work, the web service must employs transaction bridging, registering a participant with the coordinator for the web service transaction and creating a matching XA transaction within which it can invoke the driver to make tentative changes to the database. The web service ensures that service requests associated with a specific web service transaction are executed in the scope of the corresponding XA transaction, grouping changes common to a given transaction while isolating changes belonging to different transactions. The participant responds to prepare, commit or rollback requests associated from the web service transaction coordinator by forwarding the same operations to the underlying XA transaction coordinator, thus ensuring that the local outcome in the database corresponds with the global outcome of the web service transaction as a whole." P. 23 4.2.3.1 Atomic Transactions 2nd sentence "Within the scope of an AT, services ... " to end of para. "Within the scope of an AT, web services typically employ bridging to allow them to access XA resources, such as databases and message queues, under the control of the web service transaction. When the transaction terminates, the outcome decision of the AT is propagated to the XA resources via the participant, and the appropriate commit or rollback actions are taken by each." P. 32 1st para last sentence(we are in section 5.1.3) "These handlers are designed to work with JAX-RPC and JAX-WS clients." JAX-RPC is no longer supported in the product so it would be better to reword this as "These handlers are designed to work with JAX-WS client." and then add a note which say "A JAX-RPC handler is provided for the 1.0 implementation." and then remove any further reference to the JAX-RPC handler. In particular, the content in 5.1.3.1 is worng because it refers to a JAX-RPC handler in the wst11 package and there is no such handler. P. 33 5.2.2 Service-Side Handler Configuration The doc should only refer to JAX-RPC as a note for 1.0. So, the first para 4th sentence should say "XTS provides a JaxWS handler ..." and then the opening sentence of the 2nd para should say "The JaxWS service side handler comes in two different versions." P. 34 5.2.2.1 JAX-RPC Service Context Handlers This should be dropped as JAX-RPC is not supported. P. 34 5.2.2.2 JAX-WS Service Context Handlers A spurious header "5.2.3 Implementing the Business Logic" has crept in here. The text that follows belongs to 5.2.2.2. The spurious header is then repeated (in the slightly modified but correct form) at the end of the 5.2.2.2 text on p 36 as "5.2.4 Implementing the Web Service Business Logic". P. 35 5.2.4 This section is worse than useless as it proposes somethign which the user cannot do, which we do not intend to do and which the bridge code (when it eventually arrives in EAP) will make irrelevant. It should be deleted. P. 37 Durable2PCParticipant Signatures prepare "The implementation can go to any lengths in order to fulfill the implicit contract between it and the coordinator." This was originally "The implementation is free to do whatever it needs to in order to fulfill the implicit contract between it and the coordinator." I think your change misses the point of the original. Your wording makes it sound as if the issue here is that the participant may need to perform arbitrarily large or complex amounts of work. The original is emphasising that that what the participant does below the call to prepare is unconstrained by any requirements imposed by the XTS code (other than returning one of the 3 possible return values). How much work it does is of no significance. P. 38 Volatile2PCParticipant Signatures prepare Same issue as the preceding one. P. 39 6.1.2. Business Activity This reads badly because of the way the references get formatted. Better phrasing would be "All Business Activity participants are instances of one or other of the interfaces described in Section 6.1.2.1, “BusinessAgreementWithParticipantCompletion” or Section 6.1.2.2, “BusinessAgreementWithCoordinatorCompletion”. As a more general comment I know the original text often used terms in the format "the XXX interface" to refer to a specific interface. However, it is actually much more natural parlance to say "interface XXX". So, for example at the end of para 1 of 6.1.2.1 it reads much clearer to a programmer if it says "... as per interface com.arjuna.wst11.BusinessAgreementWithParticipantCompletionParticipant." (not that anything with a name that long can ever really read very 'clearly' or 'naturally') P. 40 BusinessAgreementWithCoordinatorCompletion Signatures complete This is rather infortunately worded. Better would be "The coordinator is informing the participant all work it needs to do within the scope of this business activity has been completed and taht it should make permananent any provisional changes it has made." P. 40 BusinessAgreementWithCoordinatorCompletion Signatures unknown Missing 'is' "This method is deprecated ... " P. 41 6.1.2.3. BAParticipantManager 2nd para last sentence "This handle is an instance of the BAParticipantManager interface, located in com.arjuna.wst11.BAParticipantManager, with the methods listed in BAParticipantManager Methods." The 'located in' is a mash-up. Interface BAParticipantManager is located in package com.arjuna.wst11 so its full name (sometimes referred to as its package-qualified name) is com.arjuna.wst11.BAParticipantManager. So, this sentence would read much better as "This handle is an instance of interface com.arjuna.wst11.BAParticipantManager with the methods listed in BAParticipantManager Methods." P. 41 BAParticipantManager Methods exit "The participant uses the exit to inform the coordiantor ..." That should be either "the exit method to inform ..." or "method exit to inform ..." You then edited the following sentence "It will not be informed when (and how) the business activity terminates." changing it to "It is not informed when and how the business activity terminates." I understand your desire to normalise the narrative to present indicative. However, this change fails to get across the point here which is that calling exit means the participant is no longer be involved the business activity. So, whereas normally it would subsequently be informed when (and how) the business activity terminates, after calling exit it will not be informed when (and how) the business activity terminates. The next sentence has also, perhaps, had an ambiguity opened up (or exacerbated) by your edit from "This method may only be invoked while the participant is in state active (or completing in the case of a participant registered for the ParticipantCompletion protocol)." to "This method may only be invoked while the participant is in the active state, or the completing state in the case of a participant registered for the ParticipantCompletion protocol." The clause originally provided in paranthesis is meant to be additional rather than alternative to the first. This would maybe be clearer as: "This method may only be invoked while the participant is in the active state, or also the completing state in the case of a participant registered for the ParticipantCompletion protocol." (although, personally, I find the ambiguity is significantly lessened by the use of brackets since it leaves the first clause standing as much more definitive). P. 41 6.2.1 Note This note is misleading as the interfaces located in package com.arjuna.wst are still present but they are not the same interfaces since they belong to the 1.0 implementation and have a very slightly different definition. It would be better to say "The corresponding participant interfaces used in the 1.0 protocol implementation are located in package <code>com.arjuna.wst</code>." P. 42 6.2.2 Deploying Participants This section was almost completely incoherent when it was first written, addressing problems which would only exist in the mind of an XTS implementor. Although you made a valiant attempt I don't think your edits have really made what little it was saying that much clearer, even given the large scope for improvement, but they have made it mercifully shorter. I think this needs replacing with something expressing what actually needs to be said. "Transactional web services and transactional clients are deployed by placing them in the application server deploy directory alongside the XTS service archive (SAR). The SAR exports all the client and web service API classes needed to manage transactions and enroll and manage participant web services. It provides implementations of all the WS-C and WS-T coordination services, not just the coordinator services. In particular, this it exposes the client and web service participant endpoints which are needed to receive incoming messages originating from the coordinator." "Normally, a transactional application client and the transaction web service it invokes will be deployed in different application servers. As long as the XTS SAR is deployed to each of these containers XTS will transparently route coordination messages from clients or web services to their coordinator and vice versa. When the the client begins a transaction by default it creates a context using the coordination services in its local container. The context holds a reference to the local Registration Service which means that any web services enlisted in the transaction enrol with the cooridnation services in the same container." "The coordinator does not need to reside in the same container as the client application. By configuring the client deployment appropriately it is possible to use the coordinator services co-located with one of the web services or even to use services deployed in a separate, dedicated container. See Chapter 8 Stand-Alone Coordination for details of how to configure a coordinator located in a different container to the client." P. 42 6.2.2. Note This stands as is except that the second occurence of 'were' in the 1st sentence is redundant. P. 44. 7.1.2 Note Same issue as for P. 41 6.2.1 Note P. 44 7.1.3 UserTransaction 1st para 1st sentence "com.arjuna.mw.wst11.UserTransaction is the class that clients or services typically employ" That really ought to just say "clients" rather than "clients or services" as web services rarely, if ever, start transactions. By the same token it would probably be best to add at the start of 7.1.5 TransactionManager "com.arjuna.mw.wst11.TransactionManager is the class that web services typically employ" P. 44 userTransaction Methods begin Parameters timeout First, a general comment. It is conventional to list parameters before exceptions since knowing what the parameters are is often necessary in order to understand the possible exceptions but never the other way round. So, this re-ordering should apply to all the following section. Secondly, this is not quite the right explanation. "This optional parameter, measured in milliseconds, specifies a time interval after which the newly created transaction may be automatically rolled back by the coordinator" P. 44 userTransaction Methods commit The second sentence does not really make sense since execute is not an appropriate verb to use in the context of a protocol. It would be better to say "Volatile2PC and Durable2PC participants enlisted in the transaction are requested first to prepare and then to commit their changes. If any of the participants fails to prepare in the first phase then all other participants are requested to abort." P. 44 userTransaction Methods commit Exceptions TransactionRolledBackException This explanation does not make sense. "The transaction was rolled back either because of a timeout or because a participant was unable to commit." P. 45 TransactionManager "service-side user" is not the best choice of words here. Better would be just to say "web service" or "transactional web service". P. 45 TransactionManager Methods resume The Exceptions list here should be preceded by a Parameters subhead with a single parameter. "txContext A TxContext instance as returned by suspend identifying the transaction to be resumed." Also, WrongStateException is not applicable as an exception for this method. It looks like this has got mangled as it and the explanation for it being thrown are appropriate to the two enlist methods which follow on p 46. P. 46 TransactionManager Methods enlistForVolatile/DurableTwoPhase There appears to be a dangling Parameters subhead above these two methods and missing Parameters/Exceptions subheads after each method description. Terminology?! The method name used here is enlist but the verb used up to now has been enroll. Perhaps we should change enroll globally to enlist? (both terms are perfectly acceptable transactions-speak). If we stick with enroll then the text here should say enroll even though the method name uses enlist. The Parameters section for enlistForVolatileTwoPhase should say "participant An implementation of interface Volatile2PCParticipant whose prepare, commit and abort methods are called when the corresponding coordinator message is received. id A unique identifier for the participant. The value of this String should differ for each enlisted participant. It should also be possible for a given identifier to determine that the participant belongs to the enlisting web service rather than some other web service deployed to the same container." The Parameters section for enlistForDurableTwoPhase should say "participant An implementation of interface Durable2PCParticipant whose prepare, commit and abort methods are called when the corresponding coordinator message is received. id A unique identifier for the participant. The value of this String should differ for each enlisted participant. It should also be possible for a given identifier to determine that the participant belongs to the enlisting web service rather than some other web service deployed to the same container." The Exceptions section for these two methods is the same "UnknownTransactionException No transaction is associated with the invoking thread. WrongStateException The transaction is not in a state where new participants may be enrolled (e.g. it is terminating)" P. 46 7.2.1 Same issue as for P. 41 6.2.1 Note P. 46 7.2.2 UserBusinessActivity 1st para 1st sentence "com.arjuna.wst11.UserBusinessActivity is the class that most clients or services typically employ" That really ought to just say "clients" rather than "clients or services" as web services rarely, if ever, start transactions. By the same token it would probably be best to add at the start of 7.2.4 BusinessActivityManager "com.arjuna.mw.wst11.BusinessActivityManager is the class that web services typically employ" P. 46 7.2.2 UserBusinessActivity 1st para 2nd sentence "A client begins a new atomic transaction first obtaining a UserBusinessActivity from the UserBusinessActivityFactory." That should say "a new business activity by first..." rather than "a new atomic transaction by first...". P. 46 7.2.2 UserBusinessActivity Methods close Once again the second sentence tries to "execute" a protocol whicch makes no sense. Also, it is the wrong protocol! Better replace this with: "First, all Coordinator Completion participants enlisted in the activity are requested to complete the activity. Next all participants, whether they enlisted for Coordinator or Participant Completion, are requested to close the activity. If any of the Coordinator Completion participants fails to complete at the first stage then all completed participants are asked to compensate the activity while any remaining uncompleted participants are requested to cancel the activity." TransactionRolledBackException should probably say a little more "The activity has been cancelled because one of the Coordinator Completion participants failed to complete. This exception may also thrown if one of the Participant Completion participants has not completed before the client calls close." P. 46 7.2.2 UserBusinessActivity Methods cancel The description is somewhat lacking. "Terminates the business activity. All Participant Completion participants enlisted in the activity which have already completed are requested to compensate the activity. All uncompleted Participant Completion participants and all Coordinator Completion participants are requested to cancel the activity." The paragraph about Coordinator Completion participants which follows the exceptions for cancel is redundant (it's also incorrect). The complete method has been deprecated and so it should not be documented. P. 47 BusinessActivityManager "service-side user" This is the same issue as P. 45 TransactionManager above p 47 BusinessActivityManager Methods currentTransaction missing 't' in currentTransaction p 47 BusinessActivityManager Methods resume This should have a Parameters subhead subhead defining one parameter "txContext A TxContext instance as returned by suspend identifying the transaction to be resumed." Also, the Exceptions section is incorrect. WrongStateException is not thrown by resume. Finally, the enlist methods which follow have suffered the sam efate as htose for TransactionManager. They should not be preceded by a Parameters subhead. They should each have a Parameters and Exceptions subhead following the method description. We ar ealso up against teh enlist enroll terminology problem again. The text should be: "enlistForBusinessAgreementWithParticipantCompletion Enroll the specified participant with current business activity, causing it to participate in the BusinessAgreementWithParticipantCompletion protocol. A unique identifier for the participant is also required. The return value is an instance of BAParticipantManager which can be used to notify the coordinator of changes in the participant state. In particular, since the participant is enlisted for the Participant Completion protcol it is expected to call the completed method of this returned instance when it has completed all the work it expects to do in this activity and has made all its changes permanent. Alternatively, if the participant does not need to perform any compensation actions should some other participant fail it can leave the activity by calling the exit method of the returned BAParticipantManager instance. Parameters participant An implementation of interface BusinessAgreementWithParticipantCompletionParticipant whose close, cancel and compensate methods are called when the corresponding coordinator message is received. id A unique identifier for the participant. The value of this String should differ for each enlisted participant. It should also be possible for a given identifier to determine that the participant belongs to the enlisting web service rather than some other web service deployed to the same container. UnknownTransactionException No transaction is associated with the invoking thread. WrongStateException The transaction is not in a state where new participants may be enrolled (e.g. it is terminating)" enlistForBusinessAgreementWithCoordinatorCompletion Enroll the specified participant with current business activity, causing it to participate in the BusinessAgreementWithCoordinatorCompletion protocol. A unique identifier for the participant is also required. The return value is an instance of BAParticipantManager which can be used to notify the coordinator of changes in the participant state. Note that in this case it is an error to call the completed method of this returned instance. With the Coordinator Completion protocol the participant is expected to wait until its completed method is called before it makes all its changes permanent. Alternatively, if the participant determiens that it has no changes to make it can leave the activity by calling the exit method of the returned BAParticipantManager instance. Parameters participant An implementation of interface BusinessAgreementWithCoordinatorCompletionParticipant whose completed, close, cancel and compensate methods are called when the corresponding coordinator message is received. id A unique identifier for the participant. The value of this String should differ for each enlisted participant. It should also be possible for a given identifier to determine that the participant belongs to the enlisting web service rather than some other web service deployed to the same container. UnknownTransactionException No transaction is associated with the invoking thread. WrongStateException The transaction is not in a state where new participants may be enrolled (e.g. it is terminating)" P 49 8.1 Introduction This should document the release as ocnaitning only the 1.1 implementation. "The XTS service is deployed as a JBoss service archive (SAR). The version of the service archive provided with the Transaction Service implements the 1.1 versions of the WS-C, WS-AT and WS-BA protocols. You can rebuild the XTS service archive to include both the 1.0 and 1.1 implementations and deploy them side by side. See the service archive build script for for further details." p 49 8.2 Table 8.1 The 2nd column should have heading "Property", not parameter. The entry in the Format column is screwed up and unreadable. This appears to be because the entries in the parameter column are overflowing. P. 50 8.3 The XTS Service Archive This should have been explained at 6.2.2 where it is appropriate to talk about it (see the amendements above which provide this explanation). The text here is not relevant to Stand-Alone Coordination so this section should be deleted. P 51 Participant Crash Recovery WS-AT/BA Transaction You have split three sentences into two paragraphs with sub-heads here. However, the second sentence under the WSBA subhead "On rare occasions ... report transaction failures" applies to both protocols. This should appear below the two indented paragraphs at body text level to make it clear it is a rider to both of them. P. 52 1st new para 2st sentence missing "are" "... imply that they are ready to ..." P. 53 Example 9.1 There should be some white space indentation before the method declaration (i.e. preceding the text "byte[]"), preferably two spaces in a fixed width code font. P. 54 9.1.2.1.2 Recovering Participants at Reboot 2nd sentence "Registration is performed using the XTSATRecoveryManager class defined in the org.jboss.jbossts.xts.recovery.participant.at." There are two terminology issues here which also apply to quite a few subsequent occurences. Firstly, it is normal to say "in class XXX", not "the XXX class". The latter sounds distinctly odd to a programmer. Secondly, and much more importantly, you need to use the word "package" when you speak about a class's location. Java employs a hierarchical namespace for classes. The spaces in the hierarchy are called 'packages'. Classes which share the same prefix up to the last '.' in their full name belong to the same package and the prefix without the last '.' is used to name this package. Classes whose prefixes differ are in different packages. So, class org.my.foo.Foo and class org.my.foo.Foo2 are both in package org.my.foo while class org.my.foo.bar.Bar and org.my.baz.Baz are in different packages, org.my.foo.bar and org.my.baz. So this text ought to say "Registration is performed using class XTSATRecoveryManager defined in package org.jboss.jbossts.xts.recovery.participant.at" Oh, now there's a problem. The full stop at the end of the sentence should not be conflated as being part of the package name. Myabe suitable typography can make this clear. P. 54 Example 9.2 There should be the same white space indentation before each method declaration, preferably two spaces in a fixed width code font. The throws clause should be on a newline indented twice as much (ie. 4 spaces). p 54 2nd to last para I originally wrote "The XTS implementation does not know which participants belong to which recovery modules. ..." You edited this to "The XTS implementation does not map participants to recovery modules. ..." I understand that you may want to depersonify the code here, removing the suggestion of psychic attributes, but this translation is potentially confusing since "map" is a somewhat 'oversignified' term in computer la-la-land. Perhaps this would be clearer. "The XTS implementation cannot identify which participants belong to which recovery modules. This is the responsibility of the recovery module. ..." P. 55 WS-BA Coordinator Crash Recovery 2nd para 1st sentence missing "nor" "The coordinator does not need to account for any close messages sent before the crash, nor resend messages if it crashes several times." P. 55 9.2.2 WS-BA Participant Crash Recovery All the text is missing here! P. 56 9.2.3.1. Saving Participant Recovery State 2nd para after Example 9.4 This mentions "PersistableATParticipant" but it should mention "PersistableBAParticipant" P 57 9.2.3.2 2nd para Same error as previous