2 Replies Latest reply on Aug 29, 2008 1:16 PM by Mark Little

    XTS Participant APIs for use by Web Service-specific code

    Andrew Dinn Master

      Ok, I raised a JIRA (JBTM-393) to cover any possible action on this but it really needs discussion first. Here is what I wrote in the JIRA:


      The BAWithXXXCompletionParticipant interfaces which define the API implemented by Web service-specific participant implementations (and also the participant stubs on the coordinator side) include methods with the following signatures:

       public String status() throws SystemException;
       public String unknown() throws SystemException;
       public String error() throws SystemException;
      


      These appear to relate (vaguely) to the BA protocol message pair GetStatus (request) and Status (response) which can be initiated from either the coordinator or the participant. If so then they appear to be inappropriate as part of the Web service-specific API. The application does not and, indeed, should not need to know about the state model employed by the protocol implementation. status() probably ought to be dropped and maybe also the other two. However, it may be that error and unknown are intended to be called during recovery processing or,perhaps, even normal processing (e.g. if the participant receives an InvalidState fault or a Failed message). So, this needs to be clarified first.

      The message handlers for the i) GetStatus and ii) Status messages are currently implemented, respectively, i) to dispatch a Status message with the current (service or coordinator-side) participant engine state and ii) to do nothing. The current implementation does not ever dispatch a GetStatus message -- it is not necessary to do so for the purpose of implementing recovery on either the coordinator or the participant side. Since the BA spec provides no details as to when or how these messages are to be used the current implementation is, perhaps, appropriate, This needs to be clarified and, if necessary, the code modified to verify its use.


      So, I will start the discussion with a question. Anyone know the intention behind defining the Participant API this way?

      I can't see why status() is specified to return a String -- what String generated by the Web service would be meaningful here? I can see how it might conceivably be useful for the participant engine to tell the participant what its status is (using, say, a String rendering of one of the predefined State values) but not the other way round.

      The other methods might be helpful during recovery or when processing failure notifications but, once again, I am not exactly sure what the envisaged scenario is that is not covered by the actions detailed in the transition tables. This is maybe where the GetStatus/Status messages come into the equation.

      It looks as if the spec was designed so that the coordinator would check up on its participants (or rather the engines which wrap them) during crash recovery by sending GetStatus and seeing what state they thought they were in. Ditto the participants (the engines) would use GetStatus to check what the coordinattor thought their status was during crash recovery.

      Is this actually necessary? Do the state transitions not ensure that each participant knows exactly what to do in the event that it is recovered and reactivated?

      Is the idea of unknown() that it provides a way for a reactivated participant to clear up its compensation data? If so then why is this not covered by the normal state transitions?

      Is error() supposed to be called when a failure occurs? This does not seem very helpful because the participant will normally only send FAIL to the coordinator and get a FAILED response because the participant has thrown an exception.


        • 1. Re: XTS Participant APIs for use by Web Service-specific cod
          Mark Little Master

           

          "adinn" wrote:
          Ok, I raised a JIRA (JBTM-393) to cover any possible action on this but it really needs discussion first. Here is what I wrote in the JIRA:


          The BAWithXXXCompletionParticipant interfaces which define the API implemented by Web service-specific participant implementations (and also the participant stubs on the coordinator side) include methods with the following signatures:

           public String status() throws SystemException;
           public String unknown() throws SystemException;
           public String error() throws SystemException;
          


          These appear to relate (vaguely) to the BA protocol message pair GetStatus (request) and Status (response)



          Almost. These operations existed in the API before there was anything equivalent in the WS-TX specification, let alone the WS-TX standard. So before I go on, a quick history lesson: XTS began life as an offshoot of HP-WST, which was based on OASIS BTP. When that fizzled out we began to target WS-T 1.0 (the precursor to WS-TX) but also WS-CAF (and in this case WS-LRA). Some of the operations that appear in the API we've got now reflect more on what was in WS-CAF that WS-TX because the interfaces were richer (and still are in some ways).

          Anyway, I digress slightly.

          Eventually WS-TX 1.0 moved to adopt status operations. But even then they are not exactly the same. You also need to know that recovery was pretty poorly defined in the earlier drafts of the WS-T specification (it hasn't really improved that much, to be honest). These are (or were) meant more for recovery purposes. I'm assuming you've read the comments in the code, as they do explain them somewhat.



          which can be initiated from either the coordinator or the participant. If so then they appear to be inappropriate as part of the Web service-specific API. The application does not and, indeed, should not need to know about the state model employed by the protocol implementation.



          They're not there for the application, they are there for the participant implementation. Think RecoveryCoordinator in OTS, with it's replay_completion.



          status() probably ought to be dropped and maybe also the other two. However, it may be that error and unknown are intended to be called during recovery processing or,perhaps, even normal processing (e.g. if the participant receives an InvalidState fault or a Failed message). So, this needs to be clarified first.



          status is meant to be called by the coordinator on the participant. Like "how are you doing, please to meet you, now can you please tell me where you are in the protocol." So this is part of top-down recovery.

          unknown and error are the reciprocal operations for when the participant calls up (bottom-up recovery) to the coordinator "nice to meet you, can you please tell me what's happening with the transaction I was within?"



          The message handlers for the i) GetStatus and ii) Status messages are currently implemented, respectively, i) to dispatch a Status message with the current (service or coordinator-side) participant engine state and ii) to do nothing. The current implementation does not ever dispatch a GetStatus message -- it is not necessary to do so for the purpose of implementing recovery on either the coordinator or the participant side. Since the BA spec provides no details as to when or how these messages are to be used the current implementation is, perhaps, appropriate, This needs to be clarified and, if necessary, the code modified to verify its use.



          I'd like to go through the recovery details you've got in your head at the moment and see how you're expecting to replace these current calls. Is there something I can read?


          So, I will start the discussion with a question. Anyone know the intention behind defining the Participant API this way?

          I can't see why status() is specified to return a String -- what String generated by the Web service would be meaningful here? I can see how it might conceivably be useful for the participant engine to tell the participant what its status is (using, say, a String rendering of one of the predefined State values) but not the other way round.


          Hopefully that's answered now? It was a QName originally.


          The other methods might be helpful during recovery or when processing failure notifications but, once again, I am not exactly sure what the envisaged scenario is that is not covered by the actions detailed in the transition tables. This is maybe where the GetStatus/Status messages come into the equation.


          Maybe, but the spec. only covers the basics. For example, where in WS-AT does it talk about top-down or bottom-up recovery ;-) ?


          It looks as if the spec was designed so that the coordinator would check up on its participants (or rather the engines which wrap them) during crash recovery by sending GetStatus and seeing what state they thought they were in. Ditto the participants (the engines) would use GetStatus to check what the coordinattor thought their status was during crash recovery.

          Is this actually necessary? Do the state transitions not ensure that each participant knows exactly what to do in the event that it is recovered and reactivated?


          And what about time outs, autonomous choices etc. BA does not avoid heuristic decisions. No matter what we might have tried to hide in WS-AT, it doesn't either.


          Is the idea of unknown() that it provides a way for a reactivated participant to clear up its compensation data? If so then why is this not covered by the normal state transitions?


          No. The idea (back then) was that the participant does an upcall to a transaction manager asking for the status of transaction XYZ. That transaction isn't available any more so it must have rolled back. Just like OTS, the participant expects a status (unknown in this case, which can be interpreted as rolled back), even if the act of enquiring also kicks of recovery top-down.


          Is error() supposed to be called when a failure occurs? This does not seem very helpful because the participant will normally only send FAIL to the coordinator and get a FAILED response because the participant has thrown an exception.


          No. Similar to above, it's the coordinator-side (or something acting on its behalf, like the SOAP stack at the coordinator or participant) that drives these messages. In this case the participant has enquired as to the status of the transaction and there has been an error, e.g., a comms failure. Because all of the interactions are modeled as one-way's we need some way of communicating that back to the participant.

          BTW, it may be useful to check out the WS-CAF docs because at least in those we also included interaction diagrams :-)

          • 2. Re: XTS Participant APIs for use by Web Service-specific cod
            Mark Little Master

            Just another BTW ;-) I am fairly sure that those operations can be removed in favour of the equivalents in the 1.1 specification. I'll have to check because I think we added more status-like ops in the 1.2 version.

            Obviously the 1.0 version (pre-OASIS) is something different though, since status/getStatus didn't exist in the 2003 version of the specification.