XTS Participant APIs for use by Web Service-specific code
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.
