3. API: AqQueue Class

An AqQueue object is created by connection.getQueue(). It is used for enqueuing and dequeuing Oracle Advanced Queuing messages. Each AqQueue can be used for enqueuing, dequeuing, or for both.

Note

In this release, Oracle Advanced Queuing (AQ) is only supported in the node-oracledb Thick mode. See Enabling node-oracledb Thick Mode.

See Oracle Advanced Queuing (AQ) for usage.

The AqQueue class was added in node-oracledb 4.0.

3.1. AqQueue Properties

aqQueue.name: This read-only property is a string containing the name of the queue specified in the connection.getQueue() call.

aqQueue.deqOptions

This property is an object specifying the Advanced Queuing options to use when dequeuing messages. Attributes can be set before each queue.deqOne() or queue.deqMany(), see Changing AQ options.

When a queue is created, the queue.deqOptions property is an AqDeqOptions object. AqDeqOptions objects cannot be created independently.

Table 3.3 AqDeqOptions Class Attributes
Attribute Name	Description
`condition`	A String that defines the condition that must be satisfied in order for a message to be dequeued.
`consumerName`	A String that defines the name of the consumer that is dequeuing messages.
`correlation`	A String that defines the correlation to use when dequeuing.
`mode`	An integer value that defines the mode to use for dequeuing messages. It can be one of the following constants: oracledb.AQ_DEQ_MODE_BROWSE, oracledb.AQ_DEQ_MODE_LOCKED, oracledb.AQ_DEQ_MODE_REMOVE, oracledb.AQ_DEQ_MODE_REMOVE_NO_DATA.
`msgId`	A Buffer containing a unique identifier specifying the message to be dequeued.
`navigation`	An integer value that defines the position in the queue of the message that is to be dequeued. It can be one of the following constants: oracledb.AQ_DEQ_NAV_FIRST_MSG, oracledb.AQ_DEQ_NAV_NEXT_TRANSACTION, oracledb.AQ_DEQ_NAV_NEXT_MSG.
`transformation`	A String that defines the transformation that will take place on messages when they are dequeued.
`visibility`	An integer value that defines whether the dequeue occurs in the current transaction or as a separate transaction. It can be one of the following constants: oracledb.AQ_VISIBILITY_IMMEDIATE, oracledb.AQ_VISIBILITY_ON_COMMIT.
`wait`	An integer defining the number of seconds to wait for a message matching the search criteria to become available. It can alternatively be one of the following constants: oracledb.AQ_DEQ_NO_WAIT, oracledb.AQ_DEQ_WAIT_FOREVER.

See Oracle Advanced Queuing Documentation for more information about attributes.

aqQueue.enqOptions

This property is an object specifying the Advanced Queuing options to use when enqueuing messages. Attributes can be set before each queue.enqOne() or queue.enqMany() call to change the behavior of message delivery, see Changing AQ options.

When a queue is created, the queue.enqOptions property is an AqEnqOptions object. AqEnqOptions objects cannot be created independently.

Table 3.4 AqEnqOptions Class Attributes
Attribute Name	Data Type	Description
`deliveryMode`	Integer	Defines the delivery mode when enqueuing messages. It can be one of the following constants: oracledb.AQ_MSG_DELIV_MODE_PERSISTENT, oracledb.AQ_MSG_DELIV_MODE_BUFFERED, oracledb.AQ_MSG_DELIV_MODE_PERSISTENT_OR_BUFFERED.
`transformation`	String	Defines the transformation that will take place when messages are enqueued.
`visibility`	Integer	Defines whether the enqueue occurs in the current transaction or as a separate transaction. It can be one of the following constants: oracledb.AQ_VISIBILITY_IMMEDIATE, oracledb.AQ_VISIBILITY_ON_COMMIT.

See Oracle Advanced Queuing Documentation for more information about attributes.

aqQueue.payloadType: This read-only property is one of the oracledb.DB_TYPE_RAW or oracledb.DB_TYPE_OBJECT, or oracledb.DB_TYPE_JSON constants.

Changed in version 6.1: Added oracledb.DB_TYPE_JSON constant.

aqQueue.payloadTypeClass

This read-only property is the DbObject Class corresponding to the payload type specified when the queue was created.

This is defined only if payloadType has the value oracledb.DB_TYPE_OBJECT.

aqQueue.payloadTypeName: This read-only property is a string and it can either be the string “RAW” or the name of the Oracle Database object type identified when the queue was created.

3.2. AqQueue Methods

aqQueue.deqMany()

Promise:

promise = deqMany(Number maxMessages);

Dequeues up to the specified number of messages from an Oracle Advanced Queue.

The parameters of the aqQueue.deqMany() method are:

Table 3.5 aqQueue.deqMany() Parameters
Parameter	Data Type	Description
`maxMessages`	Number	Dequeue at most this many messages. Depending on the dequeue options, the number of messages returned will be between zero and `maxMessages`.

Callback:

If you are using the callback programming style:

deqMany(Number maxMessages, function(Error error, Array messages));

See aqQueue.deqMany() Parameters for information on the maxMessages parameter.

The parameters of the callback function function(Array messages, Error error) are:

Callback Function Parameter	Description
Array `messages`	An array of AqMessage objects.
Error `error`	If `deqMany()` succeeds, `error` is NULL. If an error occurs, then `error` contains the error message.

aqQueue.deqOne()

Promise:

promise = deqOne();

Dequeues a single message from an Oracle Advanced Queue. Depending on the dequeue options, the message may also be returned as undefined if no message is available.

Callback:

If you are using the callback programming style:

deqOne(function(Error error, AqMessage message));

The parameters of the callback function function(Error error, AqMessage message) are:

Callback Function Parameter	Description
Error `error`	If `deqOne()` succeeds, `error` is NULL. If an error occurs, then `error` contains the error message.
AqMessage `message`	The message that is dequeued. See AqMessage Class.

Dequeued messages are returned as AqMessage objects.

Table 3.6 AqMessage Class Attributes
Attribute Name	Description
`correlation`	A String containing the correlation that was used during enqueue.
`delay`	An integer containing the number of seconds the message was delayed before it could be dequeued.
`deliveryMode`	An integer containing the delivery mode the messages was enqueued with.
`exceptionQueue`	A String containing the name of the exception queue defined when the message was enqueued.
`expiration`	The number of seconds until expiration defined when the message was enqueued.
`msgId`	A Buffer containing the unique identifier of the message.
`numAttempts`	An integer containing the number of attempts that were made to dequeue the message.
`originalMsgId`	A Buffer containing the unique identifier of the message in the last queue that generated it.
`payload`	A Buffer or DbObject containing the payload of the message, depending on the value of `queue.payloadType`. Note that enqueued Strings are returned as UTF-8 encoded Buffers.
`priority`	An integer containing the priority of the message when it was enqueued.
`state`	An integer representing the state of the message. It is one of the following constants: oracledb.AQ_MSG_STATE_READY, oracledb.AQ_MSG_STATE_WAITING, oracledb.AQ_MSG_STATE_PROCESSED, oracledb.AQ_MSG_STATE_EXPIRED.

See Oracle Advanced Queuing Documentation for more information about attributes.

aqQueue.enqMany()

Promise:

promise = enqMany();

Enqueues multiple messages to an Oracle Advanced Queue.

Warning

Calling enqMany() in parallel on different connections acquired from the same pool may cause a problem with older versions of Oracle (see Oracle bug 29928074). Ensure that enqMany() is not run in parallel. Instead, use standalone connections or make multiple calls to enqOne(). The deqMany() method is not affected.

Callback:

If you are using the callback programming style:

enqMany(Array messages, function(Error error));

The parameters of the aqQueue.enqMany() method are:

Table 3.7 aqQueue.enqMany() Parameters
Parameter	Data Type	Description
`messages`	Array	Each element of the array must be a String, a Buffer, a DbObject, or a JavaScript Object as used by `enqOne()`.

The parameters of the callback function function(Error error) are:

Callback Function Parameter	Description
Error `error`	If `enqMany()` succeeds, `error` is NULL. If an error occurs, then `error` contains the error message.

The queue.enqMany() method returns an array of AqMessage objects.

Changed in version 6.1: Previously, aqQueue.enqMany() did not return any value. Now, this method returns an array of AqMessage objects.

aqQueue.enqOne()

Promise:

promise = enqOne();

Enqueues a single message to an Oracle Advanced Queue. The message may be a String, or a Buffer, or a DbObject. It may also be a JavaScript Object containing the actual message and some attributes controlling the behavior of the queued message.

Callback:

If you are using the callback programming style:

enqOne(String message, function(Error error));
enqOne(Buffer message, function(Error error));
enqOne(DbObject message, function(Error error));
enqOne(Object message, function(Error error));

The parameters of the aqQueue.enqOne() method are:

Table 3.8 aqQueue.enqOne() Parameters
Parameter	Data Type	Description
`message`	String, Buffer, DbObject, or Object	String: If the message is a String, it will be converted to a buffer using the UTF-8 encoding. Buffer: If the message is a Buffer, it will be transferred as it is. DbObject: An object of the DbObject Class. Object message: A JavaScript object can be used to alter the message properties. It must contain a `payload` property with the actual message content. It may contain other attributes as noted in the Object Message Attributes table.

Table 3.9 Object Message Attributes
Message Attribute	Data Type	Description
`correlation`	String	The correlation of the message to be enqueued.
`delay`	Number	The number of seconds to delay the message before it can be dequeued.
`exceptionQueue`	String	The name of an exception queue in which to place the message if an exception takes place.
`expiration`	Number	The number of seconds the message is available to be dequeued before it expires.
`payload`	String, Buffer, DbObject, Object	The actual message to be queued. This property must be specified.
`priority`	Integer	An integer priority of the message.
`recipients`	Array of strings	An array of strings where each string is a recipients name. Added in version 5.5.

See Oracle Advanced Queuing Documentation for more information about attributes.

The parameters of the callback function function(Error error) are:

Callback Function Parameter	Description
Error `error`	If `enqOne()` succeeds, `error` is NULL. If an error occurs, then `error` contains the error message.

Enqueued messages are returned as AqMessage objects.

Changed in version 6.1: Previously, aqQueue.enqOne() did not return any value. Now, this method returns an AqMessage object.