4.3.3 Develop Spring Boot Applications with Saga

For Spring Boot applications that use the Saga transaction protocol, you must use the Java library file provided by MicroTx Distributed Transactions.

For reference information about the MicroTx Distributed Transactions library for Spring Boot applications, see Oracle® Transaction Manager for Microservices Spring Boot API Reference for Saga.

To include the MicroTx Distributed Transactions library files and property values for Spring Boot applications:

1. Include the MicroTx Distributed Transactions Java library file as a maven dependency in the Spring Boot application's pom.xml file. The following sample code is for the 23.4.1 release. Provide the correct version, based on the release version that you want to use.

   Spring Boot 3.x applications work with Java 17 in Jakarta EE9 environments.

   <dependency>
        <groupId>com.oracle.microtx.lra</groupId>
        <artifactId>microtx-lra-spring-boot-starter</artifactId>
        <version>23.4.1</version>
   </dependency>

2. Specify values for the MicroTx Distributed Transactions library properties in the application.properties file of your application. This enables the custom library to establish communication with the MicroTx Distributed Transactions Saga coordinator, participate in Saga transactions, and propagate the relevant headers for the coordinated transactions. See Configure MicroTx Distributed Transactions Library Properties for Java Apps.
3. Import the com.oracle.microtx.springboot.lra.annotation.* package.

   import com.oracle.microtx.springboot.lra.annotation.*

4. Create an object, of a class in the MicroTx library, to call the endpoints of other Saga transaction participant services. 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 object that you create.
   • RestTemplate
   • OpenFeign

   Autowire the Spring Boot RestTemplate, provided by the MicroTx library.

   @Autowired
   @Qualifier("MicroTxLRA")
   RestTemplate restTemplate;

   Configure an interceptor, provided by the MicroTx library, in one of the following ways. This is required if an outgoing request is a part of a transaction or if you want to intercept an outgoing request.

   • Configure an interceptor in the configuration property of the @FeignClient annotation as shown in the following example.

     @FeignClient(value = "<feign1.name>", url = "<feign1.url>", configuration = MicroTxLRAFeignClientInterceptorConfig.class)
     public interface <interface_name> {
        //...
     }

     Where, you replace <feign1.name> and <feign1.url> with values specific to your environment. Note down the name of the interface that you specify as you will use it later in your application code.

   • Configure interceptors by specifying property values as shown in the following example. Provide these values in the same file that contains values for the MicroTx client library properties.

     spring.cloud.openfeign.client.config.<participant1_service_name>.request-interceptors[0]= com.oracle.microtx.springboot.lra.clientinterceptor.MicroTxLRAFeignClientInterceptorConfig

     Where, you replace <feign1.name> and <feign1.url> with values specific to your environment. Note down the name of the interface as you will use it later in your application code.

5. Optional. Perform the following steps only if you want to execute the methods in the Spring Boot participant applications asynchronously. Instead of waiting for a called participant's method to be executed completely, and then calling another method, you can use the Async annotation to run each method as an isolated thread.
   1. Import the com.oracle.microtx.springboot.lra.annotation.* package.

      import com.oracle.microtx.springboot.lra.annotation.*

   2. Create an executor bean, with a unique name, to override the SimpleAsyncTaskExecutor class available in the Spring framework. While creating the executor bean, you must set the task decorator named MicroTxTaskDecorator, which is part of the MicroTx Distributed Transactions library. The following example shows how you can create a bean named taskExecutorForTripBooking, and then set MicroTxTaskDecorator, the MicroTx Distributed Transactions task decorator.

      Perform this task for each method that you want to run asynchronously.

      Example Code

      @Bean(name = "taskExecutorForTripBooking")
        public Executor asyncExecutor()
          {
              ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
              ... // application-specific code
              executor.setTaskDecorator(new MicroTxTaskDecorator());
              ... // application-specific code
              return executor;
          }

      Note down the name of the bean as you will need to provide this name as an attribute in the @Async annotation.

      If your application code already contains a task decorator, you can add the logic from the MicroTxTaskDecorator class into your existing task decorator, instead of creating a new one.

   3. Annotate the methods that you want to execute in a separate thread with @Async. For value, specify the name of the executor bean that you have created in the previous step as shown in the following example.

      Example Code

      @Async(value = "taskExecutorForTripBooking")
      @Override
      public CompletableFuture bookHotel(String name, String id) 
          {
      	//Code to implement the application's business logic
          }

Source code of a sample Spring REST-based transaction initiator application which uses the MicroTx Distributed Transactions library is available in the trip-manager-springboot folder in the microtx-samples GitHub repository. Source code of a sample Spring REST-based transaction participant application which uses the MicroTx Distributed Transactions library is available in the hotel-springboot folder in the microtx-samples GitHub repository. You can use these files as a reference while integrating the MicroTx libraries with your application.