OracleAQQueueクラス

OracleAQQueueオブジェクトは、キューを表します。

クラスの継承

System.Object

OracleAQQueue

宣言

// C#
public class OracleAQQueue : IDisposable

スレッド安全性

パブリック静的メソッドはスレッドセーフですが、インスタンス・メソッドではスレッド安全性は保証されません。

備考

キューとはメッセージのリポジトリであり、ユーザー・キューと例外キューのいずれかです。ユーザー・キューは通常のメッセージ処理に使用されます。なんらかの理由でメッセージを取り出して処理することができない場合、そのメッセージはユーザー・キューから例外キューに移動されます。

要件

ネームスペース: Oracle.DataAccess.Client

アセンブリ: Oracle.DataAccess.dll

ODP.NETのバージョン: ODP.NET for .NET Framework 2.0またはODP.NET for .NET Framework 4

関連項目:

Oracle.DataAccess.Clientネームスペース
OracleAQQueueメンバー
OracleAQQueueコンストラクタ
OracleAQQueue静的メソッド
OracleAQQueueプロパティ
OracleAQQueueパブリック・メソッド
OracleAQQueueイベント

OracleAQQueueメンバー

OracleAQQueueメンバーを、次の各表に示します。

OracleAQQueueコンストラクタ

OracleAQQueueコンストラクタを、表12-19にリストします。

表12-19 OracleAQQueueコンストラクタ

コンストラクタ	説明
OracleAQQueueコンストラクタ	`OracleAQQueue`クラスの新規インスタンスをインスタンス化します(オーバーロード)。

OracleAQQueue静的メソッド

OracleAQQueue静的メソッドを、表12-20にリストします。

表12-20 OracleAQQueue静的メソッド

静的メソッド	説明
Listen	`OracleAQAgent`オブジェクトの配列に指定された1つ以上のコンシューマについて、1つ以上のキューでメッセージをリスニングします(オーバーロード)。

OracleAQQueueプロパティ

OracleAQQueueプロパティを、表12-21にリストします。

表12-21 OracleAQQueueプロパティ

プロパティ	説明
Connection	キューに関連付けられた`OracleConnection`オブジェクトを指定します。
DequeueOptions	キューからメッセージをデキューする際に使用するデキュー・オプションを指定します。
EnqueueOptions	キューにメッセージをエンキューするために使用されるエンキュー・オプションを指定します。
MessageType	このキューに関連付けられたキュー表のタイプを指定します。
名前	キューの名前を戻します。
Notification	`MessageAvailable`イベントを使用して登録する通知の様々な通知オプションを指定します。
NotificationConsumers	キューの受信メッセージについて非同期に通知を受ける、複数コンシューマ・キューのコンシューマの配列を指定します。
UdtTypeName	`MessageType`が`OracleAQMessageType.UDT`の場合にキューおよび対応するキュー表のベースとなるタイプ名を指定します。

OracleAQQueueパブリック・メソッド

OracleAQQueueパブリック・メソッドを、表12-22にリストします。

表12-22 OracleAQQueueパブリック・メソッド

パブリック・メソッド	説明
Dequeue	キューからメッセージをデキューします(オーバーロード)。
DequeueArray	キューから複数のメッセージをデキューします(オーバーロード)。
Dispose	オブジェクトにより割り当てられたリソースまたはメモリーを解除します
Enqueue	キューにメッセージをエンキューします(オーバーロード)。
EnqueueArray	キューに複数のメッセージをエンキューします(オーバーロード)。
Listen	`listenConsumers`に代わってキューのメッセージをリスニングします(オーバーロード)。

OracleAQQueueイベント

OracleAQQueueイベントを、表12-23にリストします。

表12-23 OracleAQQueueイベント

イベント名	説明
MessageAvailable Event	`NotificationConsumers`がキュー内のメッセージを使用できるようになると通知します。

関連項目:

OracleAQQueueコンストラクタ

OracleAQQueueコンストラクタは、OracleAQQueueクラスの新規インスタンスを作成します。

オーバーロード・リスト:

OracleAQQueue(string)

このコンストラクタは、キュー名を使用してキュー・オブジェクトを初期化します。
OracleAQQueue(string, OracleConnection)

このコンストラクタは、キュー名と接続を使用してキュー・オブジェクトを初期化します。キュー・オブジェクトの作成時に接続がオープンしている必要はありません。
OracleAQQueue(string, OracleConnection, OracleAQMessageType)

このコンストラクタは、キュー名、接続およびメッセージ・タイプの列挙を使用してキュー・オブジェクトを初期化します。
OracleAQQueue(string, OracleConnection, OracleAQMessageType, string)

このコンストラクタは、キュー名、接続、メッセージ・タイプの列挙およびUDTタイプ名を使用してキュー・オブジェクトを初期化します。

関連項目:

OracleAQQueue(string)

このコンストラクタは、キュー名を使用してキュー・オブジェクトを初期化します。

宣言

// C#
public OracleAQQueue(string name);

パラメータ

name

データベースで指定されているキューの名前。

例外

ArgumentNullException - キュー名がnullです。

ArgumentException - キュー名が空です。

備考

OracleAQQueueオブジェクトの作成操作では、データベースにキューが存在するかどうかはチェックされません。

関連項目:

OracleAQQueue(string, OracleConnection)

このコンストラクタは、キュー名と接続を使用してキュー・オブジェクトを初期化します。キュー・オブジェクトの作成時に接続がオープンしている必要はありません。

宣言

// C#
public OracleAQQueue(string name, OracleConnection con);

パラメータ

name

データベースで指定されているキューの名前。
con

キューに接続するOracleConnectionオブジェクト。

例外

ArgumentNullException - 接続がnullか、キュー名がnullです。

ArgumentException - キュー名が空です。

備考

接続にはConnectionプロパティを使用してアクセスできます。この接続は、EnqueueやDequeueなどの操作APIをコールする前にオープンしておく必要があります。

OracleAQQueueオブジェクトの作成時には、データベースにキューが存在するかどうかはチェックされません。

関連項目:

OracleAQQueue(string, OracleConnection, OracleAQMessageType)

このコンストラクタは、キュー名、接続およびメッセージ・タイプの列挙を使用してキュー・オブジェクトを初期化します。キュー・オブジェクトの作成時に接続がオープンしている必要はありません。

宣言

// C#
public OracleAQQueue(string name, OracleConnection con, OracleAQMessageType
  messageType);

パラメータ

name

データベースで指定されているキューの名前。
con

キューへの接続に使用されるOracleConnectionオブジェクト。
messageType

このキューに対してエンキューまたはデキューされるメッセージのタイプを指定するOracleAQMessageTypeの列挙。

例外

ArgumentNullException - 接続がnullか、キュー名がnullです。

ArgumentException - キュー名が空か、指定したメッセージ・タイプが無効です。

備考

OracleAQQueueオブジェクトの作成時には、データベースにキューが存在するかどうかはチェックされません。

messageTypeがUDTの場合、キュー・オブジェクトを使用する前にUdtTypeNameプロパティを設定しておく必要があります。udtTypeNameを指定することで、もう1つのコンストラクタ・オーバーロードを使用してキューを作成する方法もあります。

関連項目:

OracleAQQueue(string, OracleConnection, OracleAQMessageType, string)

このコンストラクタは、キュー名、接続、メッセージ・タイプの列挙およびUDTタイプ名を使用してキュー・オブジェクトを初期化します。キュー・オブジェクトの作成時に接続がオープンしている必要はありません。

宣言

// C#
public OracleAQQueue(string name, OracleConnection con, OracleAQMessageType
  messageType, string udtTypeName);

パラメータ

name

データベースで指定されているキューの名前。
con

キューへの接続に使用されるOracleConnectionオブジェクト。
messageType

このキューに対してエンキューまたはデキューされるメッセージのタイプを指定するOracleAQMessageTypeの列挙。
udtTypeName

messageTypeがUDTの場合に使用されるデータベース・オブジェクト・タイプの名前。udtTypeNameパラメータは、キューのベースとなるタイプを表します。

例外

ArgumentNullException - 接続がnullか、キュー名がnullです。

ArgumentException - キュー名が空か、指定したmessageTypeが無効です。

備考

OracleAQQueueオブジェクトの作成時には、データベースにキューが存在するかどうかはチェックされません。

関連項目:

OracleAQQueue静的メソッド

OracleAQQueue静的メソッドを、表12-24にリストします。

表12-24 OracleAQQueue静的メソッド

静的メソッド	説明
Listen	`OracleAQAgent`オブジェクトの配列に指定された1つ以上のコンシューマについて、1つ以上のキューでメッセージをリスニングします(オーバーロード)。

関連項目:

リスニング

Listenメソッドは、OracleAQAgentオブジェクトの配列に指定された1つ以上のコンシューマについて、1つ以上のキューでメッセージをリスニングします。

オーバーロード・リスト

Listen(OracleConnection, OracleAQAgent[ ])

この静的メソッドは、OracleAQAgentオブジェクトの配列に指定された1つ以上のコンシューマについて、1つ以上のキューでメッセージをリスニングします。
Listen(OracleConnection, OracleAQAgent[ ], int)

この静的メソッドは、OracleAQAgentオブジェクトの配列に指定された1つ以上のコンシューマについて、1つ以上のキューでメッセージをリスニングします。このメソッドには待機時間も指定します。

関連項目:

Listen(OracleConnection, OracleAQAgent[ ])

この静的メソッドは、OracleAQAgentオブジェクトの配列に指定された1つ以上のコンシューマについて、1つ以上のキューでメッセージをリスニングします。

宣言

// C#
public static OracleAQAgent Listen(OracleConnection con, OracleAQAgent[]
  listenConsumers);

パラメータ

con

OracleConnectionインスタンス。
listenConsumers

リスニングされるコンシューマの配列。単一コンシューマ・キューの場合は、OracleAQAgentオブジェクトの名前をnullまたは空にする必要があります。

戻り値

OracleAQAgentオブジェクト。

例外

ArgumentNullException - conまたはlistenConsumersパラメータがnullです。

InvalidOperationException - 接続がオープンされていません。

備考

Listenは、いずれかのキューでコンシューマがメッセージを使用できるようになるまで複数のキューを監視する必要がある場合に便利です。OracleAQAgentオブジェクトのNameプロパティはコンシューマの名前を表し、Addressプロパティはキューの名前を表します。

このコールは、リスト内のコンシューマがメッセージを消費できるようになるまでコール元のスレッドをブロックします。このコールは、デキュー可能になったメッセージのコンシューマとキューを指定するOracleAQAgentオブジェクトを戻します。

関連項目:

Listen(OracleConnection, OracleAQAgent[ ], int)

この静的メソッドは、OracleAQAgentオブジェクトの配列に指定された1つ以上のコンシューマについて、1つ以上のキューでメッセージをリスニングします。OracleAQAgentオブジェクトのNameプロパティはコンシューマの名前を表し、OracleAQAgentオブジェクトのAddressプロパティはキューの名前を表します。

タイムアウトした場合、このメソッドはnullを戻します。

宣言

// C#
public static OracleAQAgent Listen(OracleConnection con, OracleAQAgent[]
  listenConsumers, int waitTime);

パラメータ

con

OracleConnectionインスタンス。
listenConsumers

リスニングされるコンシューマの配列。単一コンシューマ・キューの場合は、OracleAQAgentオブジェクトの名前をnullまたは空にする必要があります。
waitTime

待機時間(秒)。

戻り値

OracleAQAgentオブジェクト。

例外

ArgumentNullException - conまたはlistenConsumersパラメータがnullです。

InvalidOperationException - 接続がオープンされていません。

ArgumentException - waitTimeが-1未満です。

備考

Listenは、いずれかのキューでコンシューマがメッセージを使用できるようになるまで複数のキューを監視する必要がある場合に便利です。OracleAQAgentオブジェクトのNameプロパティはコンシューマの名前を表し、OracleAQAgentオブジェクトのAddressプロパティはキューの名前を表します。

waitTimeが-1の場合、待機時間は無限です。

関連項目:

OracleAQQueueプロパティ

OracleAQQueueプロパティを、表12-25にリストします。

表12-25 OracleAQQueueプロパティ

プロパティ	説明
Connection	キューに関連付けられた`OracleConnection`オブジェクトを指定します。
DequeueOptions	キューからメッセージをデキューする際に使用するデキュー・オプションを指定します。
EnqueueOptions	キューにメッセージをエンキューするために使用されるエンキュー・オプションを指定します。
MessageType	このキューに関連付けられたキュー表のタイプを指定します。
名前	キューの名前を戻します。
Notification	`MessageAvailable`イベントを使用して登録する通知の様々な通知オプションを指定します。
NotificationConsumers	キューの受信メッセージについて非同期に通知を受ける、複数コンシューマ・キューのコンシューマの配列を指定します。
UdtTypeName	`MessageType`が`OracleAQMessageType.UDT`の場合にキューおよび対応するキュー表のベースとなるタイプ名を指定します。

関連項目:

Connection

このプロパティは、キューに関連付けられたOracleConnectionオブジェクトを指定します。

宣言

// C#
public OracleConnection Connection {get; set;}

プロパティ値

キューに関連付けられた接続を示すOracleConnectionオブジェクト。

例外

ObjectDisposedException - オブジェクトはすでに処理されています。

備考

この接続は、EnqueueやDequeueなどのメソッドをコールする前にオープンしておく必要があります。

関連項目:

DequeueOptions

このインスタンス・プロパティは、キューからメッセージをデキューする際に使用するデキュー・オプションを指定します。

宣言

// C#
public OracleAQDequeueOptions DequeueOptions {get; set}

プロパティ値

OracleAQDequeueOptionsオブジェクト。

例外

ObjectDisposedException - オブジェクトはすでに処理されています。

備考

デフォルト値は、デフォルトのプロパティ値を指定したOracleAQDequeueOptionsオブジェクトです。このプロパティをnullに設定すると、すべてのデキュー・オプションがデフォルト値にリセットされます。

関連項目:

EnqueueOptions

このインスタンス・プロパティは、キューにメッセージをエンキューするために使用されるエンキュー・オプションを指定します。

宣言

// C#
public OracleAQEnqueueOptions EnqueueOptions {get; set}

プロパティ値

OracleAQEnqueueOptionsオブジェクト。

例外

ObjectDisposedException - オブジェクトはすでに処理されています。

備考

デフォルト値は、デフォルトのプロパティ値を指定したOracleAQEnqueueOptionsオブジェクトです。このプロパティをnullに設定すると、すべてのエンキュー・オプションがデフォルト値にリセットされます。

関連項目:

MessageType

このインスタンス・プロパティは、このキューに関連付けられたキュー表のタイプを指定します。

宣言

// C#
public OracleAQMessageType MessageType {get; set;}

プロパティ値

OracleAQMessageTypeの列挙値。

例外

ArgumentOutOfRangeException - 指定したタイプ値が無効です。

ObjectDisposedException - オブジェクトはすでに処理されています。

備考

MessageTypeプロパティは、キューに対してエンキューまたはデキューされるメッセージ・ペイロードのタイプも決定します。MessageTypeに応じて様々なペイロードをエンキューできます。

表12-26に、様々なメッセージ・タイプで使用できるペイロード・タイプを示します。

表12-26 メッセージのタイプとペイロード

OracleAQQueue.MessageType	エンキュー可能なOracleAQMessage.Payloadタイプ
`OracleAQMessageType.Raw`	`OracleBinary`、`byte[]`
`OracleAQMessageType.Xml`	`OracleXmlType`、`XmlReader`、`String`(整形式のXML。整形式でない場合は例外が発生)
`OracleAQMessageType.UDT`	`UDT`カスタム・オブジェクト

表12-27に、デキューされたメッセージのペイロード・タイプを示します。

表12-27 デキューされたメッセージのペイロード・タイプ

OracleAQQueue.MessageType	DequeueOptions.ProviderSpecificType	デキューされたメッセージのOracleAQMessage.Payload
`OracleAQMessageType.Xml`	`true`	`OracleXmlType`
`OracleAQMessageType.Xml`	`false`	`XmlReader`
`OracleAQMessageType.Raw`	`true`	`OracleBinary`
`OracleAQMessageType.Raw`	`false`	`Byte[]`
`OracleAQMessageType.UDT`	N/A	`UDT`カスタム・オブジェクト

関連項目:

名前

このインスタンス・プロパティは、キューの名前を戻します。

宣言

// C#
public string Name {get;}

プロパティ値

キューの名前を示すstring。

例外

ObjectDisposedException - オブジェクトはすでに処理されています。

関連項目:

通知

このインスタンス・プロパティは、MessageAvailableイベントを使用して登録する通知の様々な通知オプションを指定します。

宣言

// C#
public OracleNotificationRequest Notification {get;}

プロパティ値

OracleNotificationRequestオブジェクトを指定します。このオブジェクトのプロパティを変更すると、通知動作を変更できます。

備考

このプロパティを使用すると、様々な通知オプションを変更できます。通知オプションは、MessageAvailableイベントへの登録の前に変更する必要があります。このプロパティの変更が再度可能になるのは、MessageAvailableイベントへの登録を解除した後です。

関連項目:

NotificationConsumers

このインスタンス・プロパティは、キューで受信したメッセージについて非同期に通知を受ける、複数コンシューマ・キューのコンシューマの配列を指定します。

宣言

// C#
public string[] NotificationConsumers {get; set;}

プロパティ値

通知配信の対象となるコンシューマ名文字列の配列を指定します。

例外

ObjectDisposedException - オブジェクトはすでに処理されています。

InvalidOperationException - MessageAvailable登録が有効です。

備考

コンシューマ名は大文字で指定する必要があります。この機能は、大文字の名前のキューのみに対応しています。

コンシューマのリストはMessageAvailableイベントで使用されます。イベントに登録する前にリストを設定しておく必要があります。このプロパティは、MessageAvailableイベントへの登録後は変更できません。変更が再度可能になるのは、MessageAvailableイベントへの登録を解除した後です。

関連項目:

UdtTypeName

このインスタンス・プロパティは、MessageTypeがOracleAQMessageType.UDTの場合にキューおよび対応するキュー表のベースとなるタイプ名を指定します。

宣言

// C#
public string UdtTypeName {get; set;}

プロパティ値

MessageTypeがOracleAQMessageType.UDTの場合のOracleユーザー定義タイプ名を指定します。

例外

ObjectDisposedException - オブジェクトはすでに処理されています。

備考

UdtTypeNameプロパティは、ペイロードのユーザー定義タイプ名に対応しています。ペイロードがユーザー定義タイプの場合、このプロパティを必ず指定する必要があります。他のペイロード・タイプについては、設定は不要です。

関連項目:

OracleAQQueueパブリック・メソッド

OracleAQQueueパブリック・メソッドを、表12-28にリストします。

表12-28 OracleAQQueueパブリック・メソッド

パブリック・メソッド	説明
Dequeue	キューからメッセージをデキューします(オーバーロード)。
DequeueArray	キューから複数のメッセージをデキューします(オーバーロード)。
Dispose	オブジェクトにより割り当てられたリソースまたはメモリーを解除します
Enqueue	キューにメッセージをエンキューします(オーバーロード)。
EnqueueArray	キューに複数のメッセージをエンキューします(オーバーロード)。
Listen	`listenConsumers`に代わってキューのメッセージをリスニングします(オーバーロード)。

関連項目:

デキュー

Dequeueメソッドは、キューからメッセージをデキューします。

オーバーロード・リスト

Dequeue()

このインスタンス・メソッドは、インスタンスのDequeueOptionsを使用してキューからメッセージをデキューします。
Dequeue(OracleAQDequeueOptions)

このインスタンス・メソッドは、指定されたデキュー・オプションを使用してキューからメッセージをデキューします。

関連項目:

Dequeue()

このインスタンス・メソッドは、インスタンスのDequeueOptionsを使用してキューからメッセージをデキューするために使用します。

宣言

// C#
public OracleAQMessage Dequeue();

戻り値

デキューされたメッセージを表すOracleAQMessageインスタンス。

例外

InvalidOperationException - 接続がオープンされていません。

ObjectDisposedException - オブジェクトはすでに処理されています。

OracleException: タイムアウトした場合、「ORA-25228: queue_nameからメッセージをデキュー中に、タイムアウトまたはフェッチ終了になりました。」というメッセージとともに例外がスローされます。DequeueOptions.Waitが-1以外の値に設定されていると、タイムアウトが発生することがあります。

備考

このファンクションをコールする前にMessageTypeプロパティを適切に設定しておく必要があります。MessageTypeがOracleAQMessageType.UDTの場合は、UdtTypeNameプロパティも設定する必要があります。

デキューされたバッファ・メッセージのMessageId値は常にnullです。

関連項目:

Dequeue(OracleAQDequeueOptions)

このインスタンス・メソッドは、指定されたデキュー・オプションを使用してキューからメッセージをデキューします。

宣言

// C#
public OracleAQMessage Dequeue(OracleAQDequeueOptions dequeueOptions);

パラメータ

dequeueOptions

OracleAQDequeueOptionsオブジェクト。

戻り値

デキューされたメッセージを表すOracleAQMessageインスタンス。

例外

InvalidOperationException - 接続がオープンされていません。

ObjectDisposedException - オブジェクトはすでに処理されています。

備考

指定したdequeueOptionsオブジェクトがnullの場合は、デキュー・オプションのデフォルト値が使用されます。この操作では、キュー・オブジェクトのDequeueOptionsプロパティは無視されます。

このメソッドをコールしても、キューのDequeueOptionsプロパティは変更されません。

デキューされたバッファ・メッセージのMessageId値は常にnullです。

関連項目:

DequeueArray

DequeueArrayメソッドは、キューから複数のメッセージをデキューします。

オーバーロード・リスト

DequeueArray(int)

このインスタンス・メソッドは、インスタンスのDequeueOptionsを使用してキューから複数のメッセージをデキューします。
DequeueArray(int, OracleAQDequeueOptions)

このインスタンス・メソッドは、指定されたデキュー・オプションを使用してキューから複数のメッセージをデキューします。

関連項目:

DequeueArray(int)

このインスタンス・メソッドは、インスタンスのDequeueOptionsを使用してキューから複数のメッセージをデキューします。

宣言

// C#
public OracleAQMessage[] DequeueArray(int dequeueCount);

パラメータ

dequeueCount

デキューするメッセージの数を指定するinteger。

戻り値

デキューされたメッセージを表すOracleAQMessageインスタンスの配列。

例外

ArgumentOutOfRangeException - dequeueCountが0以下です。

InvalidOperationException - 接続がオープンされていません。

ObjectDisposedException - オブジェクトはすでに処理されています。

OracleException: タイムアウトした場合、「ORA-25228: queue_nameからメッセージをデキュー中に、タイムアウトまたはフェッチ終了になりました。」というメッセージとともに例外がスローされます。DequeueOptions.Waitが-1以外の値に設定されていると、タイムアウトが発生することがあります。

備考

このメソッドは、Oracle Database 10g以上のリリースでサポートされます。

戻される配列のサイズは、dequeueCountより小さいことがあります。キューに存在するメッセージの実際の数によって異なります。

データベースのバージョンがOracle Database 11gリリース2 (11.2.0.4)以前の場合、DequeueArrayを使用して取得される永続OracleAQMessageオブジェクトのMessageIdプロパティは、常にnullです。

デキューされたバッファ・メッセージのMessageId値は、データベースのバージョンに関係なく、常にnullです。

関連項目:

DequeueArray(int, OracleAQDequeueOptions)

このインスタンス・メソッドは、指定されたデキュー・オプションを使用してキューから複数のメッセージをデキューします。

宣言

// C#
public OracleAQMessage[] DequeueArray(int dequeueCount, OracleAQDequeueOptions dequeueOptions);

パラメータ

dequeueCount

デキューするメッセージの数を指定するinteger。
dequeueOptions

OracleAQDequeueOptionsオブジェクト。

戻り値

デキューされたメッセージを表すOracleAQMessageインスタンスの配列。

例外

ArgumentOutOfRangeException - dequeueCountが0以下です。

InvalidOperationException - 接続がオープンされていません。

ObjectDisposedException - オブジェクトはすでに処理されています。

備考

このメソッドは、Oracle Database 10gリリース1(10.1)以上のリリースでサポートされます。このメソッドをコールしても、キューのDequeueOptionsプロパティは変更されません。

戻される配列のサイズは、dequeueCountより小さいことがあります。キューに存在するメッセージの実際の数によって異なります。

デキューされたバッファ・メッセージのMessageId値は、データベースのバージョンに関係なく、常にnullです。

関連項目:

Dispose

このメソッドでは、オブジェクトにより割り当てられたリソースまたはメモリーを解除します。

宣言

// C#
public void Dispose();

実装

IDisposable。

関連項目:

エンキュー

Enqueueインスタンス・メソッドは、キューにメッセージをエンキューします。

オーバーロード・リスト

Enqueue(OracleAQMessage)

このインスタンス・メソッドは、インスタンスのEnqueueOptionsを使用してキューにメッセージをエンキューします。
Enqueue(OracleAQMessage, OracleAQEnqueueOptions)

このインスタンス・メソッドは、指定されたエンキュー・オプションを使用してキューにメッセージをエンキューします。

関連項目:

Enqueue(OracleAQMessage)

このインスタンス・メソッドは、インスタンスのEnqueueOptionsを使用してキューにメッセージをエンキューします。

宣言

// C#
public void Enqueue(OracleAQMessage message);

パラメータ

message

OracleAQMessageオブジェクト。

例外

ObjectDisposedException - オブジェクトはすでに処理されています。

InvalidOperationException - 接続がオープンされていません。

ArgumentNullException - メッセージ・パラメータがnullです。

ArgumentException - メッセージ・ペイロードはOracleXmlTypeで、OracleXmlTypeの作成に使用される接続はキューの接続とは異なります。

備考

Enqueueのコールが完了すると、エンキューされたメッセージのMessageIdに値が移入されます。エンキューされたバッファ・メッセージは、常にnullのMessageId値を持ちます。

関連項目:

Enqueue(OracleAQMessage, OracleAQEnqueueOptions)

このインスタンス・メソッドは、指定されたエンキュー・オプションを使用してキューにメッセージをエンキューします。

宣言

// C#
public void Enqueue(OracleAQMessage message, OracleAQEnqueueOptions enqueueOptions);

パラメータ

message

OracleAQMessageオブジェクト。
enqueueOptions

OracleAQEnqueueOptionsオブジェクト。

例外

ObjectDisposedException - オブジェクトはすでに処理されています。

InvalidOperationException - 接続がオープンされていません。

ArgumentNullException - メッセージ・パラメータがnullです。

ArgumentException - メッセージ・ペイロードはOracleXmlTypeで、OracleXmlTypeの作成に使用される接続はキューの接続とは異なります。

備考

指定したenqueueOptionsオブジェクトがnullの場合は、エンキュー・オプションのデフォルト値が使用されます。この操作では、キュー・オブジェクトのEnqueueOptionsプロパティは無視されます。

Enqueueのコールが完了すると、エンキューされたメッセージのMessageIdに値が移入されます。エンキューされたバッファ・メッセージは、常にnullのMessageId値を持ちます。このメソッドをコールしても、キューのEnqueueOptionsプロパティは変更されません。

関連項目:

EnqueueArray

EnqueueArrayインスタンス・メソッドは、キューに複数のメッセージをエンキューします。

オーバーロード・リスト

EnqueueArray(OracleAQMessage[ ])

このインスタンス・メソッドは、インスタンスのEnqueueOptionsを使用してキューに複数のメッセージをエンキューします。
EnqueueArray(OracleAQMessage[ ], OracleAQEnqueueOptions)

このインスタンス・メソッドは、指定されたエンキュー・オプションを使用してキューに複数のメッセージをエンキューします。

関連項目:

EnqueueArray(OracleAQMessage[ ])

このインスタンス・メソッドは、インスタンスのEnqueueOptionsを使用してキューに複数のメッセージをエンキューします。

宣言

// C#
public int EnqueueArray(OracleAQMessage[] messages);

パラメータ

messages

OracleAQMessageオブジェクトの配列。

戻り値

実際にエンキューされたメッセージの数を表すinteger。

例外

ArgumentNullException - メッセージ・パラメータがnullです。

ArgumentException - 少なくとも1つのOracleAQMessage[]要素がnullであるか、少なくとも1つのOracleAQMessage[]要素にOracleXmlTypeのペイロードがあります。このペイロードは、キューの接続とは異なる接続を使用して作成されます。

InvalidOperationException - OracleAQMessage配列が空か、接続がオープンされていません。

ObjectDisposedException - オブジェクトはすでに処理されています。

備考

このメソッドはOracle Database 10g以上のリリースでサポートされます。Enqueueのコールが完了すると、エンキューされたメッセージのMessageIdプロパティに値が移入されます。エンキューされたバッファ・メッセージは、常にnullのMessageId値を持ちます。

関連項目:

EnqueueArray(OracleAQMessage[ ], OracleAQEnqueueOptions)

このインスタンス・メソッドは、指定されたエンキュー・オプションを使用してキューに複数のメッセージをエンキューします。

宣言

// C#
public int EnqueueArray(OracleAQMessage[] messages, OracleAQEnqueueOptions
  enqueueOptions);

パラメータ

messages

OracleAQMessageオブジェクトの配列。
enqueueOptions

OracleAQEnqueueOptionsオブジェクト。

戻り値

実際にエンキューされたメッセージの数を表すinteger。

例外

ArgumentNullException - メッセージ・パラメータがnullです。

InvalidOperationException - OracleAQMessage配列が空か、接続がオープンされていません。

ObjectDisposedException - オブジェクトはすでに処理されています。

備考

このメソッドはOracle Database 10g以上のリリースでサポートされます。Enqueueのコールが完了すると、エンキューされたメッセージのMessageIdプロパティに値が移入されます。エンキューされたバッファ・メッセージは、常にnullのMessageId値を持ちます。このメソッドをコールしても、キューのEnqueueOptionsプロパティは変更されません。

関連項目:

リスニング

Listenメソッドは、listenConsumersに代わってキューのメッセージをリスニングします。

オーバーロード・リスト

Listen(string[])

このメソッドは、listenConsumersに代わってキューのメッセージをリスニングします。
Listen (string[], int)

このメソッドは、指定された時間にわたり、listenConsumersに代わってメッセージをリスニングします。

関連項目:

Listen(string[])

このメソッドは、listenConsumersに代わってキューのメッセージをリスニングします。

宣言

// C#
public string Listen(string[] listenConsumers);

パラメータ

listenConsumers

このキューでリスニングするコンシューマの配列。単一コンシューマ・キューの場合は、このパラメータをnullにする必要があります。

戻り値

string

例外

InvalidOperationException - 接続がオープンされていません。

ObjectDisposedException - オブジェクトはすでに処理されています。

備考

このコールは、listenConsumers配列内のコンシューマがメッセージを消費できるようになるまでコール元のスレッドをブロックします。このコールは、消費可能になったメッセージのコンシューマ名を表すstringを戻します。

Listenは、listenConsumersに指定された名前のコンシューマがキュー内のメッセージを使用できるようになるまで待つ必要がある場合に便利です。

例

次の例は、Listenメソッドの使用方法を示すものです。この例の最初の部分では、データベース・ユーザーSCOTTの必要なデータベース設定を実行しています。この例の2番目の部分は、メッセージがエンキューされるまでのスレッドのリスニング方法および待機方法を示しています。

-- Part I: Database setup required for this demo
 
------------------------------------------------------------------
-- SQL to grant appropriate privilege to database user, SCOTT
------------------------------------------------------------------
SQL> ALTER USER SCOTT ACCOUNT UNLOCK IDENTIFIED BY Pwd4Sct;
User altered.
GRANT ALL ON DBMS_AQADM TO scott;
 
------------------------------------------------------------------
-- PLSQL to create queue-table and queue and start queue for SCOTT
------------------------------------------------------------------
BEGIN
  DBMS_AQADM.CREATE_QUEUE_TABLE(
    queue_table=>'scott.test_q_tab', 
    queue_payload_type=>'RAW', 
    multiple_consumers=>FALSE);
 
  DBMS_AQADM.CREATE_QUEUE(
    queue_name=>'scott.test_q', 
    queue_table=>'scott.test_q_tab');
 
  DBMS_AQADM.START_QUEUE(queue_name=>'scott.test_q');
END;
/
 
------------------------------------------------------------------
-- PLSQL to stop queue and drop queue & queue-table from SCOTT
------------------------------------------------------------------
BEGIN
  DBMS_AQADM.STOP_QUEUE('scott.test_q');
 
  DBMS_AQADM.DROP_QUEUE(
    queue_name => 'scott.test_q', 
    auto_commit => TRUE);
 
  DBMS_AQADM.DROP_QUEUE_TABLE(
    queue_table => 'scott.test_q_tab',
    force => FALSE, 
    auto_commit => TRUE);
END;
/
-- End of Part I, database setup.

//Part II: Demonstrates using the Listen method
//C#
using System;
using System.Text;
using Oracle.DataAccess.Client;
using Oracle.DataAccess.Types;
using System.Threading;
 
namespace ODPSample
{
  /// <summary>
  /// Demonstrates how a thread can listen and wait until a message is enqueued.
  /// Once a message is enqueued, the listening thread returns from the 
  /// blocked Listen() method invocation and dequeues the message.
  /// </summary>
  class EnqueueDequeue
  {
    static bool s_bListenReturned = false;
 
    static void Main(string[] args)
    {
      // Create connection
      string constr = "user id=scott;password=Pwd4Sct;data source=oracle";
      OracleConnection con = new OracleConnection(constr);
 
      // Create queue
      OracleAQQueue queue = new OracleAQQueue("scott.test_q", con);
 
      try
      {
        // Open connection
        con.Open();
 
        // Set message type for the queue
        queue.MessageType = OracleAQMessageType.Raw;
 
        // Spawning a thread which will listen for a message
        ThreadStart ts = new ThreadStart(TestListen);
        Thread t = new Thread(ts);
        t.Start();
 
        System.Threading.Thread.Sleep(2000);
 
        // Begin transaction for enqueue
        OracleTransaction txn = con.BeginTransaction();
 
        // Prepare message and RAW payload
        OracleAQMessage enqMsg = new OracleAQMessage();
        byte[] bytePayload = { 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 };
        enqMsg.Payload = bytePayload;
 
        // Prepare to Enqueue
        queue.EnqueueOptions.Visibility = OracleAQVisibilityMode.OnCommit;
 
        Console.WriteLine("[Main Thread]   Enqueuing a message...");
        Console.WriteLine("[Main Thread]   Enqueued Message Payload      : "
          + ByteArrayToString(enqMsg.Payload as byte[]));
        Console.WriteLine();
 
        // Enqueue message
        queue.Enqueue(enqMsg);
 
        // Enqueue transaction commit
        txn.Commit();
 
        // Loop till Listen returns
        while (!s_bListenReturned)
          System.Threading.Thread.Sleep(1000);
      }
      catch (Exception e)
      {
        Console.WriteLine("Error: {0}", e.Message);
      }
      finally
      {
        // Close/Dispose objects
        queue.Dispose();
        con.Close();
        con.Dispose();
      }
    }
 
    static void TestListen()
    {
      // Create connection
      string constr = "user id=scott;password=Pwd4Sct;data source=oracle";
      OracleConnection conListen = new OracleConnection(constr);
 
      // Create queue
      OracleAQQueue queueListen = new OracleAQQueue("scott.test_q", conListen);
 
      try
      {
          // Open the connection for Listen thread.
          // Connection blocked on Listen thread can not be used for other DB 
          // operations
          conListen.Open();
 
          // Set message type for the queue
          queueListen.MessageType = OracleAQMessageType.Raw;
 
        // Listen
        queueListen.Listen(null);
 
        Console.WriteLine("[Listen Thread] Listen returned... Dequeuing...");
 
        // Begin txn for Dequeue
        OracleTransaction txn = conListen.BeginTransaction();
 
        // Prepare to Dequeue
        queueListen.DequeueOptions.Visibility = OracleAQVisibilityMode.OnCommit;
        queueListen.DequeueOptions.Wait = 10;
 
        // Dequeue message
        OracleAQMessage deqMsg = queueListen.Dequeue();
        Console.WriteLine("[Listen Thread] Dequeued Message Payload      : "
          + ByteArrayToString(deqMsg.Payload as byte[]));
 
        // Dequeue txn commit
        txn.Commit();
 
        // Allow the main thread to exit
        s_bListenReturned = true;
      }
      catch (Exception e)
      {
        Console.WriteLine("Error: {0}", e.Message);
      }
      finally
      {
        // Close/Dispose objects
        queueListen.Dispose();
        conListen.Close();
        conListen.Dispose();
      }
    }
 
    // Function to convert byte[] to string
    static private string ByteArrayToString(byte[] byteArray)
    {
      StringBuilder sb = new StringBuilder();
      for (int n = 0; n < byteArray.Length; n++)
      {
        sb.Append((int.Parse(byteArray[n].ToString())).ToString("X"));
      }
      return sb.ToString();
    }
  }
}

関連項目:

Listen (string[], int)

このメソッドは、指定された時間にわたり、listenConsumersに代わってメッセージをリスニングします。

宣言

// C#
public string Listen(string[] listenConsumers, int waitTime);

パラメータ

listenConsumers

このキューでリスニングするコンシューマの配列。
waitTime

待機時間(秒)。

戻り値

string

例外

InvalidOperationException - 接続がオープンされていません。

ArgumentException - waitTimeが-1未満です。

ObjectDisposedException - オブジェクトはすでに処理されています。

備考

Listenは、listenConsumersに指定された名前のコンシューマがキュー内のメッセージを使用できるようになるまで待つ必要がある場合に便利です。

このコールは、listenConsumers配列内のコンシューマがメッセージを消費できるようになるまでコール元のスレッドをブロックします。このコールは、消費可能になったメッセージのコンシューマ名を表すstringを戻します。タイムアウトが発生した場合、このメソッドはnullを戻します。

単一コンシューマ・キューの場合は、listenConsumersパラメータをnullにする必要があります。そのような場合は空の文字列が戻されます。

waitTimeが-1の場合、待機時間は無限です。

関連項目:

OracleAQQueueイベント

OracleAQQueueイベントを、表12-29にリストします。

表12-29 OracleAQQueueイベント

イベント名	説明
MessageAvailable Event	`NotificationConsumers`がキュー内のメッセージを使用できるようになると通知します。

関連項目:

MessageAvailable Event

このイベントは、NotificationConsumersがキュー内のメッセージを使用できるようになると通知されます。

宣言

// C#
public event OracleAQMessageAvailableEventHandler MessageAvailable;

イベント・データ

このイベント・ハンドラは、OracleAQMessageAvailableEventArgsオブジェクトを受信します。

例外

InvalidOperationException - 接続がオープンされていません。

備考

非同期通知は、8.1以上のデータベース互換性レベルで作成されたすべてのキュー表でサポートされます。

メッセージの可用性に関する通知を受信するために、クライアントはOracleAQMessageAvailableEventHandlerデリゲートを作成してこのイベントをリスニングする必要があります。デリゲートをこのイベントに追加するのは、必ずNotificationConsumersおよびNotificationプロパティを設定した後にしてください。

通知の登録が行われるのは、最初のデリゲートがイベントに追加された後です。最後のデリゲートがイベントから削除されると、通知の登録は解除されます。OracleAQQueueオブジェクトに設定された通知は、オブジェクトが破棄されると自動的に取り消されます。

Oracle Data Provider for .NETは、通知をリスニングするためのポートをオープンします。HAイベント、ロード・バランシング、データベース変更通知の各機能も同じポートを共有します。このポートは、アプリケーション構成ファイルまたはWeb構成ファイルにデータベース通知ポートを設定することで、一元的に構成できます。次のサンプル・コードでは、ポート番号1200を指定しています。

<configuration>
  <oracle.dataaccess.client>
    <settings>
      <add name="DbNotificationPort" value="1200"/>
    </settings>
  </oracle.dataaccess.client>
</configuration>

構成ファイルが存在しないか、データベース通知ポートが指定されていない場合、ODP.NETは有効なポート番号をランダムに使用します。構成ファイルにデータベース通知ポートの値として-1を指定した場合も、ランダムなポート番号が要求されます。

ODP.NETと同じアプリケーション・ドメイン内で実行される通知リスナーは、指定のポート番号を使用してデータベースからの通知をリスニングします。通知リスナーが作成されるのは、アプリケーションがOracleAQQueue.MessageAvailableイベントに登録されたときです。1つの通知リスナーがすべての通知タイプをリスニングできます。通知リスナーは、アプリケーション・ドメインごとに1つだけ作成されます。

例

次の例は、アプリケーション通知を示しています。この例の最初の部分では、データベース・ユーザーSCOTTの必要なデータベース設定を実行しています。この例の2番目の部分は、キューのメッセージが使用可能になったときのアプリケーションへの通知方法を示しています。

-- Part I: Database setup required for this demo
 
------------------------------------------------------------------
-- SQL to grant appropriate privilege to database user, SCOTT
------------------------------------------------------------------
SQL> ALTER USER SCOTT ACCOUNT UNLOCK IDENTIFIED BY Pwd4Sct;
User altered.
SQL> GRANT ALL ON DBMS_AQADM TO scott;
 
------------------------------------------------------------------
-- PLSQL to create queue-table and queue and start queue for SCOTT
------------------------------------------------------------------
BEGIN
  DBMS_AQADM.CREATE_QUEUE_TABLE(
    queue_table=>'scott.test_q_tab', 
    queue_payload_type=>'RAW', 
    multiple_consumers=>FALSE);
 
  DBMS_AQADM.CREATE_QUEUE(
    queue_name=>'scott.test_q', 
    queue_table=>'scott.test_q_tab');
 
  DBMS_AQADM.START_QUEUE(queue_name=>'scott.test_q');
END;
/
 
------------------------------------------------------------------
-- PLSQL to stop queue and drop queue & queue-table from SCOTT
------------------------------------------------------------------
BEGIN
  DBMS_AQADM.STOP_QUEUE('scott.test_q');
 
  DBMS_AQADM.DROP_QUEUE(
    queue_name => 'scott.test_q', 
    auto_commit => TRUE);
 
  DBMS_AQADM.DROP_QUEUE_TABLE(
    queue_table => 'scott.test_q_tab',
    force => FALSE, 
    auto_commit => TRUE);
END;
/
-- End of Part I, database setup.

//Part II: Demonstrates application notification
//C#
using System;
using System.Text;
using Oracle.DataAccess.Client;
using Oracle.DataAccess.Types;
 
namespace ODPSample
{
  /// <summary>
  /// Demonstrates how the application can be notified when a message is 
  /// available in a queue.
  /// </summary>
  class Notification
  {
    static bool isNotified = false;
 
    static void Main(string[] args)
    {
      // Create connection
      string constr = "user id=scott;password=Pwd4Sct;data source=oracle";
      OracleConnection con = new OracleConnection(constr);
 
      // Create queue
      OracleAQQueue queue = new OracleAQQueue("scott.test_q", con);
 
      try
      {
        // Open connection
        con.Open();
 
        // Set message type for the queue
        queue.MessageType = OracleAQMessageType.Raw;
 
        // Add the event handler to handle the notification. The 
        // MsgReceived method will be invoked when a message is enqueued
        queue.MessageAvailable +=
          new OracleAQMessageAvailableEventHandler(Notification.MsgReceived);
 
        Console.WriteLine("Notification registered...");
 
        // Begin txn for enqueue
        OracleTransaction txn = con.BeginTransaction();
 
        Console.WriteLine("Now enqueuing message...");
 
        // Prepare message and RAW payload
        OracleAQMessage enqMsg = new OracleAQMessage();
        byte[] bytePayload = { 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 };
        enqMsg.Payload = bytePayload;
 
        // Prepare to Enqueue
        queue.EnqueueOptions.Visibility = OracleAQVisibilityMode.OnCommit;
 
        // Enqueue message
        queue.Enqueue(enqMsg);
 
        Console.WriteLine("Enqueued Message Payload      : "
          + ByteArrayToString(enqMsg.Payload as byte[]));
        Console.WriteLine("MessageId of Enqueued Message : "
          + ByteArrayToString(enqMsg.MessageId));
        Console.WriteLine();
 
        // Enqueue txn commit
        txn.Commit();
 
        // Loop while waiting for notification
        while (isNotified == false)
        {
          System.Threading.Thread.Sleep(2000);
        }
      }
      catch (Exception e)
      {
        Console.WriteLine("Error: {0}", e.Message);
      }
      finally
      {
        // Close/Dispose objects
        queue.Dispose();
        con.Close();
        con.Dispose();
      }
    }
 
    static void MsgReceived(object src, OracleAQMessageAvailableEventArgs arg)
    {
      try
      {
        Console.WriteLine("Notification Received...");
        Console.WriteLine("QueueName : {0}", arg.QueueName);
        Console.WriteLine("Notification Type : {0}", arg.NotificationType);
                
                //following type-cast to "byte[]" is required only for .NET 1.x
        byte[] notifiedMsgId = (byte[]) arg.MessageId[0];
        Console.WriteLine("MessageId of Notified Message : "
          + ByteArrayToString(notifiedMsgId));
        isNotified = true;
      }
      catch (Exception e)
      {
        Console.WriteLine("Error: {0}", e.Message);
      }
    }
        
        // Function to convert byte[] to string
    static private string ByteArrayToString(byte[] byteArray)
    {
      StringBuilder sb = new StringBuilder();
      for (int n = 0; n < byteArray.Length; n++)
      {
        sb.Append((int.Parse(byteArray[n].ToString())).ToString("X"));
      }
      return sb.ToString();
    }
  }
}

関連項目: