3.6.4 Subscribe to Receive XA Transaction Notifications

You can register your transaction initiator and participant services to receive notifications. MicroTx Distributed Transactions notifies the registered services when the following events occur: before the prepare phase and when MicroTx Distributed Transactions successfully commits or rolls back a transaction.

The MicroTx Distributed Transactions coordinator notifies the services that you register. You may want to register your service, if based on the business logic your service performs additional tasks when an event occurs. For every resource that you register, you must create a callback resource and declare two methods which MicroTx Distributed Transactions calls to send the notification when an event occurs.

Note:

This feature is available only for Java services.

Perform the following task for the transaction participant and initiator services that you want to register to receive event notifications.

1. Within your application code, add code to create a callback resource that the MicroTx Distributed Transactions coordinator can call when an event occurs.

   Create a JAX-RS class with two methods. It is mandatory for you to declare the beforeCompletion and afterCompletion methods. Within these methods, provide code that is specific to your application's business logic. The MicroTx Distributed Transactions coordinator calls the beforeCompletion method before sending a request to the participants to prepare. The afterCompletion method returns the final status of the event after the transaction is complete. The status of the can be STATUS_COMMITTED or STATUS_ROLLEDBACK.

   In the following sample code, EventListenerResource is the name of the JAX-RS class and transaction-sync is the name of the callback resource. You can provide any name of your choice for the class and callback resource. Note down the name of this resource as you will provide it later.

   Sample code

   @Path("transaction-sync")
   public class EventListenerResource {
        
       /**
       * The MicroTx Distributed Transactions coordinator calls the beforeCompletion method before 
       * the two-phase transaction commit process starts. This call is executed with
       * the transaction  context of the transaction that is being committed.
       **/
       @POST
       @Path("/{gtrid}/beforecompletion")
       @Produces(MediaType.APPLICATION_JSON)
       public Response beforeCompletion(@PathParam("gtrid") String gtrid) {
           ...
           //tasks to be done before the transaction is completed 
           //enter the code based on your application's business logic
           return Response.status(Response.Status.OK).build();
       }
    
       /**
       * The MicroTx Distributed Transactions coordinator calls the afterCompletion method after the 
       * transaction is committed or rolled back.
       **/
       @POST
       @Path("/{gtrid}/aftercompletion/{status}")
       @Produces(MediaType.APPLICATION_JSON)
       public Response afterCompletion(@PathParam("gtrid") String gtrid, @PathParam("status") String status) {
          ...
          //tasks to be done after the transaction is completed 
          //enter the code based on your application's business logic
          return Response.status(Response.Status.OK).build();
       }
   }

2. Register the initiator service to receive event notifications based on your application's business logic.

   The following sample code describes that you call the TrmRegisterSynchronization.register() method after calling begin(), but before calling commit() or rollback(). When you call the TrmRegisterSynchronization.register() method, you must pass the name of the callback resource that you have created in the previous step.

   Sample code

   import oracle.tmm.jta.TrmUserTransaction;
   /**
   * Initiator method which initiates the transaction
   */
   transactionMethod() {
       TrmUserTransaction transaction = new TrmUserTransaction();
       transaction.begin();
       //
       TrmRegisterSynchronization.register(transaction.getTransactionID(), "/transaction-sync");
       ...
       // code that is specific to the application's business logic
       transaction.commit();
   }

   Where,

   • transaction-sync is the name of the callback resource that you have created in the previous step. Replace this value based on your environment.
   • transaction.getTransactionID() is the GTRID of the current transaction. Use the TrmUserTransaction class object to retrieve the GTRID of the current transaction.
3. Register one or more transaction participant services to receive event notifications. Based on your application's business logic, you can decide whether your application requires to receive event notifications.

   The following sample code demonstrates how you can call the TrmRegisterSynchronization.register() method by explicitly passing the GTRID value and the name of the callback resource that you have previously created.

   Sample code

   import oracle.tmm.jta.TrmRegisterSynchronization;
   /**
   * Participant method which is in transaction context.
   * Transaction event registration using GTRID
   */
   participantMethod1(){
       TrmXaContext trmXaContext = ThreadLocalXaContext.get();
       if (trmXaContext != null) {
           String currentTransactionGTRID = new String(trmXaContext.trmXid.getGlobalTransactionId());
           TrmRegisterSynchronization.register(currentTransactionGTRID, "/transaction-sync");
       }
       ...
       // code that is specific to the application's business logic
   }
    

   Where,

   • transaction-sync is the name of the callback resource that you have previously created. Replace this value based on your environment.
   • currentTransactionGTRID is the GTRID of the current transaction. To retrieve the GTRID of the current transaction from ThreadLocal, use TrmXaContext. This applies to transaction initiator as participant services as well.