Operational Interface: Basic Operations, 7 of 19

Enqueuing a Message [Add Payload]

Figure 11-6 Use Case Diagram: Enqueuing a Message [Add Payload]

Text description of adq11qop16.gif follows

Text description of the illustration adq11qop16.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

Usage Notes

To store a payload of type RAW, AQ will create a queue table with LOB column as the payload repository. The maximum size of the payload is determined by which programmatic environment you use to access AQ. For PL/SQL, Java and precompilers the limit is 32K; for the OCI the limit is 4G.

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, ENQUEUE 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, AQOracleQueue.enque

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): Enqueue of Object Type Messages

Note: You may need to set up the following data structures for certain examples to work:

CONNECT system/manager
CREATE USER aq IDENTIFIED BY aq;
GRANT Aq_administrator_role TO aq;
EXECUTE DBMS_AQADM.CREATE_QUEUE_TABLE (
   Queue_table            =>  'aq.objmsgs_qtab',
   Queue_payload_type     =>  'aq.message_typ');
EXECUTE DBMS_AQADM.CREATE_QUEUE ( 
   Queue_name            =>  'aq.msg_queue',
   Queue_table           =>  'aq.objmsgs_qtab');
EXECUTE DBMS_AQADM.START_QUEUE (
   Queue_name         => 'aq.msg_queue',
   Enqueue            => TRUE);
EXECUTE DBMS_AQADM.CREATE_QUEUE_TABLE (
   Queue_table            => 'aq.prioritymsgs_qtab',
   Sort_list              => 'PRIORITY,ENQ_TIME',
   Queue_payload_type     => 'aq.message_typ');
EXECUTE DBMS_AQADM.CREATE_QUEUE (
   Queue_name             => 'aq.priority_msg_queue',
   Queue_table            => 'aq.prioritymsgs_qtab');
EXECUTE DBMS_AQADM.START_QUEUE (
   Queue_name             => 'aq.priority_msg_queue',
   Enqueue                => TRUE);

Enqueue a Single Message and Specify the Queue Name and Payload

/* Enqueue to msg_queue: */
DECLARE
   Enqueue_options     DBMS_AQ.enqueue_options_t;
   Message_properties  DBMS_AQ.message_properties_t;
   Message_handle      RAW(16);
   Message             aq.message_typ;

BEGIN
   Message := aq.message_typ('NORMAL MESSAGE',
      'enqueued to msg_queue first.');

   DBMS_AQ.ENQUEUE(queue_name => 'msg_queue',           
   Enqueue_options            => enqueue_options,       
   Message_properties         => message_properties,     
   Payload                    => message,               
   Msgid                      => message_handle);

   COMMIT;
END;

Enqueue a Single Message and Specify the Priority

/* The queue name priority_msg_queue is defined as an object type queue table. 
   The payload object type is message. The schema of the queue is aq.  */

 /* Enqueue a message with priority 30: */ 
DECLARE 
   Enqueue_options       dbms_aq.enqueue_options_t; 
   Message_properties    dbms_aq.message_properties_t; 
   Message_handle        RAW(16); 
   Message               aq.Message_typ; 
 
BEGIN 
   Message := Message_typ('PRIORITY MESSAGE', 'enqued at priority 30.'); 
 
   message_properties.priority := 30; 
 
   DBMS_AQ.ENQUEUE(queue_name => 'priority_msg_queue', 
   enqueue_options            => enqueue_options, 
   message_properties         => message_properties, 
   payload                    => message, 
   msgid                      => message_handle); 
 
   COMMIT; 
END;

Enqueue a Single Message and Specify a Transformation

/* Enqueue to msg_queue: */
DECLARE
   Enqueue_options     DBMS_AQ.enqueue_options_t;
   Message_properties  DBMS_AQ.message_properties_t;
   Message_handle      RAW(16);
   Message             aq.message_typ;

BEGIN
   Message := aq.message_typ('NORMAL MESSAGE',
      'enqueued to msg_queue first.');

   DBMS_AQ.ENQUEUE(queue_name => 'msg_queue',           
   Enqueue_options            => enqueue_options,       
   Message_properties         => message_properties,
   transformation             => 'AQ.MSG_MAP',    
   Payload                    => message,               
   Msgid                      => message_handle);

   COMMIT;
END;

Where MSG_MAP was created as follows:

BEGIN
   DBMS.TRANSFORM.CREATE_TRANSFORMATION
   (
      schema => 'AQ',
      name =>   'MSG_MAP',
      from_schema => 'AQ',
      from_type => 'PO_ORDER1',
      to_schema => 'AQ',
      to_type => 'PO_ORDER2',
      transformation => 'AQ.MAP_PO_ORDER (source.user_data)'),
END;

Java (JDBC): Enqueue a message (add payload)

/* Setup  */
connect system/manager
create user aq identified by aq;
grant aq_administrator_role to aq;

public static void setup(AQSession aq_sess) throws AQException
{
     AQQueueTableProperty    qtable_prop;
     AQQueueProperty         queue_prop;
     AQQueueTable            q_table;
     AQQueue                 queue;
     AQAgent                 agent;

     qtable_prop = new AQQueueTableProperty("RAW"); 

     q_table = aq_sess.createQueueTable ("aq", "rawmsgs_qtab", qtable_prop);

     queue_prop = new AQQueueProperty();
     queue = aq_sess.createQueue (q_table, "msg_queue", queue_prop);

     queue.start();

     qtable_prop = new AQQueueTableProperty("RAW"); 
     qtable_prop.setMultiConsumer(true);

     qtable_prop.setSortOrder("priority,enq_time");
     q_table = aq_sess.createQueueTable ("aq", "rawmsgs_qtab2", 
					     qtable_prop);

     queue_prop = new AQQueueProperty();
     queue = aq_sess.createQueue (q_table, "priority_msg_queue", queue_prop);

     queue.start();

     agent = new AQAgent("subscriber1", null);

     queue.addSubscriber(agent, null);
}


/* Enqueue a message */
public static void example(AQSession aq_sess) throws AQException, SQLException
{
     AQQueue                  queue;
     AQMessage                message;
     AQRawPayload             raw_payload;
     AQEnqueueOption          enq_option;
     String                   test_data = "new message";
     byte[]                   b_array;
     Connection               db_conn;

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

     /* Get a handle to the queue */
     queue = aq_sess.getQueue ("aq", "msg_queue");

     /* Create a message to contain raw payload: */
     message = queue.createMessage();

     /* Get handle to the AQRawPayload object and populate it with raw data: */
     b_array = test_data.getBytes();

     raw_payload = message.getRawPayload();

     raw_payload.setStream(b_array, b_array.length);

     /* Create a AQEnqueueOption object with default options: */
     enq_option = new AQEnqueueOption();

     /* Enqueue the message: */
     queue.enqueue(enq_option, message);
     
     db_conn.commit();
}


/* Enqueue a message with priority = 5 */
public static void example(AQSession aq_sess) throws AQException, SQLException
{
     AQQueue                  queue;
     AQMessage                message;
     AQMessageProperty        msg_prop;
     AQRawPayload             raw_payload;
     AQEnqueueOption          enq_option;
     String                   test_data = "priority message";
     byte[]                   b_array;
     Connection               db_conn;

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

     /* Get a handle to the queue */
     queue = aq_sess.getQueue ("aq", "msg_queue");

     /* Create a message to contain raw payload: */
     message = queue.createMessage();

     /* Get Message property */
     msg_prop = message.getMessageProperty();

     /* Set priority */
     msg_prop.setPriority(5);

     /* Get handle to the AQRawPayload object and populate it with raw data: */
     b_array = test_data.getBytes();

     raw_payload = message.getRawPayload();

     raw_payload.setStream(b_array, b_array.length);

     /* Create a AQEnqueueOption object with default options: */
     enq_option = new AQEnqueueOption();

     /* Enqueue the message: */
     queue.enqueue(enq_option, message);
     
     db_conn.commit();
}

Visual Basic (OO4O): Enqueue a message

Enqueuing messages of type objects

'Prepare the message. MESSAGE_TYPE is a user defined type
' in the "AQ" schema 
Set OraMsg = Q.AQMsg(1, "MESSAGE_TYPE") 
Set OraObj = DB.CreateOraObject("MESSAGE_TYPE") 

OraObj("subject").Value = "Greetings from OO4O" 
OraObj("text").Value = "Text of a message originated from OO4O" 

Set OraMsg.Value = OraObj 
Msgid = Q.Enqueue

Enqueuing messages of type RAW

'Create an OraAQ object for the queue "DBQ" 
Dim Q as object 
Dim Msg as object 
Dim OraSession as object 
Dim DB as object 

Set OraSession = CreateObject("OracleInProcServer.XOraSession") 
Set OraDatabase = OraSession.OpenDatabase(mydb, "scott/tiger" 0&) 
Set Q = DB.CreateAQ("DBQ") 

'Get a reference to the AQMsg object 
Set Msg = Q.AQMsg 
Msg.Value = "Enqueue the first message to a RAW queue." 

'Enqueue the message 
Q.Enqueue() 

'Enqueue another message.  

Msg.Value = "Another message" 
Q.Enqueue() 

'Enqueue a message with non-default properties. 
Msg.Priority = ORAQMSG_HIGH_PRIORITY 
Msg.Delay = 5 
Msg.Value = "Urgent message" 
Q.Enqueue() 
Msg.Value = "The visibility option used in the enqueue call is 
             ORAAQ_ENQ_IMMEDIATE" 
Q.Visible = ORAAQ_ENQ_IMMEDIATE 
Msgid = Q.Enqueue 

'Enqueue Ahead of message Msgid_1 
Msg.Value = "First Message to test Relative Message id" 
Msg.Correlation = "RELATIVE_MESSAGE_ID" 

Msgid_1 = Q.Enqueue 
Msg.Value = "Second message to test RELATIVE_MESSAGE_ID is queued 
             ahead of the First Message " 
OraAq.relmsgid = Msgid_1 
Msgid = Q.Enqueue