Quarkus トランザクションマネージャーを使用した JTA トランザクションの管理


Red Hat build of Quarkus 2.2

ガイド

概要

Narayana JTA エクステンションを使用して、Quarkus アプリケーションでトランザクションを管理します。

はじめに

アプリケーション開発者は、Quarkus トランザクションマネージャーを使用し、アプリケーションに対して JTA トランザクションを調整および公開することができます。

Quarkus は、1 つ以上のリソース全体で JTA トランザクションを調整するためのトランザクションマネージャーを提供します。Quarkus トランザクションマネージャーを使用して、宣言的またはプログラムによる方法でトランザクション境界を制御することができます。トランザクションを変更し、トランザクションのタイムアウトを設定することもできます。この機能は、quarkus-narayana-jta エクステンションによって提供されます。

Red Hat ドキュメントへのフィードバック (英語のみ)

弊社の技術的な内容についてのフィードバックに感謝します。ご意見をお聞かせください。コメントの追加、Insights の提供、誤字の修正、および質問を行う必要がある場合は、ドキュメントで直接行うこともできます。

注記

Red Hat アカウントがあり、カスタマーポータルにログインしている必要があります。

カスタマーポータルからドキュメントのフィードバックを送信するには、以下の手順を実施します。

  1. Multi-page HTML 形式を選択します。
  2. ドキュメントの右上にある Feedback ボタンをクリックします。
  3. フィードバックを提供するテキストのセクションを強調表示します。
  4. ハイライトされたテキストの横にある Add Feedback ダイアログをクリックします。
  5. ページの右側のテキストボックスにフィードバックを入力し、送信 をクリックします。

フィードバックを送信すると、自動的に問題の追跡が作成されます。Submit をクリックすると表示されるリンクを開き、問題の監視を開始するか、さらにコメントを追加します。

貴重なフィードバックにご協力いただきありがとうございます。

多様性を受け入れるオープンソースの強化

Red Hat では、コード、ドキュメント、Web プロパティーにおける配慮に欠ける用語の置き換えに取り組んでいます。まずは、マスター (master)、スレーブ (slave)、ブラックリスト (blacklist)、ホワイトリスト (whitelist) の 4 つの用語の置き換えから始めます。この取り組みは膨大な作業を要するため、今後の複数のリリースで段階的に用語の置き換えを実施して参ります。詳細は、Red Hat CTO である Chris Wright のメッセージ をご覧ください。

第1章 前提条件

  • OpenJDK (JDK) 11 がインストールされ、JAVA_HOME 環境変数が Java SDK の場所を指定するように設定されていること。

    • Red Hat ビルドの Open JDK は、Red Hat カスタマーポータルの Software Downloads ページからダウンロードできます (ログインが必要です)。
  • Apache Maven 3.6.2 以降がインストールされていること。

  • Quarkus Maven プロジェクトがあること。

第2章 Narayana JTA トランザクションマネージャーおよび Quarkus

Narayana JTA トランザクションマネージャーを使用すると、Quarkus アプリケーションに対して JTA トランザクションを調整および公開することができます。quarkus-narayana-jta エクステンションをプロジェクトの pom.xml ファイルへの依存関係として追加し、javax.transaction パッケージに定義されたアノテーション、またはコンテキストおよび依存性注入 (CDI) を使用して JTA トランザクションを管理することができます。

以下の表は、最も一般的な Java トランザクション API (JTA) アノテーションについて説明しています。Java トランザクション API (JTA) アノテーションは以下のとおりです。

Expand
アノテーション説明

@Transactional

メソッドレベルまたはクラスレベルで、CDI Bean でトランザクション境界を制御する機能を提供します。

@TransactionScoped

ライフサイクルが現在アクティブなトランザクションにスコープ指定された Bean インスタンスを定義する標準の CDI スコープを指定する機能を提供します。

注記

@Transactional アノテーションに属性を設定して、トランザクションの開始方法を制御できます。属性が設定された @Transactional アノテーションを個別のメソッドまたは Bean 全体に適用することができます。

第3章 Quarkus Narayana JTA エクステンションのインストール

quarkus-narayana-jta エクステンションを依存関係として Quarkus プロジェクトに追加する必要があります。Hibernate ORM を使用している場合は、quarkus-narayana-jta エクステンションはすでにプロジェクトに存在します。

前提条件

  • Quarkus Maven プロジェクトがあること。

手順

  1. プロジェクトのルートディレクトリーに移動します。

    cd <directory_name>
    Copy to Clipboard Toggle word wrap
  2. 以下の方法のいずれかを使用して、Quarkus プロジェクトに quarkus-narayana-jta エクステンションを追加します。

    1. quarkus-narayana-jta エクステンションを pom.xml ファイルに追加します。

      <dependency>
          <groupId>io.quarkus</groupId>
          <artifactId>quarkus-narayana-jta</artifactId>
      </dependency>
      Copy to Clipboard Toggle word wrap
    2. コマンドラインを使用して quarkus-narayana-jta エクステンションを追加します。

      ./mvnw quarkus:add-extension -Dextensions="narayana-jta"
      Copy to Clipboard Toggle word wrap

第4章 アノテーションを使用した JTA の宣言的トランザクション管理

アノテーションに基づいて JTA トランザクションを自動的に開始およびコミットすることで、コンテナーがトランザクション境界をデマケーションすることができます。以下の章は、JTA トランザクションを管理し、@Transactional アノテーションを使用してトランザクション境界を定義する方法を示しています。

4.1. トランザクション境界の宣言的定義

@Transactional を使用して、メソッドレベルまたはクラスレベルでの CDI Bean でトランザクション境界を制御し、すべてのメソッドがトランザクションによるものであることを確認できます。これは REST エンドポイントにも適用されます。

手順

  • エントリーメソッドで @Transactional アノテーションを使用してトランザクションのスコープを定義します。

    例: src/main/java/org/acme/SantaClauseService.java

    import javax.inject.Inject;
    import javax.enterprise.context.ApplicationScoped;
    import javax.transaction.Transactional;
    
    @ApplicationScoped
    public class SantaClausService {
    
        @Inject ChildDAO childDAO;
        @Inject SantaClausDAO santaDAO;
    
        @Transactional 
    1
    
        public void getAGiftFromSanta(Child child, String giftDescription) {
            // some transaction work
            Gift gift = childDAO.addToGiftList(child, giftDescription);
            if (gift == null) {
                throw new OMGGiftNotRecognizedException(); 
    2
    
            }
            else {
                santaDAO.addToSantaTodoList(gift);
            }
        }
    }
    Copy to Clipboard Toggle word wrap

    1
    @Transactional アノテーションはトランザクション境界を定義し、この呼び出しをトランザクション内でラップします。
    2
    RuntimeException がトランザクション境界を超えると、トランザクションマネージャーはトランザクションをロールバックします。

4.2. ロールバックのトランザクションの宣言的設定

システムレベルの障害によって生じる例外は、トランザクションをロールバックするためにマークを付け、トランザクションを即座に中止します。@Transactional(dontRollbackOn=SomeException.class) または rollbackOn 属性を使用してデフォルトの動作を上書きできます。

前提条件

  • Quarkus Maven プロジェクトがあること。

手順

  • @Transactional(dontRollbackOn=SomeException.class) を使用して、トランザクションをロールバックしない例外を指定します。

    例: src/main/java/org/acme/SantaClauseService.java

    import javax.inject.Inject;
    import javax.enterprise.context.ApplicationScoped;
    import javax.transaction.Transactional;
    
    @ApplicationScoped
    public class SantaClausService {
    
        @Inject ChildDAO childDAO;
        @Inject SantaClausDAO santaDAO;
    
        @Transactional(dontRollbackOn=NonCriticalRuntimeException.class)
        public void getAGiftFromSanta(Child child, String giftDescription) throws Exception {
            Gift gift = childDAO.addToGiftList(child);
    
            // might throw a NonCriticalRuntimeException
            gift.setDescription(giftDescription);
    
            santaDAO.addToSantaTodoList(gift);
        }
    }
    Copy to Clipboard Toggle word wrap

    この例では、トランザクションコンテキストは @Transactional メソッドでネストされたすべての呼び出しに伝播されます (childDAO.addToGiftList() および santaDAO.addToSantaTodoList())。ランタイム例外がメソッド境界を超過しない限り、トランザクションはコミットします。

4.3. トランザクションタイムアウトの宣言的設定

@TransactionConfiguration アノテーションに加えて @Transactional アノテーションを使用して、タイムアウトを秒単位で指定します。@TransactionConfiguration アノテーションは、トランザクションを記述するトップレベルのメソッドにのみ配置できます。

手順

  • @TransactionConfigurationtimeout プロパティーを使用して、タイムアウトを秒単位で設定します。

    import javax.transaction.Transactional;
    
    @Transactional
    @TransactionConfiguration(timeout=40)
    public void getAGiftFromSanta(Child child, String giftDescription) {...}
    Copy to Clipboard Toggle word wrap
注記

メソッドで定義された設定は、クラスで定義された設定よりも優先されます。クラスで @TransactionConfiguration を定義する場合、@Transactional のマークの付いたクラスのすべてのメソッドで定義することと同じになります。

4.4. リアクティブ値を返すメソッド

@Transactional のアノテーションが付いたメソッドがリアクティブ値を返すと、返されたリアクティブ値が終了するまでトランザクションは終了しません。リアクティブ値が例外によって終了すると、ロールバックするようにトランザクションにマークが付けられます。そうでない場合は、トランザクションはコミットされます。

第5章 API アプローチを使用したプログラムによる JTA トランザクションの管理

UserTransaction を注入して、トランザクション境界をプログラムで管理できます。以下の章では、API のアプローチを使用して JTA トランザクションを管理し、トランザクション境界を定義する方法を説明しています。

5.1. API アプローチを使用したトランザクション境界の定義

その begin()commit()、および rollback() メソッドを呼び出すことにより、UserTransaction を注入し、トランザクション境界を管理できます。

手順

  1. UserTransaction インターフェイスを注入します。

    src/main/java/org/acme/SantaClauseService.java

    @ApplicationScoped
    public class SantaClausService {
    
        @Inject ChildDAO childDAO;
        @Inject SantaClausDAO santaDAO;
        @Inject UserTransaction transaction;
    }
    Copy to Clipboard Toggle word wrap

  2. トランザクションのデマケーションメソッドを使用してトランザクションを制御します。

    src/main/java/org/acme/SantaClauseService.java

    import javax.transaction.Transactional;
    import javax.inject.Inject;
    import javax.transaction.SystemException;
    import javax.transaction.UserTransaction;
    
    @ApplicationScoped
    public class SantaClausService {
    
        @Inject ChildDAO childDAO;
        @Inject SantaClausDAO santaDAO;
        @Inject UserTransaction transaction;
    
        public void getAGiftFromSanta(Child child, String giftDescription) {
            // some transaction work
            try {
                transaction.begin(); 
    1
    
                Gift gift = childDAO.addToGiftList(child, giftDescription);
                santaDAO.addToSantaTodoList(gift);
                transaction.commit();
            }
            catch(SomeException e) {
                // do something on Tx failure
                transaction.rollback(); 
    2
    
            }
        }
    }
    Copy to Clipboard Toggle word wrap

    1
    transaction.begin()transaction.commit() の間にトランザクションコードを配置します。
    2
    トランザクションを即座に中止します。
    注記

    @Transactional 呼び出しによってトランザクションが開始するメソッドで UserTransaction を使用することはできません。

5.2. API アプローチを使用したロールバックのトランザクションの設定

システムレベルの障害によって生じる例外は、ロールバック用にトランザクションにマークを付けます。TransactionManager を注入して、ロールバックのトランザクションにプログラムを使用してマークを付けることができます。

手順

  1. TransactionManager を注入し、setRollbackOnly でロールバックするトランザクションを設定します。

    この例では、トランザクションコンテキストは @Transactional メソッドでネストされたすべての呼び出しに伝播されます (childDAO.addToGiftList() および santaDAO.addToSantaTodoList())。ランタイム例外がメソッド境界を超過しない限り、トランザクションマネージャーはトランザクションをコミットします。

    例: src/main/java/org/acme/SantaClausService.java

    import javax.transaction.Transactional;
    import javax.inject.Inject;
    import javax.transaction.SystemException;
    import javax.transaction.UserTransaction;
    
    @ApplicationScoped
    public class SantaClausService {
    
        @Inject TransactionManager tm; 
    1
    
        @Inject ChildDAO childDAO;
        @Inject SantaClausDAO santaDAO;
    
        @Transactional
        public void getAGiftFromSanta(Child child, String giftDescription) {
            // some transaction work
            Gift gift = childDAO.addToGiftList(child, giftDescription);
            if (gift == null) {
                tm.setRollbackOnly(); 
    2
    
            }
            else {
                santaDAO.addToSantaTodoList(gift);
            }
        }
    }
    Copy to Clipboard Toggle word wrap

    1
    TransactionManager を注入して、setRollbackOnly セマンティクスをアクティブにすることができます。
    2
    トランザクションをロールバックするタイミングをプログラムを使用して決定します。

第6章 デフォルトのトランザクションタイムアウトの上書き

application.properties ファイルで quarkus.transaction-manager.default-transaction-timeout プロパティーの値を設定することで、トランザクションのタイムアウトを上書きできます。トランザクションマネージャーによって管理されるすべてのトランザクションのデフォルトのタイムアウトは 60 秒です。トランザクションがタイムアウト内で解決されない場合、トランザクションマネージャーは自動的にこれをロールバックします。

手順

  • application.properties ファイルで quarkus.transaction-manager.default-transaction-timeout プロパティーに <duration> を設定します。

    quarkus.transaction-manager.default-transaction-timeout=<duration>
    Copy to Clipboard Toggle word wrap

    <duration> 時間を秒単位で設定するか、または標準の java.time.Duration format 形式を使用できます。たとえば、タイムアウトを 2 分に設定するには、quarkus.transaction-manager.default-transaction-timeout=PT2M を入力します。

第7章 XA トランザクションのトランザクションノード名識別子の設定

複数のリソースを持つ XA トランザクションの一意のノード識別子を設定できます。トランザクションを作成すると、ノード名識別子はトランザクション ID の一部になります。識別子により、トランザクションマネージャーは、データベースに作成または JMS ブローカーによって作成される XA トランザクションを認識することができます。トランザクションマネージャーは、リカバリー時にこのトランザクションをロールバックすることができます。

手順

  • application.properties ファイルで quarkus.transaction-manager.node-name プロパティーに 値を設定します。

    quarkus.transaction-manager.node-name=<unique_id>
    Copy to Clipboard Toggle word wrap
    注記

    トランザクションマネージャーのデプロイメントごとに、必ず一意のノード名識別子を設定してください。ノード識別子は、トランザクションマネージャーの再起動時に安定する必要があります。

第8章 Quarkus トランザクション設定プロパティーの概要

以下の表は、トランザクション管理を設定するために使用できる設定プロパティーをまとめたものです。

Expand
表8.1 Quarkus トランザクション設定プロパティーおよびそのデフォルト値の表
プロパティー説明デフォルト

quarkus.datasource.jdbc.transactions

通常の JDBC トランザクション、XA を使用できます。または、すべてのトランザクション機能を無効にします (enabledxadisabled)。

enabled

quarkus.datasource.jdbc.transaction-isolation-level

トランザクション分離レベル (undefinednoneread-uncommittedread-committedrepeatable-readserializable)

 

quarkus.transaction-manager.default-transaction-timeout

トランザクションマネージャーによって管理されるすべてのトランザクションのタイムアウト

60 秒

quarkus.transaction-manager.node-name

ノード名の識別子

 

改訂日時:2023-01-28 19:58:58 +1000

トップに戻る
Red Hat logoGithubredditYoutubeTwitter

詳細情報

試用、購入および販売

コミュニティー

Red Hat ドキュメントについて

Red Hat をお使いのお客様が、信頼できるコンテンツが含まれている製品やサービスを活用することで、イノベーションを行い、目標を達成できるようにします。 最新の更新を見る.

多様性を受け入れるオープンソースの強化

Red Hat では、コード、ドキュメント、Web プロパティーにおける配慮に欠ける用語の置き換えに取り組んでいます。このような変更は、段階的に実施される予定です。詳細情報: Red Hat ブログ.

会社概要

Red Hat は、企業がコアとなるデータセンターからネットワークエッジに至るまで、各種プラットフォームや環境全体で作業を簡素化できるように、強化されたソリューションを提供しています。

Theme

© 2026 Red Hat