6.12.2 Configure JAX-RS Participant App to Leverage Transactional Event Queues

Use the information provided in this section to integrate Oracle MicroTx library with your JAX-RS participant application to leverage the Oracle Transactional Event Queues (TEQ) feature.

You can also perform the following steps for a JAX-RS application that initiates and participates in an XA transaction.

1. Open the application.yaml file in any text editor and provide property values for the MicroTx client library and the database details.
   • In addition to the existing data source configuration details, enter a unique TEQ topic name for the session.

     jms:
        topicName: "MicroTxXATopicSession"

     Remember this name as you will use it later to inject a TopicSession object. If you are using multiple resource managers, enter these details in the application.yaml file for each resource manager.

   • Provide details to connect to the Oracle Database where TEQ is available. The following example provides sample database URL, password, user name, and RMID values for the departmentDataSource database. For description of the properties, see Data Store Properties.

     departmentDataSource:
         url: "jdbc:oracle:thin:@tcps://<host>:<port>/<service_name>?wallet_location=Database_Wallet"
         user: "dbuser"
         password: "xxxxxx"
         rmid: "174A5FF2-D8B1-47B0-AF09-DA5AFECA2F61"

     Only if you use multiple resource managers, specify a unique resource manager ID (RMID) for each resource manager. Also specify one of these RMIDs in the MicroTx library properties. If you use a single resource manager, you don't need to mention the RMID in the application.yaml file.

   • The following example provides sample values for the MicroTx client library properties. Provide the values based on your environment.

     oracle.tmm.TcsConnPoolSize = 15
     oracle.tmm.CallbackUrl = https://bookTicket-app:8081
     oracle.tmm.PropagateTraceHeaders = true
     oracle.tmm.TransactionTimeout = 60000
     oracle.tmm.xa.XaSupport = true

     Ensure that oracle.tmm.xa.XaSupport is set to true.

     For details about each property and other optional properties, see Configure Library Properties.

2. Import the oracle.tmm.jta.common.MicroTxXATopicSession package.

   import oracle.tmm.jta.common.MicroTxXATopicSession;

3. 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.

   <dependency>
        <groupId>jakarta.jms</groupId>
        <artifactId>jakarta.jms-api</artifactId>
        <version>3.1.0</version>
   </dependency>
   
   <dependency>
        <groupId>com.oracle.database.messaging</groupId>
        <artifactId>aqapi-jakarta</artifactId>
        <version>24.2</version>
   </dependency>

4. Initialize an XADatasource object.

   The MicroTx client library needs to access an XADatasource object. It uses this object to create XAConnection and XAResource objects to connect with a resource manager or database server. The following code describes how you can define the XADatasource object at the beginning of the application code when you create the connection object.

   class oracle.tmm.jta.TrmConfig
   static void initXaDataSource(XADataSource xaDs)

   For more information about XADataSource, see https://docs.oracle.com/javase/8/docs/api/javax/sql/XADataSource.html.

5. In the transaction participant function or block, specify the XADatasource object which is used by the MicroTx client library. Provide the credentials and other details to connect to the resource manager.

   //Example for a participant using an Oracle Database:
   OracleXADataSource dataSource = new oracle.jdbc.xa.client.OracleXADataSource();
   dataSource.setURL(url); //database connection string
   dataSource.setUser(user); //username to access database
   dataSource.setPassword(password); //password to access database
   TrmConfig.initXaDataSource((XADataSource)dataSource);

   It is the responsibility of the application developer to ensure that an XA-compliant JDBC driver and required parameters are set up while allocating XADataSource.

   The MicroTx client library uses the XADatasource object to create database connections.

6. In the transaction participant function or block, add the following line of code only once after you have initialized the XADatasource object.

   oracle.tmm.jta.TrmConfig.initXaDataSource((XADataSource)xaDs);

   XADatasource is an interface defined in JTA whose implementation is provided by the JDBC driver.

   The MicroTx client library uses this object to connect to database to start XA transactions and perform various operations such as prepare, commit, and rollback. The MicroTx library also provides a SQL connection object to the application code to execute DML using dependency injection.

7. Insert the following line in the code of the participant service so that the application uses the connection passed by the MicroTx client library.

   @Inject     
   @MicroTxXATopicSession     
   private XATopicSession xaTopicSession;

   Where, MicroTxXATopicSession is the name of that you have provided in jms.topicName in the application.yaml file.

8. When you inject MicroTxXATopicSession, MicroTx client library automatically creates a session object and injects a database connection object. So, you do not have to inject a connection object.

   The following code snippet demonstrates how you can retrieve the details of a database connection object while using the MicroTxXATopicSession object.

   connection = ((AQjmsSession) xaTopicSession).getDBConnection();

9. Use the MicroTxXATopicSession object, injected by the MicroTx client library, to publish messages to TEQ and for any DML operation on Oracle Database. Insert the following lines in the code of the participant service so that the service uses the injected connection object whenever the participant service performs a DML operation.

   Statement stmt1 = connection.createStatement();
   stmt1.execute(query);
   stmt1.close();

   Where, connection is the name of the Connection object that you have injected in the previous step.

   Insert these lines of code for every DML operation that your participant service performs. Create a new statement object, such as stmt1 or stmt2 for every DML operation, but use the same connection object that is created by the MicroTx client library.

10. Save the changes.

Source code of a sample JAX-RS transaction participant application which uses the MicroTx XA library functions to leverage TEQ is available in the xa/java/jms/department-helidon-teq folder in the microtx-samples GitHub repository. You can use this as a reference while integrating the MicroTx libraries with your application.