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

[Andrew Dinn (JIRA)]

     [ https://jira.jboss.org/browse/JBTM-780?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Andrew Dinn closed JBTM-780.
----------------------------

    Fix Version/s: 4.13.0
       Resolution: Done


> 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

-- 
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators: https://jira.jboss.org/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira