DBMS_AQ
パッケージは、Oracle Streams Advanced Queuing(AQ)へのインタフェースを提供します。
関連項目:
|
この章では、次の項目について説明します。
定数
データ構造
使用上の注意
DBMS_AQパッケージでは、表21-1に示す定数が使用されます。
BROWSE
、LOCKED
またはREMOVE
などの列挙定数を使用するときは、それを定義しているパッケージの有効範囲内で、PL/SQL定数を指定する必要があります。 操作インタフェースに関連付けられているすべてのタイプに、DBMS_AQ
を付加する必要があります。 たとえば、DBMS_AQ.BROWSE
のようにします。
注意: DBMS_AQADM サブプログラムのmessage_grouping パラメータをTRANSACTIONAL に設定すると、sequence_deviation 属性は、Oracle Streams AQ 10g リリース1(10.1)以前のリリースでは無効になります。Oracle Streams AQ 10g リリース2(10.2)では、順序逸脱機能の使用は推奨されていません。 |
表21-1 列挙定数
パラメータ | オプション | 型 | 説明 |
---|---|---|---|
|
|
||
|
|||
|
|
||
|
|||
|
|||
|
|||
|
|
||
|
|||
|
|
||
|
|||
|
|||
|
|||
|
|
||
|
|||
|
|
|
|
|
|
||
|
|
||
|
|
||
|
|
||
|
|||
|
|
|
|
|
|
|
|
|
|
||
|
|
|
表21-2 DBMS_AQのデータ構造
データ構造 | 説明 |
---|---|
|
データベース・オブジェクトに名前を付けます。 |
|
キュー・タイプを定義します。 |
Oracle Streams AQ PL/SQLコールバック |
メッセージ通知時に起動されるようにデータベースに定義することで、ユーザー定義のPL/SQLプロシージャを指定します。 |
object_name
データ構造は、データベース・オブジェクトの名前を付けます。この構造は、キュー、キュー表、エージェント名およびオブジェクト・タイプに適用されます。
構文
object_name := VARCHAR2; object_name := [schema_name.]name;
使用上の注意
オブジェクト名は、オプションのスキーマ名および名前で指定します。スキーマ名が指定されない場合は、現在のスキーマ名が使用されます。 名前は、予約語について、『Oracle Database SQL言語リファレンス』のオブジェクト名ガイドラインに従う必要があります。 スキーマ、エージェントおよびオブジェクト・タイプの名前は、30バイト以内で設定します。キューおよびキュー表の名前は、24バイト以内で設定します。
type_name
データ構造は、キュー・タイプを定義します。
構文
type_name := VARCHAR2;
type_name := object_type | "RAW";
属性
表21-3 タイプ名の属性
属性 | 説明 |
---|---|
|
オブジェクト・タイプ内の属性の最大数は900です。 |
|
|
plsqlcallback
データ構造は、メッセージ通知時に起動されるようにデータベースで定義することで、ユーザー定義のPL/SQLプロシージャを指定します。
構文
RAW
ペイロード・エンキューの通知メッセージが要求されている場合、PL/SQLコールバックには次の署名が付加されている必要があります。
procedure plsqlcallback( context IN RAW, reginfo IN SYS.AQ$_REG_INFO, descr IN SYS.AQ$_DESCRIPTOR, payload IN RAW, payloadl IN NUMBER);
属性
表21-4 Oracle Streams AQ PL/SQLコールバックの属性
属性 | 説明 |
---|---|
|
|
|
「AQ$_REG_INFOタイプ」を参照してください。 |
|
「AQ$_DESCRIPTORタイプ」を参照してください。 |
|
RAWペイロード・エンキューの通知メッセージが要求されている場合、非永続キューにエンキューされたRAWペイロードが含まれます。RAWペイロードが含まれる永続キューの場合、パラメータはNULLです。 |
|
|
ユーザー定義型のペイロード・エンキューの通知メッセージが要求されている場合、PL/SQLコールバックには次の署名が付加されている必要があります。
procedure plsqlcallback( context IN RAW, reginfo IN SYS.AQ$_REG_INFO, descr IN SYS.AQ$_DESCRIPTOR, payload IN VARCHAR2, payloadl IN NUMBER);
DBMS_AQ
およびDBMS_AQADM
には、Javaインタフェースを使用できます。 Javaインタフェースは、$ORACLE_HOME/rdbms/jlib/aqapi
.jar
にあります。 これらのインタフェースを使用するには、ユーザーにDBMS_AQIN
パッケージのEXECUTE
権限が必要です。
表21-5 DBMS_AQパッケージのサブプログラム
サブプログラム | 説明 |
---|---|
|
LDAPディレクトリにOracle Streams AQエージェントのエントリを作成します。 |
|
指定したキューからメッセージをデキューします。 |
|
指定したキューからメッセージの配列をデキューします。 |
|
指定したキューにメッセージを追加します。 |
|
指定したキューにメッセージの配列を追加します。 |
|
エージェントのリストにかわって1つ以上のキューをリスニングします。 |
|
匿名サブスクリプションに転送します。サブスクリプションに登録された全クライアントが通知を受信できます。 |
|
メッセージ通知を登録します。 |
|
LDAPディレクトリからOracle Streams AQエージェントのエントリを削除します。 |
|
通知をオフにするサブスクリプションを登録解除します。 |
注意: DBMS_AQ には、純正レベルが定義されていません。したがって、RNDS 、WNDS 、RNPS またはWNPS 制約が定義されている他のプロシージャからこのパッケージ内のプロシージャをコールできません。 |
このプロシージャによって、LDAPサーバーにOracle Streams AQエージェントのエントリを作成します。
構文
DBMS_AQ.BIND_AGENT( agent IN SYS.AQ$_AGENT, certificate IN VARCHAR2 default NULL);
パラメータ
表21-6 BIND_AGENTプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
LDAPサーバーで登録されるエージェント。 |
|
このエージェントでデジタル証明書( |
使用上の注意
LDAPサーバーでは、デジタル証明書がOrganizationalPerson
エンティティの属性(usercertificate
)として格納されます。このOrganizationalPerson
の識別名をエージェントのバインド時に指定する必要があります。
このプロシージャは、指定したキューからメッセージをデキューします。
構文
DBMS_AQ.DEQUEUE ( queue_name IN VARCHAR2, dequeue_options IN dequeue_options_t, message_properties OUT message_properties_t, payload OUT "<ADT_1>" msgid OUT RAW);
パラメータ
表21-7 DEQUEUEプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
キュー名を指定します。 |
|
「DEQUEUE_OPTIONS_Tタイプ」を参照してください。 |
|
「MESSAGE_PROPERTIES_Tタイプ」を参照してください。 |
|
Oracle Streams AQによって解釈されません。ペイロードは、関連するキュー表の仕様に基づいて指定する必要があります。 |
|
システムが生成するメッセージID。 |
使用上の注意
デキューされるメッセージの検索基準は、dequeue_options
の次のパラメータによって判断されます。
consumer_name
msgid
msgid
はデキューされるメッセージを一意に識別します。msgid
が指定されていないかぎり、READY
状態のメッセージのみがデキューされます。
correlation
相関識別子は、Oracle Streams AQによって解釈されないアプリケーション定義の識別子です。
deq_condition
デキュー条件は、メッセージ・プロパティ、メッセージ・データ・プロパティおよびPL/SQLファンクションに基づいた式です。deq_condition
はSQL問合せのWHERE
句と同様の構文を使用して、ブール式で指定されます。このブール式には、メッセージ・プロパティ、ユーザー・データのプロパティ(オブジェクト・ペイロードのみ)、およびPL/SQLファンクションまたはSQLファンクション(SQL問合せのWHERE句で指定)に関する条件を組み込むことができます。メッセージ・プロパティには、priority
、corrid
およびキュー表におけるその他の列が含まれます。
メッセージ・ペイロード(オブジェクト・ペイロード)のデキュー条件を指定するには、句にオブジェクト・タイプの属性を使用します。 各属性の前に修飾子としてtab.user_data
を付加して、ペイロードを格納するキュー表の特定の列を示します。
例: tab.user_data.orderstatus='EXPRESS'
デキュー順序は、dequeue_options
のmsgid
と相関IDで上書きされないかぎり、キュー表の作成時に指定した値によって判断されます。
キュー操作には、データベース読込み一貫性メカニズムが適用されます。たとえば、BROWSE
コールは、ブラウズ・トランザクションの開始後にエンキューされたメッセージを参照しない場合があります。
デキュー時のデフォルトのNAVIGATION
パラメータは、NEXT_MESSAGE
です。この場合、後続のデキューは、最初のデキューで取得したスナップショットに基づいて、キューからメッセージを取り出します。特に、最初のデキュー・コマンド後にエンキューされたメッセージは、キュー内の残りのメッセージがすべて処理されるまで処理されません。これは、すべてのメッセージがすでにキューにエンキューされている場合、またはキューに優先順位が設定されていない場合は、通常問題ありません。 ただし、デキュー・コマンドのたびにキュー内の先頭メッセージを処理する必要があるときには、アプリケーションでFIRST_MESSAGE
ナビゲーション・オプションを使用する必要があります。この処理は、すでにエンキューされたメッセージの処理中に優先順位の高いメッセージがキューに登録された場合に必要になります。
注意: 同時にエンキューされている複数のメッセージがある場合は、FIRST_MESSAGE ナビゲーション・オプションを使用すると効率が向上します。 FIRST_MESSAGE オプションが指定されていない場合、Oracle Streams AQは最初のデキュー・コマンド時のスナップショットを生成し続けるため、パフォーマンスが低下します。 FIRST_MESSAGE オプションが指定されている場合、Oracle Streams AQはすべてのデキュー・コマンドに対して新しいスナップショットを使用します。 |
同一トランザクションでメッセージのグループ化に対応しているキューにエンキューされたメッセージは、グループを形成します。そのトランザクションでエンキューされたメッセージが1つのみの場合は、実質的に1つのメッセージでグループを形成します。1つのトランザクションでグループ化できるメッセージの数に上限はありません。
メッセージのグループ化に対応していないキューでは、LOCKED
またはREMOVE
モードのデキューは、1つのメッセージのみロックします。これに対して、グループの一部のメッセージをデキューしようとするデキュー操作は、グループ全体をロックします。これは、グループ内のすべてのメッセージを基本単位で処理する必要がある場合に有効です。
グループ内のすべてのメッセージがデキューされている場合、そのデキューはグループ内のすべてのメッセージが処理済であることを示すエラーを戻します。 この場合、アプリケーションはNEXT_TRANSACTION
を使用して、次に使用可能なグループからメッセージのデキューを開始します。使用可能なグループがない場合、デキューは指定したWAIT
期間後にタイムアウトします。
保護キューの使用方法
保護キューの場合は、dequeue_options
パラメータにconsumer_name
を指定する必要があります。 consumer_name
の詳細は、「DEQUEUE_OPTIONS_Tタイプ」を参照してください。
保護キューを使用するときは、次の事項を満たしている必要があります。
DBMS_AQADM.CREATE_AQ_AGENT
を使用して、有効なOracle Streams AQエージェントを作成している必要があります。「CREATE_AQ_AGENTプロシージャ」を参照してください。
保護キューに対するデキュー権限のあるデータベース・ユーザーにOracle Streams AQエージェントをマップする必要があります。これは、DBMS_AQADM.ENABLE_DB_ACCESS
を使用して行います。「ENABLE_DB_ACCESSプロシージャ」を参照してください。
関連項目: 保護キューの詳細は、『Oracle Streams概要および管理』を参照してください。 |
このファンクションはメッセージの配列をデキューし、ペイロードの配列、メッセージ・プロパティの配列およびメッセージIDの配列の形式でそれらを戻します。このファンクションは、正常にデキューされたメッセージの数を返します。
構文
DBMS_AQ.DEQUEUE_ARRAY ( queue_name IN VARCHAR2, dequeue_options IN dequeue_options_t, array_size IN pls_integer, message_properties_array OUT message_properties_array_t, payload_array OUT "<COLLECTION_1>", msgid_array OUT msgid_array_t, error_array OUT error_array_t) RETURN pls_integer;
パラメータ
表21-8 DEQUEUE_ARRAYファンクションのパラメータ
パラメータ | 説明 |
---|---|
|
メッセージをデキューするキュー名(単一行デキューと同じ)。 |
|
配列内のすべてのメッセージに適用する一連のオプション(単一行デキューと同じ)。 |
|
デキューする要素の数。 |
|
各メッセージ・プロパティに対応する配列を格納するレコード。各ペイロード要素は、対応する一連のメッセージ・プロパティを持ちます。「MESSAGE_PROPERTIES_ARRAY_Tタイプ」を参照してください。 |
|
デキューされたペイロード・データの配列。 "<COLLECTION_1>"は連想配列、VARRAYまたはPL/SQL表現でのネストした表です。 |
|
デキューされたメッセージのメッセージIDの配列。「MSGID_ARRAY_Tタイプ」を参照してください。 |
|
現在、実装されていません。 |
使用上の注意
dequeue_options
に指定する0(ゼロ)以外の待機時間は、キュー内にメッセージがない場合にのみ認識されます。 キューにデキュー可能なメッセージが格納されている場合、DEQUEUE_ARRAY
ファンクションによって、最大array_size
メッセージがデキューされ、ただちに戻ります。
message_id
によるデキューはサポートしていません。navigation
パラメータの詳細は、「DEQUEUEプロシージャ」を参照してください。既存のNAVIGATION
モードをサポートしています。さらに、メッセージのグループ化に対応しているキュー用に、2つの新しいNAVIGATION
モードをサポートしています。
FIRST_MESSAGE_MULTI_GROUP
NEXT_MESSAGE_MULTI_GROUP
トランザクション・グループ・キューおよびONE_GROUP
ナビゲーションの場合、メッセージはarray_size
制限に従って、単一のトランザクション・グループからのみデキューされます。 MULTI_GROUP
ナビゲーションでは、メッセージはarray_size
制限に従って、複数のトランザクション・グループからデキューされます。 ORA-25235が返され、トランザクション・グループの終わりを示します。
DEQUEUE_ARRAY
は、バッファに入れたメッセージではサポートされませんが、1つのメッセージにarray_size
を設定すると、バッファに入れた個々のメッセージで使用できます。
このプロシージャは、指定したキューにメッセージを追加します。
構文
DBMS_AQ.ENQUEUE ( queue_name IN VARCHAR2, enqueue_options IN enqueue_options_t, message_properties IN message_properties_t, payload IN "<ADT_1>", msgid OUT RAW);
パラメータ
表21-9 ENQUEUEプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
このメッセージをエンキューするキュー名を指定します。例外キューは指定できません。 |
|
「ENQUEUE_OPTIONS_Tタイプ」を参照してください。 |
|
「MESSAGE_PROPERTIES_Tタイプ」を参照してください。 |
|
Oracle Streams AQによって解釈されません。ペイロードは、関連するキュー表の仕様に基づいて指定する必要があります。 |
|
システムが生成するメッセージID。これは、デキュー時にメッセージを識別するために使用するグローバルな一意のIDです。 |
使用上の注意
enqueue_options
のsequence_deviation
パラメータを使用すると、2つのメッセージ間の処理順序を変更できます。 参照されるメッセージのIDは、enqueue_options
のパラメータrelative_msgid
で指定できます。 関係は、sequence_deviation
パラメータによって識別されます。
メッセージにsequence_deviation
を指定すると、このメッセージに指定できる遅延および優先の順位値が一部制限されます。遅延の値は、このメッセージより後にエンキューされるメッセージの遅延以下に設定する必要があります。優先順位は、このメッセージより後にエンキューされるメッセージの優先順位以上に設定する必要があります。
注意: DBMS_AQADM サブプログラムのmessage_grouping パラメータをTRANSACTIONAL に設定すると、sequence_deviation 属性は、Oracle Streams AQ 10g リリース1(10.1)以前のリリースでは無効になります。Oracle Streams AQ 10g リリース2(10.2)では、順序逸脱機能の使用は推奨されていません。 |
メッセージが受信者のいないマルチ・コンシューマ・キューにエンキューされ、かつそのキューにサブスクライバが存在しない(またはこのメッセージと一致するルールベースのサブスクライバが存在しない)場合は、OracleエラーORA
_24033
が発生します。これは、配信可能な受信者またはサブスクライバが存在しないために、そのメッセージが廃棄されることを示す警告です。
保護キューの使用方法
保護キューの場合は、messages_properties
パラメータにsender_id
を指定する必要があります。 sender_id
の詳細は、「MESSAGE_PROPERTIES_Tタイプ」を参照してください。
保護キューを使用するときは、次の事項を満たしている必要があります。
DBMS_AQADM.CREATE_AQ_AGENT
を使用して、有効なOracle Streams AQエージェントを作成している必要があります。「CREATE_AQ_AGENTプロシージャ」を参照してください。
保護キューに対するエンキュー権限のあるデータベース・ユーザーにsender_id
をマップする必要があります。これは、DBMS_AQADM.ENABLE_DB_ACCESS
を使用して行います。「ENABLE_DB_ACCESSプロシージャ」を参照してください。
関連項目: 保護キューの詳細は、『Oracle Streams概要および管理』を参照してください。 |
このファンクションは、対応するメッセージ・プロパティの配列を使用して、ペイロードの配列をエンキューします。出力は、エンキューしたメッセージのメッセージIDの配列になります。
構文
DBMS_AQ.ENQUEUE_ARRAY ( queue_name IN VARCHAR2, enqueue_options IN enqueue_options_t, array_size IN pls_integer, message_properties_array IN message_properties_array_t, payload_array IN "<COLLECTION_1>", msgid_array OUT msgid_array_t, error_array OUT error_array_t) RETURN pls_integer;
パラメータ
表21-10 ENQUEUE_ARRAYファンクションのパラメータ
パラメータ | 説明 |
---|---|
|
メッセージをエンキューするキュー名(単一行エンキューと同じ)。 |
|
「ENQUEUE_OPTIONS_Tタイプ」を参照してください。 |
|
エンキューする要素の数。 |
|
各メッセージ・プロパティに対応する配列を格納するレコード。 プロパティごとに |
|
ペイロード・データの配列。 "< |
|
エンキューされたメッセージのメッセージIDの配列。特定のメッセージでエラーが発生すると、対応するメッセージIDがNULLになります。「MSGID_ARRAY_Tタイプ」を参照してください。 |
|
現在、実装されていません。 |
使用上の注意
ENQUEUE_ARRAY
は、バッファに入れたメッセージではサポートされませんが、1つのメッセージにarray_size
を設定すると、バッファに入れた個々のメッセージで使用できます。
このプロシージャは、エージェントのリストのかわりに1つ以上のキューをリスニングします。エージェントのアドレス・フィールドは、エージェントが監視するキューを示します。ローカル・キューのみアドレスとしてサポートされています。将来使用するためにプロトコルが予約されています。
構文
DBMS_AQ.LISTEN ( agent_list IN AQ$_AGENT_LIST_T, wait IN BINARY_INTEGER DEFAULT DBMS_AQ.FOREVER, agent OUT SYS.AQ$_AGENT);
DBMS_AQ.LISTEN ( agent_list IN AQ$_AGENT_LIST_T, wait IN BINARY_INTEGER DEFAULT FOREVER, listen_delivery_mode IN PLS_INTEGER DEFAULT DBMS_AQ.PERSISTENT, agent OUT SYS.AQ$_AGENT, message_delivery_mode OUT PLS_INTEGER);
TYPE aq$_agent_list_t IS TABLE of aq$_agent INDEXED BY BINARY_INTEGER; TYPE aq$_agent_list_t IS TABLE of aq$_agent INDEXED BY BINARY_INTEGER;
パラメータ
表21-11 LISTENプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
リスニングするエージェントのリスト。 |
|
リスニング・コールのタイムアウト(秒数)。デフォルトでは、コールは永続的にブロックします。 |
|
永続メッセージ、バッファに入れたメッセージまたは両方のタイプのメッセージのいずれを優先するかをコール元が指定します。 |
|
コンシューマ用のメッセージがあるエージェント。 |
|
メッセージがあるキューおよびコンシューマとともにメッセージ・タイプを戻します。 |
使用上の注意
エージェント・アドレスがマルチ・コンシューマ・キューである場合、エージェント名は必須項目です。単一コンシューマ・キューの場合は、エージェント名を指定する必要はありません。
このプロシージャは、引数としてエージェントのリストを使用します。リストされた各エージェントのアドレス・フィールドに、監視するキューを指定します。マルチ・コンシューマ・キューを監視するときは、エージェントの名前も指定する必要があります。単一コンシューマ・キューの場合は、エージェント名を指定する必要はありません。ローカル・キューのみアドレスとしてサポートされています。将来使用するためにプロトコルが予約されています。
これは、リスト内のエージェントに対してコンシューマ用のメッセージが準備されているときに戻されるブロック・コールです。複数のエージェントに対するメッセージがある場合は、リストの最初のエージェントのみ戻されます。待機時間が期限切れしてもメッセージが見つからない場合は、エラーが発生します。
LISTEN
コールが正常に戻された場合でも、指定したキューの中に、リストされたエージェントの1つに対するメッセージがあることのみを示しています。対象となっているエージェントは、関連メッセージを継続してデキューする必要があります。
注意: 非永続キューでは、LISTEN はコールできません。 |
このプロシージャにより、匿名サブスクリプションのリストに転送します。匿名サブスクリプションの場合、サブスクリプションに登録された全クライアントが通知を受信できます。
構文
DBMS_AQ.POST ( post_list IN SYS.AQ$_POST_INFO_LIST, post_count IN NUMBER);
パラメータ
表21-12 POSTプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
転送する匿名サブスクリプションのリストを指定します。 AQ$_POST_INFO_LISTタイプのリストです。 |
|
|
使用上の注意
このプロシージャにより、匿名サブスクリプションに転送します。匿名サブスクリプションの場合、サブスクリプションに登録された全クライアントが通知を受信できます。複数のサブスクリプションを一度に転送することもできます。
このプロシージャにより、電子メール・アドレス、ユーザー定義のPL/SQLプロシージャまたはメッセージ通知用のHTTP URLを登録します。
構文
DBMS_AQ.REGISTER ( reg_list IN SYS.AQ$_REG_INFO_LIST, count IN NUMBER);
パラメータ
表21-13 REGISTERプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
メッセージ通知用に登録するサブスクリプションのリストを指定します。AQ$_REG_INFOタイプのリストです。 |
|
|
使用上の注意
このプロシージャは、通知の登録に使用します。メッセージ通知の送信先電子メール・アドレスの指定、通知時に起動するプロシージャの登録または通知転送先のHTTP URLの登録ができます。複数のサブスクリプションを一度に登録することもできます。
プロシージャは、次に示す5つのグループ化属性を使用して、グループ化通知を登録する場合にも使用できます。
Class: グループ化の基準(現在、TIME
基準のみサポート)
Value: グループ化の基準値(現在、TIME
基準の時間(秒)のみ)
Type: 要約または最新の通知。グループで受信した通知の数も含みます(AQネームスペースに対してのみ。DBCHANGE
ネームスペースは対象外)
Repeat count: グループ化を実行する回数(デフォルトはFOREVER
)
Start time: グループ化を開始する時間(デフォルトは現在の時間)
電子メール通知を登録する場合、データベースが電子メール通知の送信に使用するSMTPサーバーのホスト名およびポート名を設定する必要があります。必要であれば、発信元電子メール・アドレスを設定します。これは、データベースのsent
from
フィールドで設定します。この機能を使用するには、Java対応のデータベースが必要です。
HTTP通知を登録する場合、データベースがHTTP通知の転送に使用するプロキシ・サーバーおよび非プロキシ・ドメイン・リストのホスト名およびポート名を設定する必要があります。
このプロシージャにより、LDAPサーバーからOracle Streams AQエージェントのエントリを削除します。
構文
DBMS_AQ.UNBIND_AGENT( agent IN SYS.AQ$_AGENT);
パラメータ
このプロシージャでは、通知をオフにするサブスクリプションを登録解除します。
構文
DBMS_AQ.UNREGISTER ( reg_list IN SYS.AQ$_REG_INFO_LIST, reg_count IN NUMBER);
パラメータ
表21-15 UNREGISTERプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
メッセージ通知用に登録するサブスクリプションのリストを指定します。AQ$_REG_INFOタイプのリストです。 |
|
|
使用上の注意
このプロシージャにより、通知をオフにするサブスクリプションを登録解除します。複数のサブスクリプションを一度に登録解除することもできます。