Dequeuing a Message from a Single-Consumer Queue [SpecifyOptions]

Figure 11-11 Use Case Diagram: Dequeuing a Message from a Single-Consumer Queue

Text description of the illustration adq11qop3.gif

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

To specify the options available for the dequeue operation.

Usage Notes

Typically, you expect the consumer of messages to access messages using the dequeue interface. You can view processed messages or messages still to be processed by browsing by message id or by using SELECTs.

The transformation, if specified, is applied before returning the message to the caller. The transformation should be defined to map the queue ADT type to the return type desired by the caller.

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): Oracle9i Supplied PL/SQL Packages and Types 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): Oracle9i Supplied Java Packages Reference,oracle.jms, AQDequeueOption

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:

• PL/SQL (DBMS_AQ Package): Dequeue of Object Type Messages

• Java (JDBC): Dequeue a message from a single consumer queue (specify options)

• Visual Basic (OO4O): Dequeue a message

PL/SQL (DBMS_AQ Package): Dequeue of Object Type Messages

/* Dequeue from msg_queue: */
DECLARE
dequeue_options     dbms_aq.dequeue_options_t;
message_properties  dbms_aq.message_properties_t;
message_handle      RAW(16);
message             aq.message_typ;

BEGIN
   DBMS_AQ.DEQUEUE(
      queue_name          =>     'msg_queue',
      dequeue_options      =>    dequeue_options,
      message_properties  =>     message_properties,
      payload             =>     message,
      msgid               =>     message_handle);

   DBMS_OUTPUT.PUT_LINE ('Message: ' || message.subject ||
                                      ' ... ' || message.text );
   COMMIT;
END;

Java (JDBC): Dequeue a message from a single consumer queue (specify options)

/* Dequeue a message with correlation id = 'RUSH' */
public static void example(AQSession aq_sess) throws AQException, SQLException
{
     AQQueue                  queue;
     AQMessage                message;
     AQRawPayload             raw_payload;
     AQDequeueOption          deq_option;
     byte[]                   b_array;
     Connection               db_conn;

     db_conn = ((AQOracleSession)aq_sess).getDBConnection();

     queue = aq_sess.getQueue ("aq", "msg_queue");

     /* Create a AQDequeueOption object with default options: */
     deq_option = new AQDequeueOption();

     deq_option.setCorrelation("RUSH");

     /* Dequeue a message */
     message = queue.dequeue(deq_option);

     System.out.println("Successful dequeue"); 
    
     /* Retrieve raw data from the message: */
     raw_payload = message.getRawPayload();
 
     b_array = raw_payload.getBytes();

     db_conn.commit();
}

Visual Basic (OO4O): Dequeue a message

Dequeuing messages of RAW type

 'Dequeue the first message available  
Q.Dequeue() 
Set Msg = Q.QMsg 

'Display the message content 
MsgBox Msg.Value 

'Dequeue the first message available without removing it 
' from the queue 
Q.DequeueMode = ORAAQ_DEQ_BROWSE 

'Dequeue the first message with the correlation identifier 
' equal to "RELATIVE_MSG_ID" 
Q.Navigation = ORAAQ_DQ_FIRST_MSG 
Q.correlate = "RELATIVE_MESSAGE_ID" 
Q.Dequeue 

'Dequeue the next message with the correlation identifier 

' of "RELATIVE_MSG_ID" 
Q.Navigation = ORAAQ_DQ_NEXT_MSG 
Q.Dequeue() 

'Dequeue the first high priority message 
Msg.Priority = ORAQMSG_HIGH_PRIORITY 
Q.Dequeue() 

'Dequeue the message enqueued with message id of Msgid_1 
Q.DequeueMsgid = Msgid_1 
Q.Dequeue() 

'Dequeue the message meant for "ANDY" 
Q.consumer = "ANDY" 
Q.Dequeue() 

'Return immediately if there is no message on the queue  
Q.wait = ORAAQ_DQ_NOWAIT 
Q.Dequeue()

Dequeuing messages of Oracle object type

Set OraObj = DB.CreateOraObject("MESSAGE_TYPE") 
Set QMsg = Q.AQMsg(1, "MESSAGE_TYPE") 

'Dequeue the first message available without removing it 
Q.Dequeue() 
OraObj = QMsg.Value 

'Display the subject and data 
MsgBox OraObj!subject & OraObj!Data