The participant is the entity that performs the work pertaining to transaction management on behalf of the business services involved in an application. The Web service (in the example code, a theater booking system) contains some business logic to reserve a seat and inquire about availability, but it needs to be supported by something that maintains information in a durable manner. Typically this is a database, but it could be a file system, NVRAM, or other storage mechanism.
Although the service may talk to the back-end database directly, it cannot commit or undo any changes, since committing and rolling back are ultimately under the control of a transaction. For the transaction to exercise this control, it must communicate with the database. In XTS, participant does this communication, as shown in Figure 6.1, “Transactions, Participants, and Back-End Transaction Control”.
All Atomic Transaction participants are instances of the Section 6.1.1.1, “Durable2PCParticipant” or Section 6.1.1.2, “Volatile2PCParticipant”.
A Durable2PCParticipant supports the WS-Atomic Transaction Durable2PC protocol with the signatures listed in
Durable2PCParticipant Signatures, as per the
com.arjuna.wst11.Durable2Participant interface.
Durable2PCParticipant Signatures
prepareThe participant should perform any work necessary, so that it can either commit or roll back the work performed by the Web service under the scope of the transaction. The implementation is free to do whatever it needs to in order to fulfill the implicit contract between it and the coordinator.
The participant indicates whether it can
prepareby returning an instance of thecom.arjuna.wst11.Vote, with one of three values.ReadOnlyindicates that the participant does not need to be informed of the transaction outcome, because it did not update any state information.Preparedindicates that the participant is ready to commit or roll back, depending on the final transaction outcome. Sufficient state updates have been made persistent to accomplish this.Abortedindicates that the participant has aborted and the transaction should also attempt to do so.
commitThe participant should make its work permanent. How it accomplishes this depends upon its implementation. For instance, in the theater example, the reservation of the ticket is committed. If commit processing cannot complete, the participant should throw a
SystemExceptionerror, potentially leading to a heuristic outcome for the transaction.rollbackThe participant should undo its work. If rollback processing cannot complete, the participant should throw a
SystemExceptionerror, potentially leading to a heuristic outcome for the transaction.unknownThis method has been deprecated and is slated to be removed from XTS in the future.
errorIn rare cases when recovering from a system crash, it may be impossible to complete or roll back a previously prepared participant, causing the
erroroperation to be invoked.
This participant supports the WS-Atomic Transaction Volatile2PC protocol with the signatures listed in Volatile2PCParticipant Signatures, as per the
com.arjuna.wst11.Volatile2Participant interface.
Volatile2PCParticipant Signatures
prepareThe participant should perform any work necessary to flush any volatile data created by the Web service under the scope of the transaction, to the system store. The implementation is free to do whatever it needs to in order to fulfill the implicit contract between it and the coordinator.
The participant indicates whether it can
prepareby returning an instance of thecom.arjuna.wst11.Vote, with one of three values.ReadOnlyindicates that the participant does not need to be informed of the transaction outcome, because it did not change any state information during the life of the transaction.Preparedindicates that the participant wants to be notified of the final transaction outcome via a call tocommitorrollback.Abortedindicates that the participant has aborted and the transaction should also attempt to do so.
- commit
The participant should perform any cleanup activities required, in response to a successful transaction commit. These cleanup activities depend upon its implementation. For instance, it may flush cached backup copies of data modified during the transaction. In the unlikely event that commit processing cannot complete, the participant should throw a
SystemExceptionerror. This will not affect the outcome of the transaction but will cause an error to be logged. This method may not be called if a crash occurs during commit processing.- rollback
The participant should perform any cleanup activities required, in response to a transaction abort. In the unlikely event that rollback processing cannot complete, the participant should throw a
SystemExceptionerror. This will not affect the outcome of the transaction but will cause an error to be logged. This method may not be called if a crash occurs during commit processing.- unknown
This method is deprecated and will be removed in a future release of XTS.
- error
This method should never be called, since volatile participants are not involved in recovery processing.
All Business Activity participants are instances one or the other of the interfaces described in Section 6.1.2.1, “BusinessAgreementWithParticipantCompletion” or Section 6.1.2.2, “BusinessAgreementWithCoordinatorCompletion” interface.
The BusinessAgreementWithParticipantCompletion interface supports the
WS-Transactions BusinessAgreementWithParticipantCompletion protocol with the
signatures listed in BusinessAgreementWithParticipantCompletion Signatures, as per interface
com.arjuna.wst11.BusinessAgreementWithParticipantCompletionParticipant.
BusinessAgreementWithParticipantCompletion Signatures
closeThe transaction has completed successfully. The participant has previously informed the coordinator that it was ready to complete.
cancelThe transaction has canceled, and the participant should undo any work. The participant cannot have informed the coordinator that it has completed.
compensateThe transaction has canceled. The participant previously informed the coordinator that it had finished work but could compensate later if required, and it is now requested to do so. If compensation cannot be performed, the participant should throw a
FaultedExceptionerror, potentially leading to a heuristic outcome for the transaction. If compensation processing cannot complete because of a transient condition then the participant should throw aSystemExceptionerror, in which case the compensation action may be retried or the transaction may finish with a heuristic outcome.statusReturn the status of the participant.
unknownThis method is deprecated and will be removed a future XTS release.
- error
In rare cases when recovering from a system crash, it may be impossible to compensate a previously-completed participant. In such cases the
erroroperation is invoked.
The BusinessAgreementWithCoordinatorCompletion participant supports the WS-Transactions
BusinessAgreementWithCoordinatorCompletion protocol with the signatures listed in
BusinessAgreementWithCoordinatorCompletion Signatures, as per the
com.arjuna.wst11.BusinessAgreementWithCoordinatorCompletionParticipant
interface.
BusinessAgreementWithCoordinatorCompletion Signatures
closeThe transaction completed successfully. The participant previously informed the coordinator that it was ready to complete.
cancelThe transaction canceled, and the participant should undo any work.
compensateThe transaction canceled. The participant previously informed the coordinator that it had finished work but could compensate later if required, and it is now requested to do so. In the unlikely event that compensation cannot be performed the participant should throw a
FaultedExceptionerror, potentially leading to a heuristic outcome for the transaction. If compensation processing cannot complete because of a transient condition, the participant should throw aSystemExceptionerror, in which case the compensation action may be retried or the transaction may finish with a heuristic outcome.completeThe coordinator is informing the participant all work it needs to do within the scope of this business activity has been completed and that it should make permananent any provisional changes it has made.
statusReturns the status of the participant.
unknownThis method is deprecated and will be removed in a future release of XTS.
errorIn rare cases when recovering from a system crash, it may be impossible to compensate a previously completed participant. In such cases, the
errormethod is invoked.
In order for the Business Activity protocol to work correctly, the participants must be able to autonomously notify the coordinator about changes in their status. Unlike the Atomic Transaction protocol, where all interactions between the coordinator and participants are instigated by the coordinator when the transaction terminates, the BAParticipantManager interaction pattern requires the participant to be able to talk to the coordinator at any time during the lifetime of the business activity.
Whenever a participant is registered with a business activity, it receives a handle on the coordinator. This handle is an instance of interface com.arjuna.wst11.BAParticipantManager with the methods listed in BAParticipantManager Methods.
BAParticipantManager Methods
exitThe participant uses the method
exitto inform the coordinator that is has left the activity. It will not be informed when and how the business activity terminates. This method may only be invoked while the participant is in theactivestate (or thecompletingstate, in the case of a participant registered for theParticipantCompletionprotocol). If it is called when the participant is in any other state, aWrongStateExceptionerror is thrown. Anexitdoes not stop the activity as a whole from subsequently being closed or canceled/compensated, but only ensures that the exited participant is no longer involved in completion, close or compensation of the activity.completedThe participant has completed its work, but wishes to continue in the business activity, so that it will eventually be informed when, and how, the activity terminates. The participant may later be asked to compensate for the work it has done or learn that the activity has been closed.
faultThe participant encountered an error during normal activation and has done whatever it can to compensate the activity. The
faultmethod places the business activity into a mandatorycancel-onlymode. The faulted participant is no longer involved in completion, close or compensation of the activity.
The participant provides the plumbing that drives the transactional aspects of the service. This section discusses the specifics of Participant programming and usage.
Implementing a participant is a relatively straightforward task. However, depending on the complexity of the transactional infrastructure that the participant needs to manage, the task can vary greatly in complexity and scope. Your implementation needs to implement one of the interfaces found under com.arjuna.wst11.
Note
The corresponding participant interfaces used in the 1.0 protocol implementation are located in package
com.arjuna.wst.
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, 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.
Warning
In previous releases, XTS applications were deployed using the appropriate XTS and Transaction Manager
.jar, .war, and configuration files bundled with the
application. This deployment method is no longer supported in the JBoss Application Server.
During JBoss Application Server startup, you should only deploy a transactional web service or transactional client after the
XTS services are available. Declare this dependency in a jboss-beans.xml file located in
the META-INF directory of the web service or client deployment. Example 6.1, “Example jboss-beans.xml” shows one way of declaring this dependency.
After the XTS service starts, it creates an instance of the application class
org.my.ServiceBean by calling its start method. During
JBoss Application Server shutdown, XTS stops the same instance by calling its stop method, prior to
shutting down the XTS Service.
Example 6.1. Example jboss-beans.xml
+<!-- example jboss-beans.xml file declaring dependency on XTS service -->
+<?xml version="1.0" encoding="UTF-8"?>
+<deployment xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="urn:jboss:bean-deployer bean-deployer_1_0.xsd"
+ xmlns="urn:jboss:bean-deployer">
+ <!-- bean class should implement start() and stop() methods -->
+ <bean name="MyService class=org.my.ServiceBean>
+ <depends>jboss:service=XTSService</depends>
+ </bean>
+</deployment>