Details

    • Type: Sub-task
    • Status: Closed (View Workflow)
    • Priority: Major
    • Resolution: Done
    • Affects Version/s: None
    • Fix Version/s: 4.13.0
    • Component/s: None
    • Labels:
      None
    • Affects:
      Documentation (Ref Guide, User Guide, etc.)

      Description

      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

        Gliffy Diagrams

          Attachments

            Activity

              People

              • Assignee:
                Unassigned
                Reporter:
                mistysj Misty Stanley-Jones
              • Votes:
                0 Vote for this issue
                Watchers:
                0 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved: