1. Transaction Manager for Microservices開発者ガイド
  2. XAでのアプリケーションの開発
  3. XAでのORDSアプリケーションの開発
  4. トランザクション参加側としてのORDSアプリケーションの構成

7.14.6 トランザクション参加側としてのORDSアプリケーションの構成

  1. MicroTxライブラリのプロパティ値を指定します。「ORDSアプリケーションのPL/SQLライブラリ・プロパティの構成」を参照してください。
  2. アプリケーションで必要な表やその他のデータベース・オブジェクトのためにDDLを作成します。
  3. デフォルト・データを挿入するために必要なDMLを追加します。
  4. アプリケーションの新しいRESTモジュールを作成または定義します。
  5. アプリケーションで必要なPL/SQL関数およびストアド・プロシージャを作成します。
  6. REST APIごとに、テンプレートおよびハンドラを定義します。
    1. RESTサービス・モジュールの名前およびベース・パスを入力します。次のコード例は、値としてaccountsを示しています。この値は、ご使用の環境に固有の情報で置き換えてください。
      DECLARE
    //Provide a name for the REST service module
    restModuleName VARCHAR2(256):= 'accounts'; 
    //Provide a base path for the REST service
    restModuleBasePath VARCHAR2(256):= 'accounts';
    2. l_callBackUrlの値を設定します。たとえば、http://localhost:50080/ords/ordstest/accountsです。TmmReturnのパラメータも初期化します。
      DECLARE
//Set up the callBackUrl correctly. This is generally the base URL or path of the module.
l_callBackUrl  VARCHAR2(256) := OWA_UTIL.get_cgi_env(''X-APEX-BASE'') || ''accounts'';
l_tmmReturn TmmReturn;
l_tmmReturn2 TmmReturn;
    3. TmmStartをコールします。

      次のコード・サンプルは、TmmStart関数をコールする方法を示しています。次の例に示すように、すべてのパラメータを渡します。TmmStartをコールするときに、l_callBackUrlの値を渡す必要があります。他のすべてのパラメータの値は、受信リクエスト・ヘッダーから自動的に取得されて渡されます。 

      //Call TmmStart. Specify value for callBackUrl.
l_tmmReturn := TmmStart(callBackUrl => l_callBackUrl, linkUrl => :linkUrl, requestId => :requestId, authorizationToken => :authorization, tmmTxToken => :tmmTxToken);

      TmmStart関数からオブジェクトが返され、属性proceedが提供されます。これは、TmmStart関数が正常に実行されたかどうか、トランザクションを先に進められるかどうかを示します。

    4. XAトランザクションを進めるか(l_tmmReturn.proceedの値が0より大きい)、進めないか(l_tmmReturn.proceedの値が0)を確認します。XAトランザクションをさらに進められる場合のみ、ビジネス・ロジックを実行します。それ以外の場合は、次のコード例に示すように、TmmStart関数がHTTPエラー・ステータス・コードを返す必要があります。ビジネス・ロジックの実行が完了したら、TmmEnd関数をコールします。
      IF (l_tmmReturn.proceed > 0) THEN                  
//Execute your business logic only if the XA transaction can proceed further.
//Execute SQLs statements or call other functions or stored procedures.
	doWithdraw(p_amount  => :amount, p_account_id  => :accountId);
 
	//Call TmmEnd at the end of the REST function.
	l_tmmReturn2 := TmmEnd(p_xid => l_tmmReturn.xid);      
        :status_code := 200;
ELSE
        :status_code := 400; --bad request
END IF;
    5. MicroTxコールバックAPIを作成します。
      createTMMCallbacks(moduleName => restModuleName);
    6. XAトランザクションに参加するすべてのメソッド・ハンドラを登録します。
      registerXaHandler(moduleName => restModuleName,
                      handlerPattern => ':accountId/withdraw',
                      handlerMethod => 'POST');

    次のコード・サンプルは、ハンドラを実装する方法を示しています。

    DECLARE
    //Provide a name for the REST service module
    restModuleName VARCHAR2(256):= 'accounts'; 
    //Provide a base path for the REST service
    restModuleBasePath VARCHAR2(256):= 'accounts';

BEGIN
    ORDS.define_module(
            p_module_name    => restModuleName,
            p_base_path      => restModuleBasePath,
            p_items_per_page => 0);
 
    ORDS.define_template(
            p_module_name    => restModuleName,
            p_pattern        => ':accountId/withdraw');
 
    ORDS.define_handler(
            p_module_name    => restModuleName,
            p_pattern        => ':accountId/withdraw',
            p_method         => 'POST',
            p_source_type    => ORDS.source_type_plsql,
            p_source         => '
                        DECLARE
                        //Set up the callBackUrl correctly. This is generally the base URL or path of the module.
                        //Example: http://localhost:50080/ords/ordstest/accounts
                        l_callBackUrl  VARCHAR2(256) := OWA_UTIL.get_cgi_env(''X-APEX-BASE'') || ''accounts''; 
                        l_tmmReturn TmmReturn;
                        l_tmmReturn2 TmmReturn;
 
                        BEGIN
                            //Call TmmStart. Pass all the other parameters than the callBackUrl.
                            l_tmmReturn := TmmStart(callBackUrl => l_callBackUrl, linkUrl => :linkUrl, requestId => :requestId, authorizationToken => :authorization, tmmTxToken => :tmmTxToken);
 
                            //Check if the transaction should proceed further
                            //(value of l_tmmReturn.proceed is greater than 0) 
                            //or not (value of l_tmmReturn.proceed is 0). 
                            //Execute your business logic only if transaction can proceed further.
                            //If not, then return with an HTTP error code.
                            IF (l_tmmReturn.proceed > 0) THEN                  
 
                                //Execute your business logic. 
                                //Execute SQLs statements or call other functions or stored procedures.
                                doWithdraw(p_amount  => :amount, p_account_id  => :accountId);
 
                                //Call TmmEnd at the end of the REST function.
                                l_tmmReturn2 := TmmEnd(p_xid => l_tmmReturn.xid);      
 
                                :status_code := 200;
 
                            ELSE
                                :status_code := 400; --bad request
 
                            END IF;
 
                        exception
                            when others then
                                :status_code := 500;
 
                         END;',
            p_items_per_page => 0);
 
 
    //Create MicroTx callback APIs.
    createTMMCallbacks(moduleName => restModuleName);
 
    //Register all method handlers that will participate in the XA transaction.
    registerXaHandler(moduleName => restModuleName,
                      handlerPattern => ':accountId/withdraw',
                      handlerMethod => 'POST');
 
COMMIT;
END;
/
MicroTx PL/SQLライブラリ関数を使用するORDSトランザクション参加側アプリケーションのソース・コードは、microtx-samples GitHubリポジトリのxa/plsql/databaseapp/ords_participant_app.sqlにあります。これは、MicroTxライブラリとアプリケーションの統合時に参照として使用できます。

親トピック: XAでのORDSアプリケーションの開発