A client uses the UserTransactionFactory and UserTransaction classes to create and manage WS-AT transactions. These classes provide a simple API which operates in a manner similar to the JTA API. A WS-AT transaction is started and associated with the client thread by calling the begin method of the UserTransaction class. The transaction can be committed by calling the commit method, and rolled back by calling the rollback method.

More complex transaction management, such as suspension and resumption of transactions, is supported by the TransactionManagerFactory and TransactionManager classes.

Full details of the WS-AT APIs are provided in Chapter 7, The XTS API.

A client creates and manages Business Activities using the UserBusinessActivityFactory and UserBusinessActivity classes. A WS-BA activity is started and associated with the client thread by calling the begin method of the UserBusinessActivity class. A client can terminate a business activity by calling the close method, and cancel it by calling the cancel method.

If any of the Web Services invoked by the client register for the BusinessActivityWithCoordinatorCompletion protocol, the client can call the completed method before calling the close method, to notify the services that it has finished making service invocations in the current activity.

More complex business activity management, such as suspension and resumption of business activities, is supported by the BusinessActivityManagerFactory and BusinessActivityManager classes.

Full details of the WS-AT APIs are provided in Chapter 7, The XTS API.

XTS does not require the client application to use a specific API to perform invocations on transactional Web Services. The client is free to use any appropriate API to send SOAP messages to the server and receive SOAP responses. The only requirements imposed on the client are:

In order to achieve this, the client must insert details of the current XTS context into the headers of outgoing SOAP messages, and extract the context details from the headers of incoming messages and associate the context with the current thread. To simplify this process, the XTS module includes handlers which can perform this task automatically. These handlers are designed to work with JAX-WS clients.

A participant is a software entity which is driven by the transaction manager on behalf of a Web service. When a web service wants to participate in a particular transaction, it must enroll a participant to act as a proxy for the service in subsequent negotiations with the coordinator. The participant implements an API appropriate to the type of transaction it is enrolled in, and the participant model selected when it is enrolled. For example, a Durable2PC participant, as part of a WS-Atomic Transaction, implements the Durable2PCParticipant interface. The use of participants allows the transactional control management aspects of the Web service to be factored into the participant implementation, while staying separate from the the rest of the Web service's business logic and private transactional data management.

The creation of participants is not trivial, since they ultimately reflect the state of a Web service’s back-end processing facilities, an aspect normally associated with an enterprise’s own IT infrastructure. Implementations must use one of the following interfaces, depending upon the protocol it will participate within: com.arjuna.wst11.Durable2PCParticipant, com.arjuna.wst11.Volatile2PCParticipant, com.arjuna.wst11.BusinessAgreementWithParticipantCompletionParticipant, or com.arjuna.wst11.BusinessAgreementWithCoordinatorCompletionParticipant.

A full description of XTS’s participant features is provided in Fix me.

A transactional Web service must ensure that a service invocation is included in the appropriate transaction. This usually only affects the operation of the participants and has no impact on the operation of the rest of the Web service. XTS simplifies this task and decouples it from the business logic, in much the same way as for transactional clientsAdd an xref. XTS provides a handler which detects and extracts the context details from the headers in incoming SOAP headers, and associates the web service thread with the transaction. The handler clears this association when dispatching SOAP responses, and writes the context into the outgoing message headers. This is shown in Figure 5.1, “Context Handlers Registered with the SOAP Server”.

The service side handlers for JAX-WS come in two different versions. The normal handler resumes any transaction identified by an incoming context when the service is invoked, and suspends this transaction when the service call completes. The alternative handler is used to interpose a local coordinator. The first time an incoming parent context is seen, the local coordinator service creates a subordinate transaction, which is resumed before the web service is called. The handler ensures that this subordinate transaction is resumed each time the service is invoked with the same parent context. When the subordinate transaction completes, the association between the parent transaction and its subordinate is cleared.

5.3.2.1. JAX-WS Service Context Handlers

To register the JAX-WS server-side context handler with the deployed Web Services, you must install a handler chain on the Server Endpoint Implementation class. The endpoint implementation class annotation, which is the one annotated with a javax.jws.WebService, must be supplemented with a javax.jws.HandlerChain annotation which identifies a handler configuration file deployed with the application. Please refer to the example application configuration file located at dd/jboss/context-handlers.xml and the endpoint implementation classes located in src/com/jboss/jbosstm/xts/demo/services for an example.

When registering a normal JAX-WS service context handler, you must instantiate the com.arjuna.mw.wst11.service.JaxWSHeaderContextProcessor class. If you need coordinator interposition, employ the com.arjuna.mw.wst11.service.JaxWSSubordinateHeaderContextProcessor instead.

[D]

Figure 5.1. Context Handlers Registered with the SOAP Server