Oracle® Data Provider for .NET開発者ガイド ODAC 12c リリース4 (12.1.0.2) for Microsoft Windows E72575-01 |
|
前 |
次 |
OracleAQQueue
オブジェクトは、キューを表します。
クラスの継承
System.Object
OracleAQQueue
宣言
// C# public class OracleAQQueue : IDisposable
要件
プロバイダ | ODP.NET管理対象外ドライバ |
アセンブリ | Oracle.DataAccess.dll |
ネームスペース | Oracle.DataAccess.Client |
.NET Framework | 3.5, 4.0, 4.5, 4.6 |
スレッド安全性
パブリック静的メソッドはスレッドセーフですが、インスタンス・メソッドではスレッド安全性は保証されません。
備考
キューとはメッセージのリポジトリであり、ユーザー・キューと例外キューのいずれかです。ユーザー・キューは通常のメッセージ処理に使用されます。なんらかの理由でメッセージを取り出して処理することができない場合、そのメッセージはユーザー・キューから例外キューに移動されます。
OracleAQQueue
メンバーを、次の各表に示します。
OracleAQQueueコンストラクタ
OracleAQQueue
コンストラクタを、表12-20にリストします。
OracleAQQueue静的メソッド
OracleAQQueue
静的メソッドを、表12-21にリストします。
表12-21 OracleAQQueue静的メソッド
静的メソッド | 説明 |
---|---|
|
|
OracleAQQueueプロパティ
OracleAQQueue
プロパティを、表12-22にリストします。
表12-22 OracleAQQueueプロパティ
プロパティ | 説明 |
---|---|
|
キューに関連付けられた |
|
キューからメッセージをデキューする際に使用するデキュー・オプションを指定します。 |
|
キューにメッセージをエンキューするために使用されるエンキュー・オプションを指定します。 |
|
このキューに関連付けられたキュー表のタイプを指定します。 |
|
キューの名前を戻します。 |
|
|
|
キューの受信メッセージについて非同期に通知を受ける、複数コンシューマ・キューのコンシューマの配列を指定します。 |
|
|
OracleAQQueueパブリック・メソッド
OracleAQQueue
パブリック・メソッドを、表12-23にリストします。
表12-23 OracleAQQueueパブリック・メソッド
パブリック・メソッド | 説明 |
---|---|
|
キューからメッセージをデキューします(オーバーロード)。 |
|
キューから複数のメッセージをデキューします(オーバーロード)。 |
|
オブジェクトにより割り当てられたリソースまたはメモリーを解除します |
|
キューにメッセージをエンキューします(オーバーロード)。 |
|
キューに複数のメッセージをエンキューします(オーバーロード)。 |
|
|
OracleAQQueueイベント
OracleAQQueue
イベントを、表12-24にリストします。
OracleAQQueue
コンストラクタは、OracleAQQueue
クラスの新規インスタンスを作成します。
オーバーロード・リスト:
このコンストラクタは、キュー名を使用してキュー・オブジェクトを初期化します。
OracleAQQueue(string, OracleConnection)
このコンストラクタは、キュー名と接続を使用してキュー・オブジェクトを初期化します。キュー・オブジェクトの作成時に接続がオープンしている必要はありません。
OracleAQQueue(string, OracleConnection, OracleAQMessageType)
このコンストラクタは、キュー名、接続およびメッセージ・タイプの列挙を使用してキュー・オブジェクトを初期化します。
OracleAQQueue(string, OracleConnection, OracleAQMessageType, string)
このコンストラクタは、キュー名、接続、メッセージ・タイプの列挙およびUDTタイプ名を使用してキュー・オブジェクトを初期化します。
このコンストラクタは、キュー名を使用してキュー・オブジェクトを初期化します。
宣言
// C#
public OracleAQQueue(string name);
パラメータ
name
データベースで指定されているキューの名前。
例外
ArgumentNullException
- キュー名がnull
です。
ArgumentException
- キュー名が空です。
備考
OracleAQQueue
オブジェクトの作成操作では、データベースにキューが存在するかどうかはチェックされません。
このコンストラクタは、キュー名と接続を使用してキュー・オブジェクトを初期化します。キュー・オブジェクトの作成時に接続がオープンしている必要はありません。
宣言
// C# public OracleAQQueue(string name, OracleConnection con);
パラメータ
name
データベースで指定されているキューの名前。
con
キューに接続するOracleConnection
オブジェクト。
例外
ArgumentNullException
- 接続がnullか、キュー名がnull
です。
ArgumentException
- キュー名が空です。
備考
接続にはConnection
プロパティを使用してアクセスできます。この接続は、Enqueue
やDequeue
などの操作APIをコールする前にオープンしておく必要があります。
OracleAQQueue
オブジェクトの作成時には、データベースにキューが存在するかどうかはチェックされません。
このコンストラクタは、キュー名、接続およびメッセージ・タイプの列挙を使用してキュー・オブジェクトを初期化します。キュー・オブジェクトの作成時に接続がオープンしている必要はありません。
宣言
// C# public OracleAQQueue(string name, OracleConnection con, OracleAQMessageType messageType);
パラメータ
name
データベースで指定されているキューの名前。
con
キューへの接続に使用されるOracleConnection
オブジェクト。
messageType
このキューに対してエンキューまたはデキューされるメッセージのタイプを指定するOracleAQMessageType
の列挙。
例外
ArgumentNullException
- 接続がnull
か、キュー名がnull
です。
ArgumentException
- キュー名が空か、指定したメッセージ・タイプが無効です。
備考
OracleAQQueue
オブジェクトの作成時には、データベースにキューが存在するかどうかはチェックされません。
messageType
がUDTの場合、キュー・オブジェクトを使用する前にUdtTypeName
プロパティを設定しておく必要があります。udtTypeName
を指定することで、もう1つのコンストラクタ・オーバーロードを使用してキューを作成する方法もあります。
このコンストラクタは、キュー名、接続、メッセージ・タイプの列挙および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
静的メソッドを、表12-25にリストします。
表12-25 OracleAQQueue静的メソッド
静的メソッド | 説明 |
---|---|
|
|
Listen
メソッドは、OracleAQAgent
オブジェクトの配列に指定された1つ以上のコンシューマについて、1つ以上のキューでメッセージをリスニングします。
オーバーロード・リスト
Listen(OracleConnection, OracleAQAgent[ ])
この静的メソッドは、OracleAQAgent
オブジェクトの配列に指定された1つ以上のコンシューマについて、1つ以上のキューでメッセージをリスニングします。
Listen(OracleConnection, OracleAQAgent[ ], int)
この静的メソッドは、OracleAQAgent
オブジェクトの配列に指定された1つ以上のコンシューマについて、1つ以上のキューでメッセージをリスニングします。このメソッドには待機時間も指定します。
この静的メソッドは、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
オブジェクトを戻します。
この静的メソッドは、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
の場合、待機時間は無限です。
このコールは、リスト内のコンシューマがメッセージを消費できるようになるまでコール元のスレッドをブロックします。このコールは、デキュー可能になったメッセージのコンシューマとキューを指定するOracleAQAgent
オブジェクトを戻します。
OracleAQQueue
プロパティを、表12-26にリストします。
表12-26 OracleAQQueueプロパティ
プロパティ | 説明 |
---|---|
|
キューに関連付けられた |
|
キューからメッセージをデキューする際に使用するデキュー・オプションを指定します。 |
|
キューにメッセージをエンキューするために使用されるエンキュー・オプションを指定します。 |
|
このキューに関連付けられたキュー表のタイプを指定します。 |
|
キューの名前を戻します。 |
|
|
|
キューの受信メッセージについて非同期に通知を受ける、複数コンシューマ・キューのコンシューマの配列を指定します。 |
|
|
このプロパティは、キューに関連付けられたOracleConnection
オブジェクトを指定します。
宣言
// C# public OracleConnection Connection {get; set;}
プロパティ値
キューに関連付けられた接続を示すOracleConnection
オブジェクト。
例外
ObjectDisposedException
- オブジェクトはすでに処理されています。
備考
この接続は、Enqueue
やDequeue
などのメソッドをコールする前にオープンしておく必要があります。
このインスタンス・プロパティは、キューからメッセージをデキューする際に使用するデキュー・オプションを指定します。
宣言
// C# public OracleAQDequeueOptions DequeueOptions {get; set}
プロパティ値
OracleAQDequeueOptions
オブジェクト。
例外
ObjectDisposedException
- オブジェクトはすでに処理されています。
備考
デフォルト値は、デフォルトのプロパティ値を指定したOracleAQDequeueOptions
オブジェクトです。このプロパティをnull
に設定すると、すべてのデキュー・オプションがデフォルト値にリセットされます。
このインスタンス・プロパティは、キューにメッセージをエンキューするために使用されるエンキュー・オプションを指定します。
宣言
// C# public OracleAQEnqueueOptions EnqueueOptions {get; set}
プロパティ値
OracleAQEnqueueOptions
オブジェクト。
例外
ObjectDisposedException
- オブジェクトはすでに処理されています。
備考
デフォルト値は、デフォルトのプロパティ値を指定したOracleAQEnqueueOptions
オブジェクトです。このプロパティをnull
に設定すると、すべてのエンキュー・オプションがデフォルト値にリセットされます。
このインスタンス・プロパティは、このキューに関連付けられたキュー表のタイプを指定します。
宣言
// C# public OracleAQMessageType MessageType {get; set;}
プロパティ値
OracleAQMessageType
の列挙値。
例外
ArgumentOutOfRangeException
- 指定したタイプ値が無効です。
ObjectDisposedException
- オブジェクトはすでに処理されています。
備考
MessageType
プロパティは、キューに対してエンキューまたはデキューされるメッセージ・ペイロードのタイプも決定します。MessageType
に応じて様々なペイロードをエンキューできます。
表12-27に、様々なメッセージ・タイプで使用できるペイロード・タイプを示します。
表12-27 メッセージのタイプとペイロード
OracleAQQueue.MessageType | エンキュー可能なOracleAQMessage.Payloadタイプ |
---|---|
|
|
|
|
|
|
表12-28に、デキューされたメッセージのペイロード・タイプを示します。
表12-28 デキューされたメッセージのペイロード・タイプ
OracleAQQueue.MessageType | DequeueOptions.ProviderSpecificType | デキューされたメッセージのOracleAQMessage.Payload |
---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
N/A |
|
このインスタンス・プロパティは、キューの名前を戻します。
宣言
// C# public string Name {get;}
プロパティ値
キューの名前を示すstring
。
例外
ObjectDisposedException
- オブジェクトはすでに処理されています。
このインスタンス・プロパティは、MessageAvailable
イベントを使用して登録する通知の様々な通知オプションを指定します。
宣言
// C# public OracleNotificationRequest Notification {get;}
プロパティ値
OracleNotificationRequest
オブジェクトを指定します。このオブジェクトのプロパティを変更すると、通知動作を変更できます。
備考
このプロパティを使用すると、様々な通知オプションを変更できます。通知オプションは、MessageAvailable
イベントへの登録の前に変更する必要があります。このプロパティの変更が再度可能になるのは、MessageAvailable
イベントへの登録を解除した後です。
このインスタンス・プロパティは、キューで受信したメッセージについて非同期に通知を受ける、複数コンシューマ・キューのコンシューマの配列を指定します。
宣言
// C# public string[] NotificationConsumers {get; set;}
プロパティ値
通知配信の対象となるコンシューマ名文字列の配列を指定します。
例外
ObjectDisposedException
- オブジェクトはすでに処理されています。
InvalidOperationException
- MessageAvailable
登録が有効です。
備考
コンシューマ名は大文字で指定する必要があります。この機能は、大文字の名前のキューのみに対応しています。
コンシューマのリストはMessageAvailable
イベントで使用されます。イベントに登録する前にリストを設定しておく必要があります。このプロパティは、MessageAvailable
イベントへの登録後は変更できません。変更が再度可能になるのは、MessageAvailable
イベントへの登録を解除した後です。
このインスタンス・プロパティは、MessageType
がOracleAQMessageType.UDT
の場合にキューおよび対応するキュー表のベースとなるタイプ名を指定します。
宣言
// C# public string UdtTypeName {get; set;}
プロパティ値
MessageType
がOracleAQMessageType.UDT
の場合のOracleユーザー定義タイプ名を指定します。
例外
ObjectDisposedException
- オブジェクトはすでに処理されています。
備考
UdtTypeName
プロパティは、ペイロードのユーザー定義タイプ名に対応しています。ペイロードがユーザー定義タイプの場合、このプロパティを必ず指定する必要があります。他のペイロード・タイプについては、設定は不要です。
OracleAQQueue
パブリック・メソッドを、表12-29にリストします。
表12-29 OracleAQQueueパブリック・メソッド
パブリック・メソッド | 説明 |
---|---|
|
キューからメッセージをデキューします(オーバーロード)。 |
|
キューから複数のメッセージをデキューします(オーバーロード)。 |
|
オブジェクトにより割り当てられたリソースまたはメモリーを解除します |
|
キューにメッセージをエンキューします(オーバーロード)。 |
|
キューに複数のメッセージをエンキューします(オーバーロード)。 |
|
|
Dequeueメソッドは、キューからメッセージをデキューします。
オーバーロード・リスト
このインスタンス・メソッドは、インスタンスのDequeueOptions
を使用してキューからメッセージをデキューします。
Dequeue(OracleAQDequeueOptions)
このインスタンス・メソッドは、指定されたデキュー・オプションを使用してキューからメッセージをデキューします。
このインスタンス・メソッドは、インスタンスのDequeueOptions
を使用してキューからメッセージをデキューするために使用します。
宣言
// C# public OracleAQMessage Dequeue();
戻り値
デキューされたメッセージを表すOracleAQMessage
インスタンス。
例外
InvalidOperationException
- 接続がオープンされていません。
ObjectDisposedException
- オブジェクトはすでに処理されています。
OracleException
: タイムアウトした場合、「ORA-25228: queue_nameからメッセージをデキュー中に、タイムアウトまたはフェッチ終了になりました。」
というメッセージとともに例外がスローされます。DequeueOptions.Wait
が-1
以外の値に設定されていると、タイムアウトが発生することがあります。
備考
このファンクションをコールする前にMessageType
プロパティを適切に設定しておく必要があります。MessageType
がOracleAQMessageType.UDT
の場合は、UdtTypeName
プロパティも設定する必要があります。
デキューされたバッファ・メッセージのMessageId
値は常にnull
です。
このインスタンス・メソッドは、指定されたデキュー・オプションを使用してキューからメッセージをデキューします。
宣言
// C#
public OracleAQMessage Dequeue(OracleAQDequeueOptions dequeueOptions);
パラメータ
dequeueOptions
OracleAQDequeueOptions
オブジェクト。
戻り値
デキューされたメッセージを表すOracleAQMessage
インスタンス。
例外
InvalidOperationException
- 接続がオープンされていません。
ObjectDisposedException
- オブジェクトはすでに処理されています。
OracleException
: タイムアウトした場合、「ORA-25228: queue_nameからメッセージをデキュー中に、タイムアウトまたはフェッチ終了になりました。」
というメッセージとともに例外がスローされます。DequeueOptions.Wait
が-1
以外の値に設定されていると、タイムアウトが発生することがあります。
備考
指定したdequeueOptions
オブジェクトがnull
の場合は、デキュー・オプションのデフォルト値が使用されます。この操作では、キュー・オブジェクトのDequeueOptions
プロパティは無視されます。
このメソッドをコールしても、キューのDequeueOptions
プロパティは変更されません。
このファンクションをコールする前にMessageType
プロパティを適切に設定しておく必要があります。MessageType
がOracleAQMessageType.UDT
の場合は、UdtTypeName
プロパティも設定する必要があります。
デキューされたバッファ・メッセージのMessageId
値は常にnull
です。
DequeueArray
メソッドは、キューから複数のメッセージをデキューします。
オーバーロード・リスト
このインスタンス・メソッドは、インスタンスのDequeueOptions
を使用してキューから複数のメッセージをデキューします。
DequeueArray(int, OracleAQDequeueOptions)
このインスタンス・メソッドは、指定されたデキュー・オプションを使用してキューから複数のメッセージをデキューします。
このインスタンス・メソッドは、インスタンスの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以上のリリースでサポートされます。
このファンクションをコールする前にMessageType
プロパティを適切に設定しておく必要があります。MessageType
がOracleAQMessageType.UDT
の場合は、UdtTypeName
プロパティも設定する必要があります。
戻される配列のサイズは、dequeueCount
より小さいことがあります。キューに存在するメッセージの実際の数によって異なります。
データベースのバージョンがOracle Database ODAC 12cリリース4 (12.1.0.2)より前の場合は、DequeueArray
を使用して取得される永続OracleAQMessage
オブジェクトのMessageId
プロパティは常にnull
です。
デキューされたバッファ・メッセージのMessageId
値は、データベースのバージョンに関係なく、常にnull
です。
このインスタンス・メソッドは、指定されたデキュー・オプションを使用してキューから複数のメッセージをデキューします。
宣言
// C# public OracleAQMessage[] DequeueArray(int dequeueCount, OracleAQDequeueOptions dequeueOptions);
パラメータ
dequeueCount
デキューするメッセージの数を指定するinteger
。
dequeueOptions
OracleAQDequeueOptions
オブジェクト。
戻り値
デキューされたメッセージを表すOracleAQMessage
インスタンスの配列。
例外
ArgumentOutOfRangeException
- dequeueCount
が0以下です。
InvalidOperationException
- 接続がオープンされていません。
ObjectDisposedException
- オブジェクトはすでに処理されています。
OracleException
: タイムアウトした場合、「ORA-25228: queue_nameからメッセージをデキュー中に、タイムアウトまたはフェッチ終了になりました。」
というメッセージとともに例外がスローされます。DequeueOptions.Wait
が-1
以外の値に設定されていると、タイムアウトが発生することがあります。
備考
このメソッドは、Oracle Database 10gリリース1(10.1)以上のリリースでサポートされます。このメソッドをコールしても、キューのDequeueOptions
プロパティは変更されません。
指定したdequeueOptions
オブジェクトがnull
の場合は、デキュー・オプションのデフォルト値が使用されます。この操作では、キュー・オブジェクトのDequeueOptions
プロパティは無視されます。
このファンクションをコールする前にMessageType
プロパティを適切に設定しておく必要があります。MessageType
がOracleAQMessageType.UDT
の場合は、UdtTypeName
プロパティも設定する必要があります。
戻される配列のサイズは、dequeueCount
より小さいことがあります。キューに存在するメッセージの実際の数によって異なります。
データベースのバージョンがOracle Database ODAC 12cリリース4 (12.1.0.2)より前の場合は、DequeueArray
を使用して取得される永続OracleAQMessage
オブジェクトのMessageId
プロパティは常にnull
です。
デキューされたバッファ・メッセージのMessageId
値は、データベースのバージョンに関係なく、常にnull
です。
Enqueue
インスタンス・メソッドは、キューにメッセージをエンキューします。
オーバーロード・リスト
このインスタンス・メソッドは、インスタンスのEnqueueOptions
を使用してキューにメッセージをエンキューします。
Enqueue(OracleAQMessage, OracleAQEnqueueOptions)
このインスタンス・メソッドは、指定されたエンキュー・オプションを使用してキューにメッセージをエンキューします。
このインスタンス・メソッドは、インスタンスのEnqueueOptions
を使用してキューにメッセージをエンキューします。
宣言
// C#
public void Enqueue(OracleAQMessage message);
パラメータ
message
OracleAQMessage
オブジェクト。
例外
ObjectDisposedException
- オブジェクトはすでに処理されています。
InvalidOperationException
- 接続がオープンされていません。
ArgumentNullException
- メッセージ・パラメータがnull
です。
ArgumentException
- メッセージ・ペイロードはOracleXmlType
で、OracleXmlType
の作成に使用される接続はキューの接続とは異なります。
備考
Enqueue
のコールが完了すると、エンキューされたメッセージのMessageId
に値が移入されます。エンキューされたバッファ・メッセージは、常にnullのMessageId
値を持ちます。
このファンクションをコールする前にMessageType
プロパティを適切に設定しておく必要があります。MessageType
がOracleAQMessageType.UDT
の場合は、UdtTypeName
プロパティも設定する必要があります。
このインスタンス・メソッドは、指定されたエンキュー・オプションを使用してキューにメッセージをエンキューします。
宣言
// 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
プロパティは変更されません。
このファンクションをコールする前にMessageType
プロパティを適切に設定しておく必要があります。MessageType
がOracleAQMessageType.UDT
の場合は、UdtTypeName
プロパティも設定する必要があります。
EnqueueArray
インスタンス・メソッドは、キューに複数のメッセージをエンキューします。
オーバーロード・リスト
EnqueueArray(OracleAQMessage[ ])
このインスタンス・メソッドは、インスタンスのEnqueueOptions
を使用してキューに複数のメッセージをエンキューします。
EnqueueArray(OracleAQMessage[ ], OracleAQEnqueueOptions)
このインスタンス・メソッドは、指定されたエンキュー・オプションを使用してキューに複数のメッセージをエンキューします。
このインスタンス・メソッドは、インスタンスの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
値を持ちます。
このファンクションをコールする前にMessageType
プロパティを適切に設定しておく必要があります。MessageType
がOracleAQMessageType.UDT
の場合は、UdtTypeName
プロパティも設定する必要があります。
このインスタンス・メソッドは、指定されたエンキュー・オプションを使用してキューに複数のメッセージをエンキューします。
宣言
// C# public int EnqueueArray(OracleAQMessage[] messages, OracleAQEnqueueOptions enqueueOptions);
パラメータ
messages
OracleAQMessage
オブジェクトの配列。
enqueueOptions
OracleAQEnqueueOptions
オブジェクト。
戻り値
実際にエンキューされたメッセージの数を表すinteger
。
例外
ArgumentNullException
- メッセージ・パラメータがnull
です。
ArgumentException
- 少なくとも1つのOracleAQMessage[]
要素がnull
であるか、少なくとも1つのOracleAQMessage[]
要素にOracleXmlType
のペイロードがあります。このペイロードは、キューの接続とは異なる接続を使用して作成されます。
InvalidOperationException
- OracleAQMessage
配列が空か、接続がオープンされていません。
ObjectDisposedException
- オブジェクトはすでに処理されています。
備考
このメソッドはOracle Database 10g以上のリリースでサポートされます。Enqueue
のコールが完了すると、エンキューされたメッセージのMessageId
プロパティに値が移入されます。エンキューされたバッファ・メッセージは、常にnullのMessageId
値を持ちます。このメソッドをコールしても、キューのEnqueueOptions
プロパティは変更されません。
指定したenqueueOptions
オブジェクトがnull
の場合は、エンキュー・オプションのデフォルト値が使用されます。この操作では、キュー・オブジェクトのEnqueueOptions
プロパティは無視されます。
このファンクションをコールする前にMessageType
プロパティを適切に設定しておく必要があります。MessageType
がOracleAQMessageType.UDT
の場合は、UdtTypeName
プロパティも設定する必要があります。
Listenメソッドは、listenConsumers
に代わってキューのメッセージをリスニングします。
オーバーロード・リスト
このメソッドは、listenConsumers
に代わってキューのメッセージをリスニングします。
このメソッドは、指定された時間にわたり、listenConsumers
に代わってメッセージをリスニングします。
このメソッドは、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(); } } }
このメソッドは、指定された時間にわたり、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
イベントを、表12-30にリストします。
このイベントは、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(); } } }