OracleAQMessage Class

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

Class Inheritance

System.Object

OracleAQMessage

Declaration

// C#
public sealed class OracleAQMessage

Requirements

Provider	ODP.NET, Unmanaged Driver
Assembly	`Oracle.DataAccess.dll`
Namespace	`Oracle.DataAccess.Client`
.NET Framework	3.5, 4.0, 4.5

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.

Note:

An instance of OracleAQMessage cannot be re-used across multiple operations of OracleAQQueue public method Enqueue() or EnqueueArray(), if the payload is an XmlReader. This is a direct consequence of the forward-only semantics of the XmlReader, as an Enqueue() or EnqueueArray() operation internally invokes a read operation on the XmlReader to extract the data to be enqueued.

See Also:

OracleAQMessage Members

OracleAQMessage members are listed in the following tables.

OracleAQMessage Constructor

OracleAQMessage constructors are listed in Table 12-14.

Table 12-14 OracleAQMessage Constructors

Constructor	Description
OracleAQMessage Constructors	Instantiates a new instance of the `OracleAQMessage` class (Overloaded).

OracleAQMessage Properties

OracleAQMessage properties are listed in Table 12-15.

Table 12-15 OracleAQMessage Properties

Property	Description
Correlation	Specifies an identification for the message.
Delay	Specifies the duration, in seconds, after which an enqueued message is available for dequeuing.
DeliveryMode	Specifies the delivery mode of the dequeued message.
DequeueAttempts	Returns the number of attempts that have been made to dequeue the message.
EnqueueTime	Specifies the time when the message was enqueued.
ExceptionQueue	Specifies the name of the queue that the message should be moved to if it cannot be processed successfully.
Expiration	Specifies the duration, in seconds, for which an enqueued message is available for dequeuing.
MessageId	Returns the message identifier.
OriginalMessageId	Specifies the identifier of the message in the last queue that generated this message.
Payload	Specifies the payload of the message.
Priority	Specifies the priority of the message.
Recipients	Specifies the list of recipients that overrides the default queue subscribers.
SenderId	Identifies the original sender of the message.
State	Specifies the state of the message at the time of dequeue.
TransactionGroup	Specifies the transaction group for the dequeued message.

See Also:

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.

See Also:

OracleAQMessage()

This constructor instantiates the OracleAQMessage class.

Declaration

// C#
public OracleAQMessage();

See Also:

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.

See Also:

OracleAQMessage Properties

OracleAQMessage properties are listed in Table 12-16.

Table 12-16 OracleAQMessage Properties

Property	Description
Correlation	Specifies an identification for the message.
Delay	Specifies the duration, in seconds, after which an enqueued message is available for dequeuing.
DeliveryMode	Specifies the delivery mode of the dequeued message.
DequeueAttempts	Returns the number of attempts that have been made to dequeue the message.
EnqueueTime	Specifies the time when the message was enqueued.
ExceptionQueue	Specifies the name of the queue that the message should be moved to if it cannot be processed successfully.
Expiration	Specifies the duration, in seconds, for which an enqueued message is available for dequeuing.
MessageId	Returns the message identifier.
OriginalMessageId	Specifies the identifier of the message in the last queue that generated this message.
Payload	Specifies the payload of the message.
Priority	Specifies the priority of the message.
Recipients	Specifies the list of recipients that overrides the default queue subscribers.
SenderId	Identifies the original sender of the message.
State	Specifies the state of the message at the time of dequeue.
TransactionGroup	Specifies the transaction group for the dequeued message.

See Also:

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.

See Also:

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.

See Also:

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

See Also:

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.

See Also:

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.

See Also:

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.

See Also:

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.

See Also:

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.

See Also:

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.

See Also:

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.

See Also:

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.

See Also:

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.

See Also:

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.

See Also:

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.

See Also:

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.

See Also: