DBMS_SAGA

160 DBMS_SAGA_ADM

DBMS_SAGA_ADMパッケージは、saga参加者、コーディネータおよびブローカを定義および管理するためのsaga管理ファンクションおよびプロシージャのコレクションを提供します。

この章のトピックは、次のとおりです:

160.1 DBMS_SAGA_ADMの概要

SYS.DBMS_SAGA_ADMパッケージは、sagaを管理するためのsaga管理APIを提供します。

DBMS_SAGA_ADMパッケージを使用して実装されたsaga管理APIを使用すると、管理者はsaga参加者、コーディネータおよびブローカを定義および管理できます。ここでは、参照用にパッケージAPIについて説明します。

160.2 DBMS_SAGA_ADMのセキュリティ・モデル

参加者は、DBMS_SAGA_ADMパッケージのプロシージャをスキーマおよびPDB内から呼び出す必要があります。DBMS_SAGA_ADMパッケージのAPIを呼び出すには、SAGA_ADM_ROLEロールが必要です。

160.3 DBMS_SAGA_ADMサブプログラムの要約

この表では、DBMS_SAGA_ADMパッケージのサブプログラムをリストし、簡単に説明します。

表160-1 DBMS_SAGA_ADMパッケージのサブプログラム

サブプログラム	説明
ADD_COORDINATORプロシージャ	sagaフレームワークにsagaコーディネータを追加します
DROP_COORDINATORプロシージャ	指定されたコーディネータをsagaフレームワークから削除します。
ADD_PARTICIPANTプロシージャ	ローカルPDBおよびブローカに参加者を追加します
DROP_PARTICIPANTプロシージャ	参加者に保留中のsagaおよび保留中のsagaメッセージがない場合は、ローカルPDBおよびブローカ上の特定の参加者を削除します。
ADD_BROKERプロシージャ	sagaフレームワークにブローカを追加し、ブローカのJMSトピックを作成します。
DROP_BROKERプロシージャ	ブローカおよび関連するJMSトピックを削除します。
REGISTER_SAGA_CALLBACKプロシージャ	ユーザーはコールバック・パッケージを作成したり、`add_participant`プロシージャを使用して作成されている場合にコールバック・パッケージを変更できます。

160.3.1 ADD_BROKERプロシージャ

このプロシージャは、sagaフレームワークにブローカを追加します。

ブローカの追加の一環として、ブローカのJMSトピックが作成されます。参加者からブローカへの受信メッセージと送信メッセージの両方の伝播チャネルで、ブローカのJMSトピックが使用されます。

構文

add_broker(
 broker_name                  IN varchar2,
 broker_schema                IN varchar2 default sys_context('userenv', 'CURRENT_USER'),
 storage_clause               IN varchar2 default NULL,
 queue_partitions             IN number DEFAULT 1,
 version                      IN number default 1
 );

パラメータ

表160-2 ADD_BROKERプロシージャのパラメータ

パラメータ	説明
`broker_name`	一意のブローカ名。
`broker_schema`	追加するマイクロサービス参加者のスキーマ。値を指定しない場合、`CURRENT_USER`が使用されます。
`storage_clause`	記憶域パラメータはインバウンドおよびアウトバウンドJMSトピックの作成時に、`CREATE_TRANSACTIONAL_EVENT_QUEUE`文に組み込まれます。`storage_clause`引数には、標準の`DBMS_AQADM.CREATE_TRANSACTIONAL_EVENT_QUEUE` `storage_clause`引数に使用できるテキストを入力できます。
`queue_partitions`	SagaエンティティのIN/OUTキューのパーティション数。これにより、Sagaエンティティの並列性とスループットの向上が可能になります。`DEFAULT`は1です。
`version`	Sagaのバージョン

160.3.2 DROP_BROKERプロシージャ

このプロシージャは、ブローカおよび関連するJMSトピックを削除します。

ブローカは、登録済の参加者およびブローカの保留中メッセージがない場合にのみ削除できます。

構文

drop_broker(broker_name      IN varchar2)

パラメータ

表160-3 DROP_BROKERプロシージャのパラメータ

パラメータ	説明
`broker_name`	削除するブローカ名。

160.3.3 ADD_COORDINATORプロシージャ

このプロシージャは、SagaフレームワークにSagaコーディネータを追加します。Sagaコーディネータは、Sagaのトランザクション・マネージャとして機能します。Sagaコーディネータは、様々な参加者にわたってSagaの状態を保持します。

構文

add_coordinator(
 coordinator_name       IN varchar2,
 coordinator_schema     IN varchar2 DEFAULT sys_context(‘USERENV’, ‘CURRENT_USER’),
 storage_clause         IN varchar2 DEFAULT NULL,
 dblink_to_broker       IN varchar2 DEFAULT NULL,
 mailbox_schema         IN varchar2,
 broker_name            IN varchar2,
 dblink_to_coordinator  IN varchar2 DEFAULT NULL,
 queue_partitions       IN number DEFAULT 1,
 listener_count         IN number DEFAULT -1,
 version                IN number default 1);

パラメータ

表160-4 ADD_COORDINATORプロシージャのパラメータ

パラメータ	説明
`coordinator_name`	Sagaコーディネータの一意の名前。
`coordinator_schema`	追加するSagaコーディネータのスキーマ。値が指定されていない場合、このパラメータは`CURRENT_USER`を使用します。
`storage_clause`	記憶域パラメータはインバウンドおよびアウトバウンドJMSトピックの作成時に、`CREATE_TRANSACTIONAL_EVENT_QUEUE`文に組み込まれます。`storage_clause`引数には、標準の`DBMS_AQADM.CREATE_TRANSACTIONAL_EVENT_QUEUE` `storage_clause`引数に使用できるテキストを入力できます。
`dblink_to_broker`	コーディネータPDBからブローカPDBに接続するための事前作成済データベース・リンク。
`mailbox_schema`	ブローカにおけるメールボックス所有者のスキーマ。
`broker_name`	ブローカの名前。
`dblink_to_coordinator`	ブローカPDBからコーディネータPDBに接続するための事前作成済データベース・リンク。
`queue_partitions`	SagaエンティティのIN/OUTキューのパーティション数。これにより、Sagaエンティティの並列性とスループットの向上が可能になります。`DEFAULT`は1です。ノート: キュー・パーティションの数は、`add_broker()`操作の実行時に指定したパーティション数と同じにする必要があります。
`listener_count`	Sagaコーディネータのインバウンド・メッセージを処理する同時Sagaリスナー・プロセスの数。 `listener_count`には、次のいずれかの値を指定できます: `DBMS_SAGA_ADM.AQ_NTFN`。これは、`DEFAULT`でもあります。この場合、Sagaコーディネータはメッセージの処理にAQ通知メカニズムを使用します。 `DBMS_SAGA_ADM.AUTO_NTFN`- この場合、Sagaコーディネータは、メッセージの処理にコーディネータ・キューからデキューするジョブ・キュー・プロセスを使用します。このジョブは、キューの深さに応じて自動的にジョブを追加および削除します。正の数(N)を指定すると、Sagaコーディネータのメッセージ処理のためにN個の固定ジョブが作成されます。
`version`	Sagaのバージョン

160.3.4 DROP_COORDINATORプロシージャ

このプロシージャは、指定されたコーディネータを削除し、コーディネータとブローカ間のメッセージの伝播を無効にします。コーディネータは、コーディネータに関連付けられた参加者がいない場合にのみ削除できます。

構文

drop_coordinator(coordinator_name  IN varchar2)

パラメータ

表160-5 DROP_COORDINATORプロシージャのパラメータ

パラメータ	説明
`coordinator_name`	削除するsagaコーディネータの名前。

160.3.5 ADD_PARTICIPANTプロシージャ

このプロシージャは、データベースおよびブローカにSaga参加者を追加します。

参加者名は、参加者が追加されるブローカに対して一意です。ADD_PARTICIPANTプロシージャは、参加者のシステム定義のインバウンドおよびアウトバウンドJMSトピックを作成します。トピックが存在しない場合は、ブローカ側にもJMSトピックが作成されます。メッセージ伝播関係は、次から設定されます。

ブローカのJMSトピックに対する参加者のアウトバウンドJMSトピック。
参加者のインバウンドJMSトピックに対するブローカのJMSトピック。

構文

add_participant(
 participant_name            IN varchar2,
 participant_schema          IN varchar2 DEFAULT sys_context('USERENV', 'CURRENT_USER'),
 storage_clause              IN varchar2 DEFAULT NULL,
 coordinator_name            IN varchar2 DEFAULT NULL,
 dblink_to_broker            IN varchar2,
 mailbox_schema              IN varchar2,
 broker_name                 IN varchar2,
 callback_schema             IN varchar2 DEFAULT sys_context(‘USERENV’,’CURRENT_USER’),
 callback_package            IN varchar2,
 dblink_to_participant       IN varchar2,
 queue_partitions            IN number DEFAULT 1,
 version                     IN number DEFAULT 1
 );

パラメータ

表160-6 ADD_PARTICIPANTプロシージャのパラメータ

パラメータ	説明
`participant_name`	saga参加者の一意の名前。
`participant_schema`	追加するsaga参加者のスキーマ。値が指定されていない場合、このパラメータは`CURRENT_USER`を使用します。
`storage_clause`	記憶域パラメータはインバウンドおよびアウトバウンドJMSトピックの作成時に、`CREATE_TRANSACTIONAL_EVENT_QUEUE`文に組み込まれます。`storage_clause`引数には、標準の`DBMS_AQADM.CREATE_TRANSACTIONAL_EVENT_QUEUE` `storage_clause`引数に使用できるテキストを入力できます。
`coordinator_name`	sagaコーディネータの名前。値が指定されておらず、`create_coordinator`が`TRUE`の場合、システム生成名が使用されます。
`dblink_to_broker`	参加者PDBからブローカPDBに接続するための事前作成済データベース・リンク。
`mailbox_schema`	ブローカ側のメールボックス所有者のスキーマ。
`broker_name`	ブローカの名前。値を指定しない場合、`mailbox_schema`名が使用されます。
`callback_schema`	ユーザー定義コールバック・パッケージのスキーマ。値を指定しない場合、`CURRENT_USER`が使用されます。
`callback_package`	ユーザー定義コールバック・パッケージの名前。コールバック・パッケージを使用すると、アプリケーション開発者はsagaインフラストラクチャの内部詳細から分離され、ビジネス・ロジックに集中できます。
`dblink_to_participant`	ブローカPDBから参加者PDBに接続するための事前作成済データベース・リンク。
`queue_partitions`	SagaエンティティのIN/OUTキューのパーティション数。これにより、Sagaエンティティの並列性とスループットの向上が可能になります。`DEFAULT`は1です。ノート: キュー・パーティションの数は、`add_broker()`操作の実行時に指定したパーティション数と同じにする必要があります。
`version`	Sagaのバージョン

使用上のノート

ADD_PARTICIPANTプロシージャには引数としてコーディネータ名が必要であるため、ADD_PARTICIPANTプロシージャの前にADD_COORDINATORプロシージャを使用する必要があります。

160.3.6 DROP_PARTICIPANTプロシージャ

このプロシージャは、ローカルPDBおよびブローカ上の指定された参加者を削除します。

DROP_PARTICIPANTプロシージャは、参加者に保留中のsagaおよび保留中のsagaメッセージがない場合に、ローカルPDBおよびブローカ上の特定の参加者を削除します。DROP_PARTICIPANTプロシージャは、参加者とブローカ間のメッセージの伝播も無効にします。

構文

drop_participant(participant_name  IN varchar2)

パラメータ

表160-7 DROP_PARTICIPANTプロシージャのパラメータ

パラメータ	説明
`participant_name`	削除する参加者マイクロサービスの名前。

160.3.7 REGISTER_SAGA_CALLBACKプロシージャ

このプロシージャを使用すると、ユーザーは、コールバック・パッケージを作成したり、パッケージがADD_PARTICIPANTプロシージャを使用して作成されている場合にコールバック・パッケージを変更できます。

コールバック・パッケージが前に追加されていない場合、REGISTER_SAGA_CALLBACKプロシージャによって必要なサブスクライバと通知コールバックが設定されます。参加者の追加時に、コールバック・パッケージを指定するオプションがあります。コールバック・パッケージの指定を延期する場合や、コールバック・パッケージを変更する場合は、REGISTER_SAGA_CALLBACKプロシージャを使用できます。参加者に対するコールバックがすでに存在する場合は、単純に置き換えられます。REGISTER_SAGA_CALLBACKプロシージャは、ユーザーがPL/SQLとJavaのどちらを実装するかが不明で、後でそれを決定する場合や、ユーザーが実装を(たとえば、JavaクライアントからPL/SQLベースのクライアントに)切り替える場合に役立ちます。

構文

register_saga_callback(participant_name IN varchar2,
 callback_schema        IN varchar2 default sys_context(‘USERENV’,’CURRENT_USER'),
 callback_package       IN varchar2);

パラメータ

表160-8 REGISTER_SAGA_CALLBACKプロシージャのパラメータ

パラメータ	説明
`participant_name`	すでに作成されている参加者の名前。
`callback_schema`	ユーザー定義コールバック・パッケージのスキーマ。値を指定しない場合、`CURRENT_USER`が使用されます。
`callback_package`	ユーザー定義コールバック・パッケージの名前。コールバック・パッケージを使用すると、アプリケーション開発者はsagaインフラストラクチャの内部詳細から分離され、ビジネス・ロジックに集中できます。