OracleAQMessage Class

An OracleAQMessage object represents a message to be enqueued and dequeued.

Class Inheritance

System.Object

  OracleAQMessage

Declaration

// C#
public sealed class OracleAQMessage

Thread Safety

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

Remarks

An OracleAQMessage object consists of control information (metadata) and Payload (data). The control information is exposed by various properties on the OracleAQMessage object and is used by Oracle Streams Advanced Queuing to manage messages. The payload is the information stored in the queue.

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

---

OracleAQMessage Members

OracleAQMessage members are listed in the following tables.

OracleAQMessage Constructor

OracleAQMessage constructors are listed in Table 12-14.

OracleAQMessage Properties

OracleAQMessage properties are listed in Table 12-15.

---

OracleAQMessage Constructors

OracleAQMessage constructors create new instances of the OracleAQMessage class.

Overload List:

• OracleAQMessage()

  This constructor instantiates the OracleAQMessage class.

• OracleAQMessage(Object)

  This constructor instantiates the OracleAQMessage class using the object provided as the payload.

OracleAQMessage()

This constructor instantiates the OracleAQMessage class.

Declaration

// C#
public OracleAQMessage();

OracleAQMessage(Object)

This constructor instantiates the OracleAQMessage class using the Object provided as the payload.

Declaration

// C#
public OracleAQMessage(Object payload);

Parameters

• payload

  An Object specifying payload. It can be one of the following types:

  • byte[]

  • IOracleCustomType

  • OracleBinary

  • OracleXmlType

  • String

  • XmlReader

Exceptions

ArgumentException - The specified payload value is of invalid type.

Remarks

The ODP.NET AQ implementation currently does not support user defined types with LOB attributes. It also does not support other variants of user defined types such as VARRAY and nested tables, as Oracle Streams AQ does not support them inherently.

---

OracleAQMessage Properties

OracleAQMessage properties are listed in Table 12-16.

Correlation

This instance property specifies an identification for the message.

Declaration

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

Property Value

A string that specifies the identification for the message.

Remarks

The producer of a message can set this property at the time of enqueuing. The consumer can then use this identification to dequeue specific messages by setting the Correlation property of an OracleAQDequeueOptions object. For more information regarding dequeuing messages based on Correlation, refer to "Correlation" under the OracleAQDequeueOptions class.

Delay

This instance property specifies the duration, in seconds, after which an enqueued message is available for dequeuing.

Declaration

// C#
public int Delay {get;set;}

Property Value

An integer that indicates the number of seconds after which an enqueued message is available for dequeuing.

Exceptions

ArgumentException - The value specified is less than 0.

Remarks

This property delays the immediate consumption of an enqueued message. The following are valid values for this property:

• Positive integer - Indicates the delay in seconds.

• 0 - indicates that the message is immediately available for dequeuing.

The default value is 0. The Delay property is not supported with buffered messaging.

DeliveryMode

This instance property specifies the delivery mode of the dequeued message.

Declaration

// C#
public OracleAQMessageDeliveryMode DeliveryMode {get;}

Property Value

An OracleAQMessageDeliveryMode enumerated value (OracleAQMessageDeliveryMode.Persistent or OracleAQMessageDeliveryMode.Buffered).

DequeueAttempts

This instance property returns the number of attempts that have been made to dequeue the message.

Declaration

// C#
public int DequeueAttempts {get;}

Property Value

An integer that indicates the number of dequeue attempts.

Remarks

This property is available in an OracleAQMessage after the message has been dequeued from a queue.

EnqueueTime

This instance property specifies the time when the message was enqueued.

Declaration

// C#
public DateTime EnqueueTime {get;}

Property Value

A DateTime object.

Remarks

This property is available after the message is dequeued. It provides the enqueue time of a dequeued message.

ExceptionQueue

This instance property specifies the name of the queue that the message should be moved to if it cannot be processed successfully.

Declaration

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

Property Value

The name of the queue that a message should be moved to if it cannot be processed successfully. The default value is null.

Remarks

This property specifies the queue that a message should be moved to if the message has expired or if the number of unsuccessful dequeue attempts have exceeded the max_retries value for the queue.

If this property is not set or the specified exception queue name does not exist, then the default exception queue associated with the queue table is used.

Expiration

This instance property specifies the duration, in seconds, for which an enqueued message is available for dequeuing.

Declaration

// C#
public int Expiration {get;set;}

Property Value

An integer that specifies the number of seconds an enqueued message is available for dequeuing.

Exceptions

ArgumentException - The value specified is less than -1.

Remarks

The value specified is an offset from the value specified in the Delay property.

The following are valid values for the property:

• Positive integer - Indicates the expiration in seconds.

• -1 - Indicates that the message never expires.

The default value is -1. When a message expires, the message moves from the READY state to the EXPIRED state.

MessageId

This instance property returns the message identifier.

Declaration

// C#
public byte[] MessageId {get;}

Property Value

A byte[] that specifies the message identifier.

Remarks

This property is available after an enqueue or dequeue operation. Dequeued buffered messages have a null value for MessageId.

OriginalMessageId

This instance property specifies the identifier of the message in the last queue that generated this message.

Declaration

// C#
public byte[] OriginalMessageId {get;}

Property Value

A byte[] that specifies the original message identifier.

Payload

This instance property specifies the payload of the message.

Declaration

// C#
public Object Payload {get;set;}

Property Value

An Object that specifies the payload of the message.

Exceptions

ArgumentException - The specified object is not one of the allowed types.

Remarks

For a complete discussion of various payload types, refer to "MessageType" under the OracleAQQueue class.

Priority

This instance property specifies the priority of the message.

Declaration

// C#
public int Priority {get;set;}

Property Value

An integer that specifies the priority of the message.

Remarks

The default value is 0. In order to take effect, this property must be set prior to enqueuing the message.

Smaller values indicate higher priority for the message. Negative values may also be used.

The priority of an enqueued message is useful for priority-based dequeuing.

Recipients

This instance property specifies the list of recipients that overrides the default queue subscribers.

Declaration

// C#
public OracleAQAgent[] Recipients {get; set}

Property Value

An OracleAQAgent[].

Remarks

This recipient list is valid only for messages being enqueued to multiconsumer queues. The list of recipients is not returned with the message at the time of dequeuing.

SenderId

This instance property identifies the original sender of the message.

Declaration

// C#
public OracleAQAgent SenderId {get; set}

Property Value

An OracleAQAgent object.

Remarks

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

State

This instance property specifies the state of the message at the time of dequeue.

Declaration

// C#
public OracleAQMessageState State {get;}

Property Value

An OracleAQMessageState enumerated value.

Remarks

This property is available after the message is dequeued.

The state of buffered messages dequeued by specifying Correlation under dequeue options is always OracleAQMessageState.Ready.

TransactionGroup

This instance property specifies the transaction group for the dequeued message.

Declaration

// C#
public string TransactionGroup {get;}

Property Value

A string that specifies the transaction group.

Remarks

This property is set only after the call to DequeueArray. This property is supported only when using Oracle Database 10g database or higher.

Messages belonging to one queue can be grouped to form a set that can only be consumed by one user at a time. This requires that the queue be created in a queue table that is enabled for message grouping. All messages belonging to a group must be created in the same transaction. Also, all messages created in one transaction belong to the same group.