6 JOTM-BTP architecture

Now that we've seen an example of JOTM-BTP, let see what is JOTM-BTP.

6.1 Design goals

At the beginning of JOTM-BTP, the goals were:

• to Apache Axis as the target deployment platform, and JOTM as the transaction manager
• to provide a simple way (as transparent as possible to the end user, i.e. as simple as JTA and XA) to implement and deploy BTP-enabled web services, on both the client and the server side.
• to be as little intrusive as possible wrt JOTM: current implementation of JOTM-BTP did not require any modification of JOTM. (JOTM is embedded in some of our web services - those with a coordinator role - as the transaction manager we rely on, and that's it!).

6.1.1 Client-side Design

On the client side, JOTM-BTP provides a simple API to exchange BTP and Application messages with web services. For example, it provides methods to perform begin(), confirm_transaction(), etc. without having to build, marshal, send, receive and unmarshal XML messages nor to have a fine understanding of BTP messages).

6.1.2 Server-side Design

On the server side, the programmer just has to extend some of our utilitary classes (for example, Participant to implement a BTP-enabled participant, which is the equivalent to a Resource in JOTM or a XAResource in JTA), and to deploy it as a Web Service on Apache Axis.
The programmer has to implement callbacks, that inform him of transaction-related events (like transaction boundaries) - so he doesn't have to cope with BTP, just with his application logic.

6.1.3 BTP implementation design

Java classes are provided for each BTP Message (eg. CONTEXT, CONTEXT-REPLY, ENROL, ENROLLED,...), as well as Related Groups (message compounds, like CONTEXT + APPLICATION).

The main Roles defined in the BTP specification (like Participant, Decider or SubCoordinator) are implemented as java classes, to be deployed as Web Services on Axis. Some embeds a JOTM transaction manager (like Decider or Subcoordinator, that can create and manage transactions), some don't (like Participant, that has some BTP capabilities to be enrolled in a transaction as a resource, but can't create and manage its own transactions).

The transaction-related messages between a coordinator and a participant are undertaken by a ``BTP Resource'' object, enrolled in JOTM as a Resource, and exchanging XML messages with the participant it represents under the control of the transaction manager (eg. a prepare() call on the resource results in a PREPARE BTP message to be sent to the participant, etc.).

6.2 Example: Message flow of CONTEXT + APLLICATION MESSAGE

• The Terminator sends a transaction context + application messages to some Participants, which are BTP-enabled web services. The CONTEXT informs the participants that they have to enrol themselves in a transaction (the CONTEXT was obtained from a previous BEGIN issued by the terminator).
• The participants extract transaction information from the Context (mainly "superior-address" and "Transaction-Id"), then determine the address of the Coordinator they have to ENROL in, and send an ENROL message.
• The Coordinator has an embedded JOTM transaction manager: upon receipt of the ENROL message, it creates a local Resource and registers it on JOTM.
• The Resource handles all the XML communication (BTP messages) with the Participant, in reaction to the JOTM transaction manager's decisions.

Figure 1: on the left, the terminator; on the right, the coordinator; at the bottom, the participants

6.3 Examples

Note: the sample code below does not exactly reflect our current (prototype) APIs, but what we have is very near from what we propose here. Of course, it is subject of changes, and comments are welcome.

6.3.1 Participant code example

public class DemoParticipant
   extends org.objectweb.jotm.btp.roles.Participant {

   public void enrolled(String transactionid) {
     System.out.println("Just enrolled in "
                        + transactionid);
   }

   public int prepare(String transactionid) {
     System.out.println("Requested to prepare transaction "
                        + transactionid);
     return Participant.VOTE_PREPARED;
   }

   public boolean confirm(String transactionid) throws Exception {
     System.out.println("Requested to confirm transaction "
                        + transactionid);
     return true;
   }

   public boolean cancel(String transactionid) throws Exception {
     System.out.println("Requested to cancel transaction "
                        + transactionid);
     return true;
   }

   public void contradiction(String transactionid) {
   }

   public String applicationMessage(String transactionid,
             org.objectweb.xml.util.XElement message) {
     System.out.println("Got an application message: "
                        + message.toString());
     return "<greetings>Hello World !</greetings>";
   }
}

6.3.2 Deployment descriptor for Axis

<deployment
   xmlns="http://xml.apache.org/axis/wsdd/"
   xmlns:java="http://xml.apache.org/axis/wsdd/providers/java">

   <!-- Demo Participant -->
   <service name="BtpDemoService" provider="java:RPC">
     <parameter name="scope" value="Application"/>
     <parameter name="className" value="DemoParticipant"/>
     <parameter name="allowedMethods" value="messages"/>
   </service>

   <!-- Decider (the transaction manager) -->
   <service name="Decider" provider="java:RPC">
     <parameter name="scope" value="Application"/>
     <parameter name="className"
                value="org.objectweb.jotm.btp.roles.Decider"/>
     <parameter name="allowedMethods" value="messages"/>
   </service>
</deployment>

6.3.3 Client code example

import  org.objectweb.jotm.btp.client.BtpClient;
import org.objectweb.jotm.btp.messages.*;

 ....

 String deciderAddr =
    "http://localhost:8080/axis/services/TravelAgency";
 String participantAddr =
    "http://localhost:8080/axis/services/HotelReservation";

 // Begin the transaction
 BtpClient client = new BtpClient();
 BtpMessage context = client.begin(deciderAddr);

 if(context != null && context.getType() == BtpMessage.CONTEXT) {

   // Build application message
   ApplicationMessage app =
      new ApplicationMessage("<greetings>Hi there !</greetings>");

   // Send it along with the context to the participant
   BtpMessage replyContext =
      client.sendCtxApp(participantAddr, (Context)context, app);

 }

 // Confirm the transaction
 BtpMessage outcome =
    client.confirmTransaction(deciderAddr, (Context)context);

 ...

6.4 XML marshalling and unmarshalling

• Each Java class that represents a BTP message has a toXml() method that generates its XML form
• The unmarshalling of messages relies on a MessageParser static class: currently based on XmlPull, it relies on a 3rd-party XML parser (XPP) to parse XML, and builds up BTP message classes depending on which BTP message it recognizes in the XML flow.

6.5 Cohesive coordinators (composers)

JOTM does not support cohesive transactions (a "cohesive" transaction can be confirmed if a subset of the involved resources - the "confirm set" - answers positively to the PREPARE request).
Cohesion is then currently supported by JOTM-BTP using a hack: the "BTP Resource" (i.e., the JOTM Resource that is registered in the TM) always confirms the PREPARE request for all resources that do not belong to the confirm set.