Operational Interface: Basic Operations, 11 of 16

Dequeue a Message

Figure 11-10 Use Case Diagram: Dequeue a Message

To refer to the table of all basic operations having to do with the Operational Interface see:

"Use Case Model: Operational Interface -- Basic Operations"

Purpose

Dequeues a message from the specified queue.

Usage Notes

Search criteria and dequeue order for messages:

The search criteria for messages to be dequeued is determined by the consumer name, msgid and correlation parameters in the dequeue options. Msgid uniquely identifies the message to be dequeued. Correlation identifiers are application-defined identifiers that are not interpreted by AQ.
Only messages in the READY state are dequeued unless a msgid is specified.
The dequeue order is determined by the values specified at the time the queue table is created unless overridden by the msgid and correlation id in dequeue options.
The database consistent read mechanism is applicable for queue operations. For example, a BROWSE call may not see a message that is enqueued after the beginning of the browsing transaction.

Navigating through a queue

The default NAVIGATION parameter during dequeue is NEXT MESSAGE. This means that subsequent dequeues will retrieve the messages from the queue based on the snapshot obtained in the first dequeue. In particular, a message that is enqueued after the first dequeue command will be processed only after processing all the remaining messages in the queue. This is usually sufficient when all the messages have already been enqueued into the queue, or when the queue does not have a priority-based ordering. However, applications must use the FIRST MESSAGE navigation option when the first message in the queue needs to be processed by every dequeue command. This usually becomes necessary when a higher priority message arrives in the queue while messages already-enqueued are being processed.

Note:
It may also be more efficient to use the FIRST MESSAGE navigation option when there are messages being concurrently enqueued. If the FIRST MESSAGE option is not specified, AQ will have to continually generate the snapshot as of the first dequeue command, leading to poor performance. If the FIRST MESSAGE option is specified, AQ will use a new snapshot for every dequeue command.

Dequeue by Message Grouping

Messages enqueued in the same transaction into a queue that has been enabled for message grouping will form a group. If only one message is enqueued in the transaction, this will effectively form a group of one message. There is no upper limit to the number of messages that can be grouped in a single transaction.
In queues that have not been enabled for message grouping, a dequeue in LOCKED or REMOVE mode locks only a single message. By contrast, a dequeue operation that seeks to dequeue a message that is part of a group will lock the entire group. This is useful when all the messages in a group need to be processed as an atomic unit.
When all the messages in a group have been dequeued, the dequeue returns an error indicating that all messages in the group have been processed. The application can then use the NEXT TRANSACTION to start dequeuing messages from the next available group. In the event that no groups are available, the dequeue will time-out after the specified WAIT period.

Syntax

See Chapter 3, "AQ Programmatic Environments" for a list of available functions in each programmatic environment. Use the following syntax references for each programmatic environment:

PL/SQL (DBMS_AQ Package): Oracle8i Supplied PL/SQL Packages Reference DBMS_AQ, DEQUEUE procedure
Visual Basic (OO4O) (Oracle Objects for OLE (OO4O) Online Help): From Help Topics, Contents tab, select OO4O Automation Server > OBJECTS > OraAQ
Java (JDBC): Oracle8i Supplied Java Packages Reference,oracle.jms, AQOracleQueue.dequeue

Examples

See Chapter 3, "AQ Programmatic Environments" for a list of available functions in each programmatic environment. Examples in the following programmatic environments are provided: