OracleAQQueue Class

An OracleAQQueue object represents a queue.

Class Inheritance

System.Object

  OracleAQQueue

Declaration

// C#
public class OracleAQQueue : IDisposable

Thread Safety

All public static methods are thread-safe, although instance methods do not guarantee thread safety.

Remarks

A queue is a repository of messages and may either be a user queue, or an exception queue. A user queue is for normal message processing. A message is moved from a user queue to an exception queue if it cannot be retrieved and processed for some reason.

Requirements

Namespace: Oracle.DataAccess.Client

Assembly: Oracle.DataAccess.dll

ODP.NET Version: ODP.NET for .NET Framework 2.0 or ODP.NET for .NET Framework 4

---

OracleAQQueue Members

OracleAQQueue members are listed in the following tables.

OracleAQQueue Constructors

OracleAQQueue constructors are listed in Table 12-19.

OracleAQQueue Static Methods

The OracleAQQueue static method is listed in Table 12-20.

OracleAQQueue Properties

OracleAQQueue properties are listed in Table 12-21.

OracleAQQueue Public Methods

The OracleAQQueue public methods are listed in Table 12-22.

OracleAQQueue Events

The OracleAQQueue event is listed in Table 12-23.

---

OracleAQQueue Constructors

OracleAQQueue constructors create new instances of the OracleAQQueue class.

Overload List:

• OracleAQQueue(string)

  This constructor takes a queue name to initialize a queue object.

• OracleAQQueue(string, OracleConnection)

  This constructor takes a queue name and connection to initialize a queue object. The connection does not need be open during the queue object construction.

• OracleAQQueue(string, OracleConnection, OracleAQMessageType)

  This constructor takes a queue name, connection, and message type enumeration to initialize a queue object.

• OracleAQQueue(string, OracleConnection, OracleAQMessageType, string)

  This constructor takes a queue name, connection, message type enumeration, and UDT type name to initialize a queue object.

OracleAQQueue(string)

This constructor takes a queue name to initialize a queue object.

Declaration

// C#
public OracleAQQueue(string name);

Parameters

• name

  The name of the queue as specified in the database.

Exceptions

ArgumentNullException - The queue name is null.

ArgumentException - The queue name is empty.

Remarks

The operation of creating an OracleAQQueue object does not involve checking for the existence of the queue in the database.

OracleAQQueue(string, OracleConnection)

This constructor takes a queue name and connection to initialize a queue object. The connection does not need to be open during the queue object construction.

Declaration

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

Parameters

• name

  Name of the queue as specified in the database.

• con

  An OracleConnection object that connects to the queue.

Exceptions

ArgumentNullException - Either the connection is null or queue name is null.

ArgumentException - Queue name is empty.

Remarks

The connection can be accessed using the Connection property, and it must be opened before calling any operational APIs such as Enqueue and Dequeue.

Creating an OracleAQQueue object does not check for the existence of the queue in the database.

OracleAQQueue(string, OracleConnection, OracleAQMessageType)

This constructor takes a queue name, connection and message type enumeration to initialize a queue object. The connection does not need to be open during the queue object construction.

Declaration

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

Parameters

• name

  The name of the queue as specified in the database.

• con

  An OracleConnection object that is used to connect to the queue.

• messageType

  An OracleAQMessageType enumeration specifying the type of the message that is enqueued or dequeued from this queue.

Exceptions

ArgumentNullException - Either the connection is null or queue name is null.

ArgumentException - Queue name is empty or the specified message type is not valid.

Remarks

Creating an OracleAQQueue object does not check for the existence of the queue in the database.

You need to set the UdtTypeName property before using the queue object if the messageType is a UDT. Another approach is to create a queue using the other constructor overload by supplying the udtTypeName.

OracleAQQueue(string, OracleConnection, OracleAQMessageType, string)

This constructor takes a queue name, connection, message type enumeration, and UDT type name to initialize a queue object. The connection does not need to be open during the queue object construction.

Declaration

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

Parameters

• name

  The name of the queue as specified in the database.

• con

  An OracleConnection object that is used to connect to the queue.

• messageType

  An OracleAQMessageType enumeration specifying the type of the message that is enqueued or dequeued from this queue.

• udtTypeName

  The name of the database object type used if the messageType is UDT. The udtTypeName parameter represents the type on which the queue is based.

Exceptions

ArgumentNullException - The connection is null or the queue name is null.

ArgumentException - The queue name is empty or the specified messageType is not valid.

Remarks

Creating an OracleAQQueue object does not check for the existence of the queue in the database.

---

OracleAQQueue Static Methods

OracleAQQueue static methods are listed in Table 12-24.

Listen

Listen methods listen for messages on one or more queues for one or more consumers as specified in the array of OracleAQAgent objects.

Overload list

• Listen(OracleConnection, OracleAQAgent[ ])

  This static method listens for messages on one or more queues for one or more consumers as specified in the array of OracleAQAgent objects.

• Listen(OracleConnection, OracleAQAgent[ ], int)

  This static method listens for messages on one or more queues for one or more consumers as specified in the array of OracleAQAgent objects. It also specifies a wait time.

Listen(OracleConnection, OracleAQAgent[ ])

This static method listens for messages on one or more queues for one or more consumers as specified in the array of OracleAQAgent objects.

Declaration

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

Parameters

• con

  An OracleConnection instance.

• listenConsumers

  The array of consumers being listened for. The name of the OracleAQAgent object must be null or empty for single consumer queues.

Return Value

An OracleAQAgent object.

Exceptions

ArgumentNullException - The con or listenConsumers parameter is null.

InvalidOperationException - The connection is not open.

Remarks

Listen is useful in situations where one needs to monitor multiple queues until a message is available for a consumer in one of the queues. The Name property of the OracleAQAgent object represents the name of the consumer and the Address property represents the name of the queue.

This call blocks the calling thread until there is a message ready for consumption for a consumer in the list. It returns an OracleAQAgent object which specifies the consumer and queue for which a message is ready to be dequeued.

Listen(OracleConnection, OracleAQAgent[ ], int)

This static method listens for messages on one or more queues for one or more consumers as specified in the array of OracleAQAgent objects. The Name property of the OracleAQAgent object represents the name of the consumer and the Address property of the OracleAQAgent object represents the name of the queue.

In case of timeout, this method returns null.

Declaration

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

Parameters

• con

  An OracleConnection instance.

• listenConsumers

  The array of consumers being listened for. The name of the OracleAQAgent object must be null or empty for single consumer queues.

• waitTime

  Wait time in seconds.

Return Value

An OracleAQAgent object.

Exceptions

ArgumentNullException - The con or listenConsumers parameter is null.

InvalidOperationException - The connection is not open.

ArgumentException - waitTime is less than -1.

Remarks

Listen is useful in situations where one needs to monitor multiple queues until a message is available for a consumer in one of the queues. The Name property of the OracleAQAgent object represents the name of the consumer and the Address property of the OracleAQAgent object represents the name of the queue.

A waitTime of -1 implies an infinite wait time.

This call blocks the calling thread until there is a message ready for consumption for a consumer in the list. It returns an OracleAQAgent object which specifies the consumer and queue for which a message is ready to be dequeued.

---

OracleAQQueue Properties

OracleAQQueue properties are listed in Table 12-25.

Connection

This property specifies the OracleConnection object associated with the queue.

Declaration

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

Property Value

An OracleConnection object that indicates the connection associated with the queue.

Exceptions

ObjectDisposedException - The object is already disposed.

Remarks

This connection must be opened before calling methods like Enqueue and Dequeue.

DequeueOptions

This instance property specifies the dequeueing options to use when dequeuing a message from a queue.

Declaration

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

Property Value

An OracleAQDequeueOptions object.

Exceptions

ObjectDisposedException - The object is already disposed.

Remarks

The default value is an OracleAQDequeueOptions object with default property values. Setting this property to null resets all dequeue options to their default values.

EnqueueOptions

This instance property specifies the enqueueing options used to enqueue a message to a queue.

Declaration

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

Property Value

An OracleAQEnqueueOptions object.

Exceptions

ObjectDisposedException - The object is already disposed.

Remarks

The default value is an OracleAQEnqueueOptions object with default property values. Setting this property to null resets all enqueue options to their default values.

MessageType

This instance property specifies the type of queue table associated with this queue.

Declaration

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

Property Value

An OracleAQMessageType enumerated value.

Exceptions

ArgumentOutOfRangeException - The type value specified is invalid.

ObjectDisposedException - The object is already disposed.

Remarks

The MessageType property also dictates the type of message payloads that are enqueued or dequeued from the queue. It is possible to enqueue a variety of payloads depending on the MessageType.

Table 12-26 lists the allowed payload types for various message types.

Table 12-27 lists the payload types for dequeued messages.

Name

This instance property returns the name of the queue.

Declaration

// C#
public string Name {get;}

Property Value

A string that indicates the name of the queue.

Exceptions

ObjectDisposedException - The object is already disposed.

Notification

This instance property specifies the various notification options for notifications that are registered using the MessageAvailable event.

Declaration

// C#
public OracleNotificationRequest Notification {get;}

Property Value

Specifies an OracleNotificationRequest object whose properties can be changed to alter the notification behavior.

Remarks

This property can be used to change various notification options. The notification options must be changed before registering with the MessageAvailable event. This property can be modified again only after unregistering from the MessageAvailable event.

NotificationConsumers

This instance property specifies the array of consumers, for a multiconsumer queue, that are to be notified asynchronously for any incoming messages on the queue.

Declaration

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

Property Value

Specifies an array of consumer name strings for which the notifications are delivered.

Exceptions

ObjectDisposedException - The object is already disposed.

InvalidOperationException - MessageAvailable registration is active.

Remarks

The consumer names must be in uppercase. This functionality only supports queues with uppercase names.

The list of consumers is used in the MessageAvailable event. The list must be set before registering for the event. This property cannot be modified after registering for the MessageAvailable event. This property can be modified again only after unregistering from MessageAvailable event.

UdtTypeName

This instance property specifies the type name on which the queue and the corresponding queue table is based if the MessageType is OracleAQMessageType.UDT.

Declaration

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

Property Value

Specifies the Oracle user-defined type name if the MessageType is OracleAQMessageType.UDT.

Exceptions

ObjectDisposedException - The object is already disposed.

Remarks

The UdtTypeName property corresponds to the user-defined type name of the payload. This property must always be specified if the payload is a user-defined type. This property need not be set for other payload types.

---

OracleAQQueue Public Methods

OracleAQQueue public methods are listed in Table 12-28.

Dequeue

Dequeue methods dequeue messages from queues.

Overload List

• Dequeue()

  This instance method dequeues messages from a queue using the DequeueOptions for the instance.

• Dequeue(OracleAQDequeueOptions)

  This instance method dequeues messages from a queue using the supplied dequeue options.

Dequeue()

This instance method is used to dequeue a message from a queue using the DequeueOptions for the instance.

Declaration

// C#
public OracleAQMessage Dequeue();

Return Value

An OracleAQMessage instance representing the dequeued message.

Exceptions

InvalidOperationException - The connection is not open.

ObjectDisposedException - The object is already disposed.

OracleException - In case of timeout, an exception is thrown with the message, ORA-25228: timeout or end-of-fetch during message dequeue from queue_name.Timeout may happen if DequeueOptions.Wait is set to a value other than -1.

Remarks

The MessageType property must be set appropriately before calling this function. If the MessageType is OracleAQMessageType.UDT, then the UdtTypeName property must also be set.

Dequeued buffered messages always have null MessageId values.

Dequeue(OracleAQDequeueOptions)

This instance method dequeues messages from a queue using the supplied dequeue options.

Declaration

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

Parameters

• dequeueOptions

  An OracleAQDequeueOptions object.

Return Value

An OracleAQMessage instance representing the dequeued message.

Exceptions

InvalidOperationException - The connection is not open.

ObjectDisposedException - The object is already disposed.

OracleException - In case of timeout, an exception is thrown with the message, ORA-25228: timeout or end-of-fetch during message dequeue from queue_name. Timeout may happen if DequeueOptions.Wait is set to a value other than -1.

Remarks

If the supplied dequeueOptions object is null, then the dequeue options default values are used. The queue object's DequeueOptions property is ignored for this operation.

Calling this method does not change the DequeueOptions property of the queue.

The MessageType property must be set appropriately before calling this function. If the MessageType is OracleAQMessageType.UDT, then the UdtTypeName property must also be set.

Dequeued buffered messages always have null MessageId values.

DequeueArray

DequeueArray methods dequeue multiple messages from queues.

Overload List

• DequeueArray(int)

  This instance method dequeues multiple messages from a queue using the DequeueOptions of the instance.

• DequeueArray(int, OracleAQDequeueOptions)

  This instance method dequeues multiple messages from a queue using the supplied dequeue options.

DequeueArray(int)

This instance method dequeues multiple messages from a queue using the DequeueOptions of the instance.

Declaration

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

Parameters

• dequeueCount

  An integer specifying the numbers of messages to dequeue.

Return Value

An array of OracleAQMessage instances representing the dequeued messages.

Exceptions

ArgumentOutOfRangeException - dequeueCount is less than or equal to 0.

InvalidOperationException - The connection is not open.

ObjectDisposedException - The object is already disposed.

OracleException - In case of timeout, an exception is thrown with the message, ORA-25228: timeout or end-of-fetch during message dequeue from queue_name. Timeout may happen if DequeueOptions.Wait is set to a value other than -1.

Remarks

This method is supported for Oracle Database 10g and higher releases.

The MessageType property must be set appropriately before calling this function. If the MessageType is OracleAQMessageType.UDT, then the UdtTypeName property must be set as well.

The size of the returned array may be less than the dequeueCount. It depends on the actual number of messages present in the queue.

For database versions earlier than Oracle Database 11g Release 2 (11.2.0.2), the MessageId property of persistent OracleAQMessage objects retrieved using DequeueArray is always null.

Dequeued buffered messages always have null MessageId values irrespective of the database version.

DequeueArray(int, OracleAQDequeueOptions)

This instance method dequeues multiple messages from a queue using the supplied dequeue options.

Declaration

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

Parameters

• dequeueCount

  An integer specifying the numbers of messages to dequeue.

• dequeueOptions

  An OracleAQDequeueOptions object.

Return Value

An array of OracleAQMessage instances representing the dequeued messages.

Exceptions

ArgumentOutOfRangeException - dequeueCount is less than or equal to 0.

InvalidOperationException - The connection is not open.

ObjectDisposedException - The object is already disposed.

OracleException - In case of timeout, an exception is thrown with the message, ORA-25228: timeout or end-of-fetch during message dequeue from queue_name. Timeout may happen if DequeueOptions.Wait is set to a value other than -1.

Remarks

This method is supported for Oracle Database 10g Release 1 (10.1) and higher releases. Calling this method does not change the DequeueOptions property of the queue.

If the supplied dequeueOptions object is null, then the dequeue options default values are used. The DequeueOptions property of the queue object is ignored in this operation.

The MessageType property must be set appropriately before calling this function. If the MessageType is OracleAQMessageType.UDT, then the UdtTypeName property must be set as well.

The size of the returned array may be less than the dequeueCount. It dependes on the actual number of messages present in the queue.

For database versions earlier than Oracle Database 11g Release 2 (11.2.0.2), the MessageId property of persistent OracleAQMessage objects retrieved using DequeueArray is always null.

Dequeued buffered messages always have null MessageId values irrespective of the database version.

Dispose

This method releases any resources or memory allocated by the object.

Declaration

// C#
public void Dispose();

Implements

IDisposable.

Enqueue

Enqueue instance methods enqueue messages to queues.

Overload List

• Enqueue(OracleAQMessage)

  This instance method enqueues messages to a queue using the EnqueueOptions of the instance.

• Enqueue(OracleAQMessage, OracleAQEnqueueOptions)

  This instance method enqueues messages to a queue using the supplied enqueue options.

Enqueue(OracleAQMessage)

This instance method enqueues messages to a queue using the EnqueueOptions of the instance.

Declaration

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

Parameters

• message

  An OracleAQMessage object.

Exceptions

ObjectDisposedException - The object is already disposed.

InvalidOperationException - The connection is not open.

ArgumentNullException - The message parameter is null.

ArgumentException - The message payload is OracleXmlType and the connection used to create OracleXmlType is different from the queue's connection.

Remarks

MessageId of the enqueued message is populated after the call to Enqueue completes. Enqueued buffered messages always have null MessageId values.

The MessageType property needs to be set appropriately before calling this function. If the MessageType is OracleAQMessageType.UDT, then the UdtTypeName property must be set as well.

Enqueue(OracleAQMessage, OracleAQEnqueueOptions)

This instance method enqueues messages to a queue using the supplied enqueue options.

Declaration

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

Parameters

• message

  An OracleAQMessage object.

• enqueueOptions

  An OracleAQEnqueueOptions object.

Exceptions

ObjectDisposedException - The object is already disposed.

InvalidOperationException - The connection is not open.

ArgumentNullException - The message parameter is null.

ArgumentException - The message payload is OracleXmlType and the connection used to create OracleXmlType is different from the queue's connection.

Remarks

If the supplied enqueueOptions object is null, then the enqueue options default values are used. The EnqueueOptions property of the queue object is ignored in this operation.

The MessageId of the enqueued message is populated after the call to Enqueue completes. Enqueued buffered messages always have null MessageId values. Calling this method does not change the EnqueueOptions property of the queue.

The MessageType property must be set appropriately before calling this function. If the MessageType is OracleAQMessageType.UDT, then the UdtTypeName property must also be set.

EnqueueArray

EnqueueArray instance methods enqueue multiple messages to a queue.

Overload List

• EnqueueArray(OracleAQMessage[ ])

  This instance method enqueues multiple messages to a queue using the EnqueueOptions of the instance.

• EnqueueArray(OracleAQMessage[ ], OracleAQEnqueueOptions)

  This instance method enqueues multiple messages to a queue using the supplied enqueue options.

EnqueueArray(OracleAQMessage[ ])

This instance method enqueues multiple messages to a queue using the EnqueueOptions of the instance.

Declaration

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

Parameters

• messages

  An array of OracleAQMessage objects.

Return Value

An integer representing the number of messages actually enqueued.

Exceptions

ArgumentNullException - The message parameter is null.

ArgumentException - At least one of the OracleAQMessage[] elements is null, or at least one of the OracleAQMessage[] elements has a payload of OracleXmlType, which is created using a connection that is different from the queue's connection.

InvalidOperationException - The OracleAQMessage array is empty or the connection is not open.

ObjectDisposedException - The object is already disposed.

Remarks

This method is supported by Oracle Database 10g and higher releases. The MessageId properties of the enqueued messages are populated after the call to Enqueue completes. Enqueued buffered messages always have null MessageId values.

The MessageType property must be set appropriately before calling this function. If the MessageType is OracleAQMessageType.UDT, then the UdtTypeName property must also be set.

EnqueueArray(OracleAQMessage[ ], OracleAQEnqueueOptions)

This instance method enqueues multiple messages to a queue using the supplied enqueue options.

Declaration

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

Parameters

• messages

  An array of OracleAQMessage objects.

• enqueueOptions

  An OracleAQEnqueueOptions object.

Return Value

An integer representing the number of messages actually enqueued.

Exceptions

ArgumentNullException - The message parameter is null.

ArgumentException - At least one of the OracleAQMessage[] elements is null, or at least one of the OracleAQMessage[] elements has a payload of OracleXmlType, which is created using a connection that is different from the queue's connection.

InvalidOperationException - The OracleAQMessage array is empty or the connection is not open.

ObjectDisposedException - The object is already disposed.

Remarks

This method is supported by Oracle Database 10g and higher releases. MessageId properties of the enqueued messages are populated after the call to Enqueue completes. Enqueued buffered messages always have null MessageId values. Calling this method does not change the EnqueueOptions property of the queue.

If the supplied enqueueOptions object is null, then the enqueue options default values are used. The EnqueueOptions property of the queue object is ignored in this operation.

The MessageType property must be set appropriately before calling this function. If the MessageType is OracleAQMessageType.UDT, then the UdtTypeName property must also be set.

Listen

Listen methods listen for messages on the queue on behalf of listenConsumers.

Overload List

• Listen(string[])

  This method listens for messages on the queue on behalf of listenConsumers.

• Listen (string[], int)

  This method listens for messages on behalf of listenConsumers for a specified time.

Listen(string[])

This method listens for messages on the queue on behalf of listenConsumers.

Declaration

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

Parameters

• listenConsumers

  An array of consumers to listen for on this queue. This parameter should be null in case of single consumer queues.

Return Value

A string.

Exceptions

InvalidOperationException - The connection is not open.

ObjectDisposedException - The object is already disposed.

Remarks

This call blocks the calling thread until there is a message ready for consumption for a consumer in the listenConsumers array. It returns a string representing the consumer name for which the message is ready.

Listen is useful in situations that require waiting until a message is available in the queue for consumers whose names are specified in listenConsumers.

Example

The following example demonstrates using the Listen method. The first part of the example performs the requisite database setup for the database user, SCOTT. The second part of the example demonstrates how a thread can listen and wait until a message is enqueued.

-- 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)

This method listens for messages on behalf of listenConsumers for a specified time.

Declaration

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

Parameters

• listenConsumers

  Array of consumers for which to listen on this queue.

• waitTime

  Wait time in seconds.

Return Value

A string

Exceptions

InvalidOperationException - The connection is not open.

ArgumentException - waitTime is less than -1.

ObjectDisposedException - The object is already disposed.

Remarks

Listen is useful in situations that require waiting until a message is available in the queue for consumers whose names are specified in listenConsumers.

This call blocks the calling thread until there is a message ready for consumption for a consumer in the listenConsumers array. It returns a string representing the consumer name for which the message is ready.The method returns null if a timeout occurs.

The listenConsumers parameter should be null for single consumer queues. An empty string is returned in such cases.

A waitTime of -1 implies infinite wait time.

---

OracleAQQueue Events

The OracleAQQueue event is listed in Table 12-29.

MessageAvailable Event

This event is notified when a message is available in the queue for NotificationConsumers.

Declaration

// C#
public event OracleAQMessageAvailableEventHandler MessageAvailable;

Event Data

The event handler receives an OracleAQMessageAvailableEventArgs object.

Exceptions

InvalidOperationException - The connection is not open.

Remarks

Asynchronous notification is supported in all queue tables created with a database compatibility level of 8.1 or higher.

In order to receive the notification about message availability, the client must create an OracleAQMessageAvailableEventHandler delegate to listen to this event. The delegate should be added to this event only after setting the NotificationConsumers and Notification properties.

The notification registration takes place after the first delegate is added to the event. The notification is unregistered when the last delegate is removed from the event. Notifications set on an OracleAQQueue object get cancelled automatically when the object gets disposed.

Oracle Data Provider for .NET opens a port to listen for notifications. HA events, load balancing, and database change notification features also share the same port. This port can be configured centrally by setting the database notification port in an application or Web configuration file. The following example code specifies a port number of 1200:

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

If the configuration file does not exist or the db notification port is not specified, then ODP.NET uses a valid and random port number. The configuration file may also request for a random port number by specifying a db notification port value of -1.

The notification listener, which runs in the same application domain as ODP.NET, uses the specified port number to listen to notifications from the database. A notification listener gets created when the application registers with OracleAQQueue.MessageAvailable event. One notification listener can listen to all notification types. Only one notification listener is created for each application domain.

Example

The following example demonstrates application notification. The first part of the example performs the requisite database setup for the database user, SCOTT. The second part of the example demonstrates how an application is notified when a message is available in the queue.

-- 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();
    }
  }
}