Skip Headers
Oracle® Database JDBC Developer's Guide,
11g Release 2 (11.2)

Part Number E16548-02
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

25 Oracle Advanced Queuing

Oracle Advanced Queuing (AQ) provides database-integrated message queuing functionality. It is built on top of Oracle Streams and optimizes the functions of Oracle Database so that messages can be stored persistently, propagated between queues on different computers and databases, and transmitted using Oracle Net Services, HTTP, and HTTPS. Because Oracle AQ is implemented in database tables, all operational benefits of high availability, scalability, and reliability are also applicable to queue data. This chapter provides information about the Java interface to Oracle AQ.

Note:

In Oracle Database 11g Release 2 (11.2), support for XMLType queues has been added. Till Oracle Database 11g Release 1 (11.1), supported queue types were RAW, ADT, and ANYDATA queue types.

See Also:

Oracle Streams Advanced Queuing User's Guide

This chapters covers the following topics:

Functionality and Framework of Oracle Advanced Queuing

The Oracle JDBC package oracle.jdbc.aq provides a fast Java interface to AQ. This package contains the following:

These classes and interfaces enable you to access an existing queue, create messages, and enqueue and dequeue messages.

Note:

Oracle JDBC drivers do not provide any API to create a queue. Queues must be created through the DBMS_AQADM PL/SQL package.

See Also:

For more information about the APIs, refer to the Javadoc at
http://download.oracle.com/otn/utilities_drivers/jdbc/111060/doc/javadoc/index.html

Making Changes to the Database

The code snippets used in this chapter assume that user SCOTT is connecting to the database. Therefore, in the database, you must grant the following privileges to SCOTT:

GRANT EXECUTE ON DBMS_AQ to SCOTT;
GRANT EXECUTE ON DBMS_AQADM to SCOTT;
GRANT AQ_ADMINISTRATOR_ROLE TO SCOTT;
GRANT ADMINISTER DATABASE TRIGGER TO SCOTT;

Before you start enqueuing and dequeuing messages, you must have queues in the Database. For this, you must perform the following:

  1. Create a queue table in the following way:

    BEGIN
        DBMS_AQADM.CREATE_QUEUE_TABLE(
                QUEUE_TABLE =>'scott.RAW_SINGLE_QUEUE_TABLE',
                QUEUE_PAYLOAD_TYPE =>'RAW',
                COMPATIBLE => '10.0');
    END;
    
  2. Create a queue in the following way:

    BEGIN
        DBMS_AQADM.CREATE_QUEUE(
                QUEUE_NAME =>'scott.RAW_SINGLE_QUEUE',
                QUEUE_TABLE =>'scott.RAW_SINGLE_QUEUE_TABLE',
    END;
    
  3. Start the queue in the following way:

    BEGIN
        DBMS_AQADM.START_QUEUE(
     'scott.RAW_SINGLE_QUEUE',
    END;
    

It is a good practice to stop the queue and remove the queue tables from the database. You can perform this in the following way:

  1. Stop the queue in the following way:

    BEGIN
        DBMS_AQADM.STOP_QUEUE(
     scott.RAW_SINGLE_QUEUE',
    END;
    
  2. Remove the queue tables from the database in the following way:

    BEGIN
        DBMS_AQADM.DROP_QUEUE_TABLE(
                QUEUE_TABLE =>'scott.RAW_SINGLE_QUEUE_TABLE',
                FORCE => TRUE
    END;
    

AQ Asynchronous Event Notification

A JDBC application can do the following:

Creating Messages

Before you enqueue a message, you must create the message. An instance of a class implementing the AQMessage interface represents an AQ message. An AQ message contains properties (metadata) and a payload (data). Perform the following to create an AQ message:

  1. Create an instance of AQMessageProperties in the following way:

    AQMessageProperties msgprop = AQFactory.createAQMessageProperties();
    
  2. Set the property attributes in the following way:

    msgprop.setCorrelation("mycorrelation");
    msgprop.setExceptionQueue("MY_EXCEPTION_QUEUE");
    msgprop.setExpiration(0);
    msgprop.setPriority(1);
    
  3. Create the AQ message using the AQMessageProperties object in the following way:

    AQMessage mesg = AQFactory.createAQMessage(msgprop);
    
  4. Set the payload in the following way:

    byte[] rawPayload = "Example_Payload".getBytes();
    mesg.setPayload(new oracle.sql.RAW(rawPayload));
    

AQ Message Properties

The properties of the AQ message are represented by an instance of the AQMessageProperties interface. You can set or get the following message properties:

AQ Message Payload

Depending on the type of the queue, the payload of the AQ message can be specified using the setPayload method of the AQMessage interface. The following code snippet illustrates how to set the payload:

...
byte[] rawPayload = "Example_Payload".getBytes();
mesg.setPayload(new oracle.sql.RAW(rawPayload));
...

You can retrieve the payload of an AQ message using the getPayload method or the appropriate getXXXPayload method in the following way:

byte[] payload = mesg.getPayload();

These methods are defined in the AQMessage interface.

Example: Creating a Message and Setting a Payload

This section provides an example that illustrates how to create a message and set a payload.

Example 25-1 Creating a Message and Setting a Payload

This example shows how to Create an instance of AQMessageProperties, set the property attributes, create the AQ message, and set the payload.

AQMessageProperties msgprop = AQFactory.createAQMessageProperties();
    msgprop.setCorrelation("mycorrelation");
    msgprop.setExceptionQueue("MY_EXCEPTION_QUEUE");
    AQAgent ag = AQFactory.createAQAgent();
    ag.setName("MY_SENDER_AGENT_NAME");
    ag.setAddress("MY_SENDER_AGENT_ADDRESS");
    msgprop.setSender(ag);
    // handle multi consumer case:
    if(recipients != null)
      msgprop.setRecipientList(recipients);
    System.out.println(msgprop.toString());
    AQMessage mesg = AQFactory.createAQMessage(msgprop);
byte[] rawPayload = "Example_Payload".getBytes();
mesg.setPayload(new oracle.sql.RAW(rawPayload));

Enqueuing Messages

After you create a message and set the message properties and payload, you can enqueue the message using the enqueue method of the OracleConnection interface. Before you enqueue the message, you can specify some enqueue options. The AQEnqueueOptions class enables you to specify the following enqueue options:

The following code snippet illustrates how to set the enqueue options and enqueue the message:

...
AQEnqueueOptions opt = new AQEnqueueOptions();opt.setRetrieveMessageId(true);
conn.enqueue(queueName, opt, mesg);
...

Dequeuing Messages

Enqueued messages can be dequeued using the dequeue method of the OracleConnection interface. Before you dequeue a message you must set the dequeue options. The AQDequeueOptions class enables you to specify the following dequeue options:

The following code snippet illustrates how to set the dequeue options and dequeue the message:

...
AQDequeueOptions deqopt = new AQDequeueOptions();
deqopt.setRetrieveMessageId(true);
deqopt.setConsumerName(consumerName);
AQMessage msg = conn.dequeue(queueName,deqopt,queueType);

Examples: Enqueuing and Dequeuing

This section provides a few examples that illustrate how to enqueue and dequeue messages.

Example 25-2 illustrates how to enqueue a message, and Example 25-3 illustrates how to dequeue a message.

Example 25-2 Enqueuing a Single Message

This example illustrates how to obtain access to a queue, create a message, and enqueue it.

AQMessageProperties msgprop = AQFactory.createAQMessageProperties();
msgprop.setPriority(1);
msgprop.setExceptionQueue("EXCEPTION_QUEUE");
msgprop.setExpiration(0);
AQAgent agent = AQFactory.createAQAgent();
agent.setName("AGENTNAME");
agent.setAddress("AGENTADDRESS");
msgprop.setSender(agent);
AQMessage mesg = AQFactory.createAQMessage(msgprop);
mesg.setPayload(buffer); // where buffer is a byte array (for a RAW queue)
AQEnqueueOptions options = new AQEnqueueOptions();
conn.enqueue("SCOTT.MY_QUEUE", options, mesg);

Example 25-3 Dequeuing a Single Message

This example illustrates how to obtain access to a queue, set the dequeue options, and dequeue the message.

AQDequeueOptions options = new AQDequeueOptions();
options.setDeliveryFilter(AQDequeueOptions.DeliveryFilter.BUFFERED);
AQMessage mesg = conn.dequeue("SCOTT.MY_QUEUE", options, "RAW");