7.12.2 トランザクション・イベント・キューを利用するためのJAX-RS参加側アプリケーションの構成

この項で説明する情報を使用して、Oracle MicroTxライブラリをJAX-RS参加側アプリケーションと統合し、Oracle Transactional Event Queues (TEQ)機能を利用します。

XAトランザクションを開始および参加するJAX-RSアプリケーションに対して、次のステップを実行することもできます。

1. 任意のテキスト・エディタでapplication.yamlファイルを開き、MicroTxクライアント・ライブラリおよびデータベースの詳細のプロパティ値を指定します。
   • 既存のデータ・ソース構成の詳細に加えて、セッションの一意のTEQトピック名を入力します。

     jms:
        topicName: "MicroTxXATopicSession"

     この名前は、後でTopicSessionオブジェクトを注入するときに使用するので覚えておいてください。複数のリソース・マネージャを使用している場合は、各リソース・マネージャのapplication.yamlファイルにこれらの詳細を入力します。

   • TEQが使用可能なOracle Databaseに接続するための詳細を指定します。次の例は、departmentDataSourceデータベースのサンプル・データベースURL、パスワード、ユーザー名およびRMID値を示しています。プロパティの詳細は、「データ・ストアのプロパティ」を参照してください。

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

     複数のリソース・マネージャを使用する場合のみ、リソース・マネージャごとに一意のリソース・マネージャID (RMID)を指定します。また、MicroTxライブラリ・プロパティでこれらのRMIDのいずれかを指定します。単一のリソース・マネージャを使用する場合は、application.yamlファイルにRMIDを指定する必要はありません。

   • 次の例は、MicroTxクライアント・ライブラリのプロパティのサンプル値を指定しています。ご自身の環境に基づいて値を指定してください。

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

     oracle.tmm.xa.XaSupportがtrueに設定されていることを確認します。

     各プロパティおよびその他のオプション・プロパティの詳細は、「JAX-RSおよびNode.jsアプリケーションのライブラリ・プロパティの構成」を参照してください。

2. oracle.tmm.jta.common.MicroTxXATopicSessionパッケージをインポートします。

   import oracle.tmm.jta.common.MicroTxXATopicSession;

3. MicroTx Javaライブラリ・ファイルをアプリケーションのpom.xmlファイルにmaven依存関係として含めます。次のサンプル・コードは24.4リリース用です。使用するリリース・バージョンに基づいて、正しいバージョンを指定してください。

   <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.4</version>
   </dependency>

4. XADatasourceオブジェクトを初期化します。

   MicroTxクライアント・ライブラリは、XADatasourceオブジェクトにアクセスする必要があります。このオブジェクトを使用してXAConnectionオブジェクトおよびXAResourceオブジェクトを作成し、リソース・マネージャまたはデータベース・サーバーに接続します。次のコードでは、接続オブジェクトを作成する際にアプリケーション・コードの先頭にXADatasourceオブジェクトをどのように定義するかを示しています。

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

   XADataSourceの詳細は、https://docs.oracle.com/javase/8/docs/api/javax/sql/XADataSource.htmlを参照してください。

5. トランザクション参加側関数またはブロックで、MicroTxクライアント・ライブラリで使用されるXADatasourceオブジェクトを指定します。リソース・マネージャに接続するための資格証明およびその他の詳細を指定します。

   //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);

   アプリケーション開発者は、XADataSourceを割り当てる際に、XA準拠JDBCドライバおよび必要なパラメータを設定する必要があります。

   MicroTxクライアント・ライブラリは、XADatasourceオブジェクトを使用してデータベース接続を作成します。

6. トランザクション参加側の関数すなわちブロックで、XADatasourceオブジェクトを初期化した後に次のコード行を1回だけ追加します。

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

   XADatasourceはJTAで定義されたインタフェースであり、JDBCドライバによって実装が提供されます。

   MicroTxクライアント・ライブラリは、このオブジェクトを使用してデータベースに接続し、XAトランザクションを開始し、準備、コミット、ロールバックなどの様々な操作を実行します。MicroTxライブラリは、依存関係インジェクションを使用してDMLを実行するためのSQL接続オブジェクトもアプリケーション・コードに提供します。

7. 参加側サービスのコードに次の行を挿入して、アプリケーションがMicroTxクライアント・ライブラリによって渡された接続を使用するようにします。

   @Inject     
   @MicroTxXATopicSession     
   private XATopicSession xaTopicSession;

   ここで、MicroTxXATopicSessionは、application.yamlファイルのjms.topicNameに指定した名前です。

8. MicroTxXATopicSessionを注入すると、MicroTxクライアント・ライブラリによってセッション・オブジェクトが自動的に作成され、データベース接続オブジェクトが注入されます。そのため、connectionオブジェクトを注入する必要はありません。

   次のコード・スニペットは、MicroTxXATopicSessionオブジェクトの使用中にデータベース接続オブジェクトの詳細を取得する方法を示しています。

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

9. MicroTxXATopicSessionオブジェクト(MicroTxクライアント・ライブラリによって注入)を使用して、メッセージをTEQおよびOracle DatabaseでのDML操作に公開します。参加側サービスのコードに次の行を挿入して、参加側サービスがDML操作を実行するたびに、注入されたconnectionオブジェクトを使用するようにします。

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

   ここで、connectionは、前のステップで注入したConnectionオブジェクトの名前です。

   これらのコード行は、参加側サービスが実行するDML操作ごとに挿入します。DML操作ごとにstmt1やstmt2などの新しい文オブジェクトを作成しますが、MicroTxクライアント・ライブラリによって作成された同一のconnectionオブジェクトを使用します。

10. 変更内容を保存します。

MicroTx XAライブラリ関数を使用してTEQを活用するサンプルJAX-RSトランザクション参加側アプリケーションのソース・コードは、microtx-samples GitHubリポジトリのxa/java/jms/department-helidon-teqフォルダにあります。これは、MicroTxライブラリとアプリケーションの統合時に参照として使用できます。