6.9.2 Configure JAX-RS App as Transaction Initiator

A transaction initiator service initiates or starts a transaction. Based on your application's business logic, a transaction initiator service may only start the transaction or start the transaction and participate in the transaction as well.

Before you begin, identify if your application only initiates the transaction or initiates and participates in the transaction. Configure your application accordingly as the requirements vary slightly for the two scenarios.

Let us consider two scenarios to understand if your application only initiates the transaction or participates in the transaction as well.

• Scenario 1: A banking teller application transfers an amount from one department to another. Here, the teller application only initiates the transaction and does not participate in it. Based on the business logic, the teller application calls different services to complete the transaction. A database instance may or may not be attached to the teller application.
• Scenario 2: A banking teller application transfers an amount from one department to another. For every transaction, the teller application charges 1% as commission. Here, the teller application initiates the transaction and participates in it. A database instance must be attached to the teller application to save the transaction information.

To configure your Java application as a transaction initiator:

1. Specify property values for the MicroTx library. See Configure Library Properties.
2. Include the MicroTx Java library file as a maven dependency in the application's pom.xml file. The following sample code is for the 24.2 release. Provide the correct version, based on the release version that you want to use.

   • In Jakarta EE8 environments, such as Helidon 2.x, use the TmmLib file.

     <dependency>
          <groupId>com.oracle.tmm.jta</groupId>
          <artifactId>TmmLib</artifactId>
          <version>24.2</version>
     </dependency>

   • In Jakarta EE9 environments, such as Helidon 3.x applications, use the TmmLib-jakarta file.

     <dependency>
          <groupId>com.oracle.tmm.jta</groupId>
          <artifactId>TmmLib-jakarta</artifactId>
          <version>24.2</version>
     </dependency>

3. Import the oracle.tmm.jta.TrmUserTransaction package.

   import oracle.tmm.jta.TrmUserTransaction;

4. Initialize an object of the TrmUserTransaction class for all new transactions to demarcate transaction boundaries in the application code, such as to begin, commit, or roll back transactions. Initialize the object before your application logic initiates or begins a transaction.
   The following code sample demonstrates how to create an instance of the TrmUserTransaction class called ut.

   UserTransaction ut = new oracle.tmm.jta.TrmUserTransaction();

5. The following code samples demonstrate how to begin a new XA transaction called.

   • If your application only initiates the transaction and does not participate in the transaction, add the following line to your application code to begin the XA transaction.

     
     ut.begin();
     ... // Implement the business logic to begin a transaction.

   • If your application initiates the transaction and participates in it, add the following line to your application code to begin the XA transaction.

     
     ut.begin(true);
     ... // Implement the business logic to begin a transaction.
     

6. Create a REST client.

   The following command creates a new client called svcClient.

   Client svcClient = ClientBuilder.newClient();

   Use this REST client to call the endpoints of the transaction participant services to perform the transaction. The transaction initiator service begins the transaction. To complete the transaction, the initiator service may have to make calls to one or more participant services. While calling the participant services, use the REST client that you have created.

7. Based on your business logic, commit or rollback the transaction.

   • To commit a transaction:

     ut.commit();

   • To rollback a transaction:

     ut.rollback();

Source code of an XA transaction initiator application is available in the xa/java/teller folder in the microtx-samples GitHub repository. This provides an example of how you can use MicroTx Java libraries with the business logic of your Java initiator application. This sample application is called Teller. It initiates a transaction between two departments. It calls Dept A to withdraw an amount and it calls Dept B to deposit the amount. Use this as a reference while integrating the MicroTx libraries with your application.

If the initiator service also participates in the transaction in addition to initiating the transaction, you must make additional configurations for the application to participate in the transaction and communicate with the resource manager. See Configure JAX-RS App as Transaction Participant.