2
Package oracle.AQ

This chapter describes the Oracle Java interfaces and classes contained in package oracle.AQ. These are based on current PL/SQL interfaces for Oracle Advanced Queuing (AQ).

This chapter contains these sections:

Package oracle.AQ Description

The Java AQ API supports both the administrative and operational features of Oracle Advanced Queueing. In developing Java programs for messaging applications, you use JDBC to open a connection to the database and then the interfaces in oracle.AQ, which contains the Java AQ API for message queuing. You need not use only PL/SQL interfaces.

Note:

If the Java classes are not-preloaded, you can load them by connecting as SYS and loading the $ORACLE_HOME/rdbms/admin/initjms.sql script.

Accessing Java AQ Classes

The Java AQ classes are located in $ORACLE_HOME/rdbms/jlib/aqapi.jar. In Oracle9i Release 2 (9.2), rdbms/jlib/*.jar conforms to the JMS 1.0.2b standard published by Sun Microsystems. These classes can be used with any Oracle8i or Oracle9i JDBC driver.

For JDK 1.3 you must include the following classes in the CLASSPATH:

$ORACLE_HOME/rdbms/jlib/aqapi13.jar
$ORACLE_HOME/lib/jndi.jar
$ORACLE_HOME/jdbc/lib/classes12.zip

For JDK 1.2 you must include the following classes in the CLASSPATH:

$ORACLE_HOME/rdbms/jlib/aqapi12.jar
$ORACLE_HOME/lib/jndi.jar
$ORACLE_HOME/jdbc/lib/classes12.zip

For JDK 1.1 you must include the following classes in the CLASSPATH:

$ORACLE_HOME/rdbms/jlib/aqapi11.jar
$ORACLE_HOME/lib/jndi.jar
$ORACLE_HOME/jdbc/lib/classes111.zip

Oracle9i Application Developer's Guide - Advanced Queuing, Appendix A contains more examples in addition to those contained in this chapter.

Setup for oracle.AQ Examples

1. Create an oracle.AQ user named `aqjava`

An aqjava user is set up as follows:

CONNECT sys/change_on_install AS sysdba

DROP USER aqjava CASCADE;
GRANT CONNECT, RESOURCE, AQ_ADMINISTRATOR_ROLE TO aqjava

   IDENTIFIED BY aqjava;
GRANT EXECUTE ON SYS.DBMS_AQADM TO aqjava;
GRANT EXECUTE ON SYS.DBMS_AQ TO aqjava;
GRANT EXECUTE ON SYS.DBMS_AQIN TO aqjava;
CONNECT aqjava/aqjava

2. Set up main class

Next, set up the main class from which you will call subsequent examples and handle exceptions. The main class for the examples is named test_aqjava.

import java.sql.*;
import oracle.AQ.*;

public class test_aqjava
{
   public static void main(String args[]) 
   {
      AQSession  aq_sess = null;

      try 
      {
         aq_sess = createSession(args);

   /* now run the test: */
        runTest(aq_sess);
      }
      catch (Exception ex)
      {
         System.out.println("Exception-1: " + ex); 
         ex.printStackTrace(); 
      }  
   }
}

3. Create an AQ Session

Next, create an AQ Session for the aqjava user as shown in the previous step for AQDriverManager:

public static AQSession createSession(String args[]) 
   {
      Connection db_conn;
      AQSession  aq_sess = null;

      try 
      {
    
         Class.forName("oracle.jdbc.driver.OracleDriver");
    /* your actual hostname, port number, and SID will 
    vary from what follows. Here we use 'dlsun736,' '5521,'
    and 'test,' respectively: */

         db_conn =
                  DriverManager.getConnection(
                  "jdbc:oracle:thin:@dlsun736:5521:test", 
                  "aqjava", "aqjava");

         System.out.println("JDBC Connection opened "); 
         db_conn.setAutoCommit(false);
                 
    /* Load the Oracle9i AQ driver: */
         Class.forName("oracle.AQ.AQOracleDriver");
    /* Create an AQ Session: */
         aq_sess = AQDriverManager.createAQSession(db_conn);
         System.out.println("Successfully created AQSession ");  
      }
      catch (Exception ex)
      {
         System.out.println("Exception: " + ex); 
         ex.printStackTrace();
      }
      return aq_sess;
   }

Package oracle.AQ Summary

Table 2-1 Package oracle.AQ member summary

Member	Description
Classes, Common	-
AQConstants	Constants used in AQ operations.
AQAgent	AQ Agent.
AQDriverManager	Driver Manager for various AQ drivers.
AQEnqueueOption	AQ Enqueue options.
AQDequeueOption	AQ Dequeue options.
AQMessageProperty	AQ Message properties.
AQQueueProperty	AQ Queue properties.
AQQueueTableProperty	AQ Queue Table properties.
Classes, Oracle8i (These classes are not described in this manual)	-
AQOracleSession	Oracle server implementation of AQSession.
AQOracleMessage	Oracle Server implementation of AQMessage.
AQOracleDriver	Oracle server implementation of AQDriver.
AQOracleQueue	Oracle server implementation of AQQueue.
AQOracleQueueTable	Oracle server implementation of AQQueueTable.
AQOracleRawPayload	Oracle server implementation of AQRawPayload.
AQOracleObjectPayload	Oracle server implementation of AQObjectPayload.
Exceptions	-
AQException	Raised when the user encounters any error while using the Java AQ API.
AQOracleSQLException	Raised for all errors that occur while performing SQL.

AQDriverManager

The various implementations of the Java AQ API are managed through a driver manager interface named AQDriverManager. Both Oracle Lite and Oracle9i have an AQDriver that is registered with the AQDriverManager. The driver manager is used to create an AQSession that can be used to perform messaging tasks.

When the AQDriverManager.createAQSession() method is invoked, it calls the appropriate AQDriver (amongst the registered drivers) depending on the parameter passed to the createAQSession() call.

The Oracle9i AQDriver expects a valid JDBC connection to be passed in as a parameter to create an AQSession. Users must have the execute privilege on the DBMS_AQIN package in order to use the AQ Java interfaces. Users can also acquire these rights through the AQ_USER_ROLE or the AQ_ADMINSTRATOR_ROLE. Users will also need the appropriate system and queue privileges for Oracle9i-style queue tables.

Methods

getDrivers

public static java.util.Vector getDrivers()

This method Returnsthe list of drivers registered with the driver manager. It Returnsa Vector of strings containing the names of the registered drivers.

getAQSession

public static AQSession getAQSession (java.lang.Object conn)
   throws AQException

This method creates an AQSession.

Parameter

conn

If the user is using the AQOracleDriver, then the object passed in must be a valid JDBC connection.

Multithreaded Program Support

Currently Java AQ objects are not thread safe. Therefore, methods on AQSession, AQQueueTable, AQQueue and other AQ objects should not be called concurrently from different threads. You can pass these objects between threads, but the program must ensure that the methods on these AQ objects are not invoked concurrently.

We recommend that multithreaded programs create a different AQSession in each thread (using the same or a different JDBC connection) and get new queue table and queue handles using the getQueueTable and getQueue methods in AQSession.

Loading the Java AQ Driver

To create an AQSession, you must first open a JDBC connection. Then you must load the AQDriver that you need to use in the application. With Oracle9i, the driver is loaded using the Class.forName("oracle.AQ.AQOracleDriver") command.

Note that the driver needs to be loaded only once (before the first createAQSession call). Loading the driver multiple times will have no effect. For more information, see "Setup for oracle.AQ Examples".

Example

Connection db_conn;       /* JDBC connection */
AQSession  aq_sess;       /* AQSession */

/* JDBC setup and connection creation: */
Class.forName("oracle.jdbc.driver.OracleDriver");
db_conn = DriverManager.getConnection (
   "jdbc:oracle:oci8:@", "aquser", "aquser");
db_conn.setAutoCommit(false);

/* Load the Oracle9i AQ driver: */
Class.forName("oracle.AQ.AQOracleDriver");
/* Create an AQ Session: */
aq_sess = AQDriverManager.createAQSession(db_conn);

In general, use only the interfaces and classes that are common to both implementations. This will ensure that your applications are portable between Oracle9i and Oracle Lite AQ implementations.

Additionally, oracle.AQ classes should only be used when you need a method that is not available in the common interfaces. Note that since the AQQueue interface extends AQQueueAdmin, all queue administrative and operational functionality is available via AQQueue.

AQSession

Methods

createQueueTable

public AQQueueTable createQueueTable(java.lang.String owner,
                                     java.lang.String name,
                   AQQueueTableProperty property) throws AQException

This method creates a new queue table in a particular user's schema according to the properties specified in the AQQueueTableProperty object passed in.

Parameter	Description
`owner`	schema (user) in which to create the queue table
`q_name`	name of the queue table
`property`	queue table properties

Returns

AQQueueTable object

getQueueTable

public AQQueueTable getQueueTable(java.lang.String owner,
                                  java.lang.String name)

This method is used to get a handle to an existing queue table.

Parameter	Description
`owner`	schema (user) in which the queue table resides
`name`	name of the queue table

Returns

AQQueueTable object

createQueue

public AQQueue createQueue(AQQueueTable q_table,
                           java.lang.String q_name,
                      AQQueueProperty q_property) throws AQException

This method creates a queue in a queue_table with the specified queue properties. It uses the same schema name that was used to create the queue table.

Parameter	Description
`q_table`	queue table in which to create queue
`name`	name of the queue to be created
`q_property`	queue properties

Returns

AQQueue object

getQueue

public AQQueue getQueue(java.lang.String owner,
                        java.lang.String name)

This method can be used to get a handle to an existing queue.

Parameter	Description
`owner`	schema (user) in which the queue table resides
`name`	name of the queue

Returns

AQQueue object

getDB Connection

public java.sql.Connection getDBConnection()

This method can be used to get the underlying JDBC connection from an AQ session object

This method is available only in the Oracle server implementation of AQSession. Hence the AQSession object must be cast to AQOracleSession before calling this method.

Example

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

listen

public AQAgent listen(AQAgent[] agent_list,
                      int wait_time)

This method can be used to listen to multiple queues for messages

Parameter Description

Parameter	Description
`agent_list`	List of agents to listen for. * For single consumer queues, the name field of the AQAgent must be set to NULL and the address field must contain the [schema].[queue_name]. * For multi consumer queues, the name field of the AQAgent must be contain the consumer_name and the address field must have the [schema].[queue_name].
`wait_time`	time-out for the listen call (in seconds). To wait forever, this must be set to AQConstants.WAIT_FOREVER.

agent_list

List of agents to listen for.

* For single consumer queues, the name field of the AQAgent must be set to NULL and the address field must contain the [schema].[queue_name].

* For multi consumer queues, the name field of the AQAgent must be contain the consumer_name and the address field must have the [schema].[queue_name].

wait_time

time-out for the listen call (in seconds). To wait forever, this must be set to AQConstants.WAIT_FOREVER.

Returns

Agent with a message available for consumption

Throws

AQException if listen failed due to time-out (ORA-25254) or another error

Example

1. Create a queue table and a queue

With the runTest class, called from the AQDriverManager main class, create a queue table and queue for the aqjava user.

public static void runTest(AQSession aq_sess) throws AQException
{
    AQQueueTableProperty     qtable_prop;
    AQQueueProperty          queue_prop;
    AQQueueTable             q_table;
    AQQueue                  queue;
   
 /* Create a AQQueueTableProperty object (payload type - RAW): */
    qtable_prop = new AQQueueTableProperty("RAW"); 
   
 /* Create a queue table called aq_table1 in aqjava schema: */
    q_table = aq_sess.createQueueTable ("aqjava", "aq_table1",
        qtable_prop);
    System.out.println("Successfully created aq_table1 in aqjava
        schema");

 /* Create a new AQQueueProperty object: */
   queue_prop = new AQQueueProperty();
   
 /* Create a queue called aq_queue1 in aq_table1: */
   queue = aq_sess.createQueue (q_table, "aq_queue1", queue_prop);
  System.out.println("Successfully created aq_queue1 in aq_table1");
}

2. Get a handle to an existing queue table and queue

public static void runTest(AQSession aq_sess) throws AQException
{
    AQQueueTable            q_table;
    AQQueue                 queue;
    
 /* Get a handle to queue table - aq_table1 in aqjava schema: */
    q_table = aq_sess.getQueueTable ("aqjava", "aq_table1");
    System.out.println("Successful getQueueTable");  
    
 /* Get a handle to a queue - aq_queue1 in aqjava schema: */
    queue = aq_sess.getQueue ("aqjava", "aq_queue1");
    System.out.println("Successful getQueue");
}

AQConstants

This class contains some constants used in the java AQ API.

Visibility constants

VISIBILITY_IMMEDIATE
public static final int VISIBILITY_IMMEDIATE

VISIBILITY_ONCOMMIT
public static final int VISIBILITY_ONCOMMIT

Payload type, Object

RAW_TYPE_PAYLOAD
public static final int RAW_TYPE_PAYLOAD

Payload type, RAW

OBJECT_TYPE_PAYLOAD
public static final int OBJECT_TYPE_PAYLOAD

AQAgent

This object specifies the producer or a consumer of a message.

Constructor

public AQAgent(java.lang.String name,
               java.lang.String address,
               double protocol)

public AQAgent(java.lang.String name,
               java.lang.String address)

There are two implementations of the constructor, each of which allocates a new AQAgent with the specified parameters.

Parameter	Description
`name`	agent name
`address`	agent address
`protocol`	agent protocol (required only in the first constructor); default is 0

Methods

getName

public java.lang.String getName() throws AQException

This method gets the agent name.

setName

public void setName(java.lang.String name) throws AQException

This method sets the agent name.

Parameter	Description
`name`	Agent name

getAddress

public java.lang.String getAddress() throws AQException

This method gets the agent address.

setAddress

public void setAddress(java.lang.String address) throws AQException

This method sets the agent address.

Parameter	Description
`address`	queue at a specific destination

getProtocol

public int getProtocol() throws AQException

This method gets the agent protocol.

setProtocol

public void setProtocol(int protocol) throws AQException

This method sets the agent protocol.

Parameter	Description
`protocol`	Agent protocol

AQQueueTableProperty

This class represents queue table properties.

Constants

public static final int NONE
public static final int TRANSACTIONAL

Constructor

public AQQueueTableProperty(java.lang.String p_type)

This method creates an AQQueueTableProperty object with default property values and the specified payload type.

Parameter	Description
`p_type`	payload type: this is "`RAW`" for queue tables that will contain raw payloads or the object ADT type for queue tables that will contain structured payloads

Methods

getPayloadType

public java.lang.String getPayloadType() throws AQException

This method Returns"RAW" for raw payloads or the object type for object payloads.

setPayloadType

public void setPayloadType(java.lang.String p_type) throws AQException

This method is used to set the payload type.

Parameter	Description
`p_type`	payload type: this is "RAW" for queue tables that will contain raw payloads or the object (ADT) type for queue tables that will contain structured payloads

setStorageClause

public void setStorageClause(java.lang.String s_clause) throws AQException

This method is used to set the storage clause to be used to create the queue table.

Parameter	Description
`s_clauses`	storage parameter: this clause is used in the ``CREATE TABLE`' statement when the queue table is created

getSortOrder

public java.lang.String getSortOrder() throws AQException

This method gets the sort order that is used.

Returns

The sort order used

setSortOrder

public void setSortOrder(java.lang.String s_order) throws AQException

This method sets the sort order to be used.

Parameter	Description
`s_order`	specifies the columns to be used as the `sort_key` in ascending order; the string has the format <sort_column1, sort_column2>; the allowed columns name are `priority` and `enq_time.`

isMulticonsumerEnabled

public boolean isMulticonsumerEnabled() throws AQException

This method queries whether the queues created in the table can have multiple consumers per message or not.

Returns

TRUE if the queues created in the table can have multiple consumers per message.

FALSE if the queues created in the table can have only one consumer per message.

setMultiConsumer

public void setMultiConsumer(boolean enable) throws AQException

This method determines whether the queues created in the table can have multiple consumers per message or not.

Parameter Description

Parameter	Description
`enable`	`FALSE` if the queues created in the table can have only one consumer per message `TRUE` if the queues created in the table can have multiple consumers per message

enable

FALSE if the queues created in the table can have only one consumer per message

TRUE if the queues created in the table can have multiple consumers per message

getMessageGrouping

public int getMessageGrouping() throws AQException

This method is used to get the message grouping behavior for the queues in this queue table.

Returns

NONE: each message is treated individually

TRANSACTIONAL: all messages enqueued as part of one transaction are considered part of the same group and can be dequeued as a group of related messages.

setMessageGrouping

public void setMessageGrouping(int m_grouping) throws AQException

This method is used to set the message grouping behavior for queues created in this queue table.

Parameter	Description
`m_grouping`	`NONE` or `TRANSACTIONAL`

getComment

public java.lang.String getComment() throws AQException

This method gets the queue table comment.

setComment

public void setComment(java.lang.String qt_comment) throws AQException

This method sets a comment.

Parameter	Description
`qt_comment`	comment

getCompatible

public java.lang.String getCompatible() throws AQException

This method gets the compatible property.

setCompatible

public void setCompatible(java.lang.String qt_compatible)
   throws AQException

This method sets the compatible property.

Parameter	Description
`qt_compatible`	compatible property

getPrimaryInstance

public int getPrimaryInstance() throws AQException

This method gets the primary instance.

setPrimaryInstance

public void setPrimaryInstance(int inst) throws AQException

This method sets the primary instance.

Parameter	Description
`inst`	primary instance

getSecondaryInstance

public int getSecondaryInstance() throws AQException

This method gets the secondary instance.

setSecondaryInstance

public void setSecondaryInstance(int inst) throws AQException

This method sets the secondary instance.

Parameter	Description
`inst`	secondary instance

Example

To run this example, first set up the test_aqjava class as described in "Setup for oracle.AQ Examples".

1. Create a queue table property object with raw payload type

public static void runTest(AQSession aq_sess) throws AQException
 {
     AQQueueTableProperty qtable_prop;

 /* Create AQQueueTable Property object: */
     qtable_prop = new AQQueueTableProperty("RAW");
     qtable_prop.setSortOrder("PRIORITY");
}

2. Create a queue table property object with raw payload type (for 8.1 style queues)

 public static void runTest(AQSession aq_sess) throws AQException
 {
     AQQueueTableProperty qtable_prop;

 /* Create AQQueueTable Property object: */
     qtable_prop = new AQQueueTableProperty("RAW");
     qtable_prop.setComment("Qtable with raw payload");
     qtable_prop.setCompatible("8.1");
}

3. Create a queue table property object with "PERSON" payload type (ADT type):

 public static void runTest(AQSession aq_sess) throws AQException
{
     AQQueueTableProperty qtable_prop;
     qtable_prop = new AQQueueTableProperty("PERSON");
     qtable_prop.setComment("Qtable with Person ADT payload");
     qtable_prop.setMessageGrouping(TRANSACTIONAL);
}

AQQueueProperty

This class represents queue properties.

Constants

public static final int NORMAL_QUEUE
public static final int EXCEPTION_QUEUE
public static final int INFINITE   /* infinite retention */

Constructor

public AQQueueProperty()

This method creates a new AQQueueProperty object with default property values.

Methods

getQueueType

public int getQueueType() throws AQException

This method gets the queue type.

Returns

NORMAL_QUEUE or EXCEPTION_QUEUE

setQueueType

public void setQueueType(int q_type) throws AQException

This method is used to set the queue type.

Parameter	Description
`q_type`	`NORMAL_QUEUE` or `EXCEPTION_QUEUE`

getMaxRetries

public int getMaxRetries() throws AQException

This method gets the maximum retries for dequeue with REMOVE mode.

setMaxRetries

public void setMaxRetries(int retries) throws AQException
public void setMaxRetries(Integer retries) throws AQException

This method sets the maximum retries for dequeue with REMOVE mode.

Parameter	Description
`retries`	maximum retries for dequeue with REMOVE mode; specifying `NULL` will use the default. The default applies to single consumer queues and 8.1. compatible multiconsumer queues. `Max_retries` is not supported for 8.0 compatible multiconsumer queues.

setRetryInterval

public void setRetryInterval(double interval) throws AQException
public void setRetryInterval(Double interval) throws AQException

This method sets the retry interval, that is the time before this message is scheduled for processing after an application rollback. Default is 0.

Parameter	Description
`interval`	retry interval; specifying `NULL` will use the default

getRetryInterval

public double getRetryInterval() throws AQException

This method gets the retry interval.

getRetentionTime

public double getRetentionTime() throws AQException

This method gets the retention time.

setRetentionTime

public void setRetentionTime(double r_time) throws AQException
public void setRetentionTime(Double r_time) throws AQException

This method gets the retention time.

Parameter
`r_time`	retention time; specifying `NULL` will use the default

getComment

public java.lang.String getComment() throws AQException

This method gets the queue comment.

setComment

public void setComment(java.lang.String qt_comment) throws AQException

This method sets the queue comment.

Parameter	Description
qt_comment	queue comment

Example

To use this example, first set up the test_aqjava class as described in the Setup for oracle.AQ Examples section on .

Create a AQQueueProperty object

 {
     AQQueueProperty         q_prop;
     q_prop = new AQQueueProperty();
     q_prop.setRetentionTime(15); /* set retention time */
     q_prop.setRetryInterval(30); /* set retry interval */
}

AQQueueTable

The AQQueueTable interface contains methods for queue table administration.

Methods

getOwner

public java.lang.String getOwner() throws AQException

This method gets the queue table owner.

getName

public java.lang.String getName() throws AQException

This method gets the queue table name.

getProperty

public AQQueueTableProperty getProperty() throws AQException

This method gets the queue table properties.

Returns

AQQueueTableProperty object

drop

public void drop(boolean force) throws AQException

This method drops the current queue table.

Parameter Description

Parameter	Description
force	`FALSE`: this operation will not succeed if there are any queues in the queue table (the default) `TRUE`: all queues in the queue table are stopped and dropped automatically

force

FALSE: this operation will not succeed if there are any queues in the queue table (the default)

TRUE: all queues in the queue table are stopped and dropped automatically

alter

public void alter(java.lang.String comment,
                  int primary_instance,
                  int secondary_instance) throws AQException
public void alter(java.lang.String comment) throws AQException

This method is used to alter queue table properties.

Parameter	Description
`comment`	new comment
`primary_instance`	new value for primary instance
`secondary_instance`	new value for secondary instance

createQueue

public AQQueue createQueue(java.lang.String queue_name,
                      AQQueueProperty q_property) throws AQException

This method is used to create a queue in this queue table.

Parameter	Description
`queue_name`	name of the queue to be created
`q_property`	queue properties

Returns

AQQueue object

dropQueue

public void dropQueue(java.lang.String queue_name) throws AQException

This method is used to drop a queue in this queue table.

Parameter	Description
queue_name	name of the queue to be dropped

Example

To run this example, first set up the test_aqjava class as described in the "Setup for oracle.AQ Examples" section .

1. Create a queue table and a queue

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

 /* Create a AQQueueTable property object (payload type - RAW): */
   qtable_prop = new AQQueueTableProperty("RAW"); 
 
 /* Create a queue table called aq_table2 in aquser schema: */
   qtable = aq_sess.createQueueTable ("aquser", "aq_table2", qtable_prop);
   System.out.println("Successfully createQueueTable");  

 /* Create a new AQQueueProperty object: */
   queue_prop = new AQQueueProperty();

 /* Create a queue called aq_queue2 in aq_table2: */
   queue = qtable.createQueue ("aq_queue2", queue_prop);
   System.out.println("Successful createQueue");  
}

2. Alter queue table, get properties and drop the queue table

{
     AQQueueTableProperty    qtable_prop;
     AQQueueTable            q_table;
     
 /*Get a handle to the queue table called aq_table2 in aquser schema: */
     q_table = aq_sess.getQueueTable ("aqjava", "aq_table2");
     System.out.println("Successful getQueueTable");  
 /* Get queue table properties: */
     qtable_prop = q_table.getProperty();

 /* Alter the queue table: */
     q_table.alter("altered queue table");
     
 /* Drop the queue table (and automatically drop queues inside it): */
     q_table.drop(true);
     System.out.println("Successful drop"); 
}

Note:

Queues can be created via the AQSession.createQueue or the AQQueueTable.createQueue interfaces. The former expects an AQQueueTable object as a parameter in addition to the queue_name and queue properties.

AQQueueAdmin

Methods

start

public void start(boolean enqueue,
                  boolean dequeue) throws AQException

This method is used to enable enqueue and dequeue on this queue.

Parameter Description

Parameter	Description
`enqueue`	`TRUE` -- enable enqueue on this queue `FALSE` -- leave current setting unchanged
`dequeue`	`TRUE` -- enable dequeue on this queue `FALSE` -- leave current setting unchanged

enqueue

TRUE -- enable enqueue on this queue

FALSE -- leave current setting unchanged

dequeue

TRUE -- enable dequeue on this queue

FALSE -- leave current setting unchanged

startEnqueue

public void startEnqueue() throws AQException

This method is used to enable enqueue on this queue. This is equivalent to start(TRUE, FALSE)

startDequeue

public void startEnqueue() throws AQException

This method is used to enable dequeue on this queue. This is equivalent to start(FALSE, TRUE).

stop

public void stop(boolean enqueue,
                 boolean dequeue,
                 boolean wait) throws AQException

This method is used to disable enqueue/dequeue on this queue.

Parameter Description

Parameter	Description
`enqueue`	`TRUE` -- disable enqueue on this queue `FALSE` -- leave current setting unchanged
`dequeue`	`TRUE` -- disable dequeue on this queue `FALSE` -- leave current setting unchanged
`wait`	`TRUE` -- wait for outstanding transactions to complete `FALSE` -- return immediately either with a success or an error

enqueue

TRUE -- disable enqueue on this queue

FALSE -- leave current setting unchanged

dequeue

TRUE -- disable dequeue on this queue

FALSE -- leave current setting unchanged

wait

TRUE -- wait for outstanding transactions to complete

FALSE -- return immediately either with a success or an error

stopEnqueue

public void stopEnqueue(boolean wait) throws AQException

This method is used to disable enqueue on a queue. This is equivalent to stop(TRUE, FALSE, wait).

Parameter Description

Parameter	Description
`wait`	`TRUE` -- wait for outstanding transactions to complete `FALSE` -- return immediately either with a success or an error

wait

TRUE -- wait for outstanding transactions to complete

FALSE -- return immediately either with a success or an error

stopDequeue

public void stopDequeue(boolean wait) throws AQException

This method is used to disable dequeue on a queue. This is equivalent to stop(FALSE, TRUE, wait).

Parameter Description

Parameter	Description
`wait`	`TRUE` -- wait for outstanding transactions to complete `FALSE` -- return immediately either with a success or an error

wait

TRUE -- wait for outstanding transactions to complete

FALSE -- return immediately either with a success or an error

drop

public void drop() throws AQException

This method is used to drop a queue

alterQueue

public void alterQueue(AQQueueProperty property) throws AQException

This method is used to alter queue properties

Parameter	Description
`property`	`AQQueueProperty` object with new property values. Note that only `max_retries`, `retry_delay`, `retention_time` and `comment` can be altered.

addSubscriber

public void addSubscriber(AQAgent subscriber,
                         java.lang.String rule) throws AQException

This method is used to add a subscriber for this queue.

Parameter	Description
`subscriber`	the `AQAgent` on whose behalf the subscription is being defined
`rule`	a conditional expression based on message properties, and the message data properties

removeSubscriber

public void removeSubscriber(AQAgent subscriber) throws AQException

This method removes a subscriber from a queue.

Parameter	Description
`subscriber`	the `AQAgent` to be removed

alterSubscriber

public void alterSubscriber(AQAgent subscriber,
                           java.lang.String rule) throws AQException

This method alters properties for a subscriber to a queue.

Parameter	Description
`subscriber`	the `AQAgent` whose subscription is being altered
`rule`	a conditional expression based on message properties, the message data properties

grantQueuePrivilege

public void grantQueuePrivilege(java.lang.String privilege,
                                java.lang.String grantee, 
                            boolean grant_option) throws AQException
public void grantQueuePrivilege(java.lang.String privilege,
                        java.lang.String grantee) throws AQException

This method is used to grant queue privileges to users and roles. The method has been overloaded. The second implementation is equivalent to calling the first implementation with grant_option = FALSE.

Parameter Description

Parameter	Description
`privilege`	specifies the privilege to be granted`: ENQUEUE`, `DEQUEUE` or `ALL`
`grantee`	specifies the grantee(s); the grantee(s) can be a user, a role or the `PUBLIC` roles
`grant_option`	`TRUE` -- the grantee is allowed to use this method to grant access to others `FALSE` -- default

privilege

specifies the privilege to be granted: ENQUEUE, DEQUEUE or ALL

grantee

specifies the grantee(s); the grantee(s) can be a user, a role or the PUBLIC roles

grant_option

TRUE -- the grantee is allowed to use this method to grant access to others

FALSE -- default

revokeQueuePrivilege

public void revokeQueuePrivilege(java.lang.String privilege,
                        java.lang.String grantee) throws AQException

This method is used to revoke a queue privilege.

Parameter	Description
`privilege`	specifies the privilege to be revoked`: ENQUEUE`, `DEQUEUE` or `ALL`
`grantee`	specifies the grantee(s); the grantee(s) can be a user, a role or the `PUBLIC` roles

schedulePropagation

public void schedulePropagation(java.lang.String destination,
                                java.util.Date start_time,
                                java.lang.Double duration,
                                java.lang.String next_time,
                        java.lang.Double latency) throws AQException

This method is used to schedule propagation from a queue to a destination identified by a database link.

Parameter	Description
`destination`	specifies the destination database link. Messages in the source queue for recipients at the destination will be propagated. `NULL` => destination is the local database and messages will be propagated to all other queues in the local database. Maximum length for this field is 128 bytes. If the name is not fully qualified, the default domain name is used.
`start_time`	specifies the initial start time for the propagation window for messages from this queue to the destination. `NULL` => start time is current time.
`duration`	specifies the duration of the propagation window in seconds. `NULL` => propagation window is forever or until propagation is unscheduled
`next_time`	date function to compute the start of the next propagation window from the end of the current window. (e.g use "`SYSDATE`+ 1 - duration/86400" to start the window at the same time everyday. `NULL` => propagation will be stopped at the end of the current window
`latency`	maximum wait, in seconds, in the propagation window for the message to be propagated after it is enqueued. `NULL` => use default value (60 seconds)

unschedulePropagation

public void unschedulePropagation(java.lang.String destination) 
   throws AQException

This method is used to unschedule a previously scheduled propagation of messages from the current queue to a destination identified by a specific database link.

Parameter	Description
destination	specifies the destination database link. `NULL` => destination is the local database.

alterPropagationSchedule

public void alterPropagationSchedule(java.lang.String destination,
                                     java.lang.Double duration,
                                     java.lang.String next_time,
                        java.lang.Double latency) throws AQException

This method is used to alter a propagation schedule.

Parameter	Description
destination	specifies the destination database link. `NULL` => destination is the local database.
duration	specifies the duration of the propagation window in seconds. `NULL` => propagation window is forever or until propagation is unscheduled
next_time	date function to compute the start of the next propagation window from the end of the current window. (e.g use "`SYSDATE`+ 1 - duration/86400" to start the window at the same time everyday. `NULL` => propagation will be stopped at the end of the current window
latency	maximum wait, in seconds, in the propagation window for the message to be propagated after it is enqueued. `NULL` => use default value (60 seconds)

enablePropagationSchedule

public void enablePropagationSchedule(java.lang.String destination) 
   throws AQException

This method is used to enable a propagation schedule.

Parameter	Description
destination	specifies the destination database link. `NULL` => destination is the local database.

disablePropagationSchedule

public void disablePropagationSchedule(java.lang.String destination) 
   throws AQException

This method is used to disable a propagation schedule.

Parameter	Description
destination	specifies the destination database link. `NULL` => destination is the local database.

Examples

Set up the test_aqjava class. For more information, see "Setup for oracle.AQ Examples"

1. Create a queue and start enqueue/dequeue

{
     AQQueueTableProperty    qtable_prop;
     AQQueueProperty         queue_prop;
     AQQueueTable            q_table;
     AQQueue                 queue;

 /* Create a AQQueueTable property object (payload type - RAW): */
     qtable_prop = new AQQueueTableProperty("RAW"); 
    qtable_prop.setCompatible("8.1");

 /* Create a queue table called aq_table3 in aqjava schema: */
     q_table = aq_sess.createQueueTable ("aqjava","aq_table3", qtable_prop);
     System.out.println("Successful createQueueTable");  

 /* Create a new AQQueueProperty object: */
     queue_prop = new AQQueueProperty();

 /* Create a queue called aq_queue3 in aq_table3: */
     queue = aq_sess.createQueue (q_table, "aq_queue3", queue_prop);
     System.out.println("Successful createQueue");  

 /* Enable enqueue/dequeue on this queue: */
     queue.start();
     System.out.println("Successful start queue");  
   
 /* Grant enqueue_any privilege on this queue to user scott: */
     queue.grantQueuePrivilege("ENQUEUE", "scott"); 
     System.out.println("Successful grantQueuePrivilege");  
}

2. Create a multi-consumer queue and add subscribers

public static void runTest(AQSession aq_sess) throws AQException
{
     AQQueueTableProperty    qtable_prop;
     AQQueueProperty         queue_prop;
     AQQueueTable            q_table;
     AQQueue                 queue;
     AQAgent                 subs1, subs2;

 /* Create a AQQueueTable property object (payload type - RAW): */
     qtable_prop = new AQQueueTableProperty("RAW"); 
     System.out.println("Successful setCompatible");  

 /* Set multiconsumer flag to true: */
     qtable_prop.setMultiConsumer(true);

 /* Create a queue table called aq_table4 in aqjava schema: */
     q_table = aq_sess.createQueueTable ("aqjava","aq_table4", qtable_prop);
     System.out.println("Successful createQueueTable");  

 /* Create a new AQQueueProperty object: */
     queue_prop = new AQQueueProperty();

     /* Create a queue called aq_queue4 in aq_table4 */
     queue = aq_sess.createQueue (q_table, "aq_queue4", queue_prop);
     System.out.println("Successful createQueue");  

 /* Enable enqueue/dequeue on this queue: */
     queue.start();
     System.out.println("Successful start queue");  

 /* Add subscribers to this queue: */
     subs1 = new AQAgent("GREEN", null, 0);
     subs2 = new AQAgent("BLUE", null, 0);

     queue.addSubscriber(subs1, null); /* no rule   */
     System.out.println("Successful addSubscriber 1");  

     queue.addSubscriber(subs2, "priority < 2"); /* with rule */
     System.out.println("Successful addSubscriber 2");  
}

AQQueue

This interface supports the operational interfaces of queues. AQQueue extends AQQueueAdmin. Hence, you can also use administrative functions through this interface.

Methods

getOwner

public java.lang.String getOwner() throws AQException

This method gets the queue owner.

getName

public java.lang.String getName() throws AQException

This method gets the queue name.

getQueueTableName

public java.lang.String getQueueTableName() throws AQException

This method gets the name of the queue table in which the queue resides.

getProperty

public AQQueueProperty getProperty() throws AQException

This method is used to get the queue properties.

Returns

AQQueueProperty object

createMessage

public AQMessage createMessage() throws AQException

This method is used to create a new AQMessage object that can be populated with data to be enqueued.

Returns

AQMessage object

enqueue

public byte[] enqueue(AQEnqueueOption enq_option,
                      AQMessage message) throws AQException

This method is used to enqueue a message in a queue.

Parameter	Description
`enq_option`	`AQEnqueOption` object
`message`	`AQMessage` to be enqueued

Returns

Message id of the enqueued message. The AQMessage object's messageId field is also populated after the completion of this call.

dequeue

public AQMessage dequeue(AQDequeueOption deq_option) 
   throws AQException

This method is used to dequeue a message from a queue.

Parameter	Description
deq_option	`AQDequeueOption` object

Returns

AQMessage, the dequeued message

dequeue (for queues with Oracle object type payloads - SQL data version)

public AQMessage dequeue(AQDequeueOption deq_option, java.lang.Class payload_
class) throws AQException

This method is used to dequeue a message from a queue containing Oracle object payloads. This version must be used if your program uses the SQL Data interface for mapping java classes to Oracle object types.

Parameters

deq_option - AQDequeueOption object

payload_class - the payload dequeued is transformed as an object of this type. The class specified must implement the SQLData interface and correspond to the payload type defined for the queue.

Returns

AQMessage, the dequeued message

Users are also required to register all java classes that map to ADTs contained in the queue in the typeMap of the JDBC connection.

For more information on the SQLData interface and registering classes in the type map refer to the JDBC developer's guide.

dequeue (for queues with Oracle object type payloads - Custom Datum version)

public AQMessage dequeue(AQDequeueOption deq_option,
oracle.sql.CustomDatumFactory payload_fact) throws AQException

This method is used to dequeue a message from a queue containing Oracle object payloads. This version must be used if your program uses the Custom Datum interface for mapping java classes to Oracle object types.

Parameters

deq_option - AQDequeueOption object

payload_fact - This is the CustomDatum factory for the class that maps to the SQL ADT type of the payload in the queue. For example, if Person is the java class that maps to PERSON ADT in the database, then the CustomDatum factory for this class can be obtained using Person.getFactory()

Returns

AQMessage - the dequeued message

For more information on the CustomDatum and CustomDatumFactory interface and registering classes in the type map refer to the JDBC developer's guide.

dequeue (for queues with Oracle object type payloads - ORAData version)

public AQMessage dequeue(AQDequeueOption deq_option,
oracle.sql.ORADataFactory payload_fact) throws AQException

This method is used to dequeue a message from a queue containing Oracle object payloads. This version must be used if your program uses the ORAData interface for mapping java classes to Oracle object types.

Parameters:

deq_option - AQDequeueOption object

payload_fact - This is the ORAData factory for the class that maps to the SQL ADT type of the payload in the queue. For example, if Person is the java class that maps to PERSON ADT in the database, then the ORAData factory for this class can be obtained using Person.getORADataFactory()

Returns

AQMessage - the dequeued message

For more information on the ORAData and ORADataFactory interface and registering classes in the type map refer to the JDBC developer's guide.

getSubscribers

public AQAgent[] getSubscribers() throws AQException

2 Package oracle.AQ

Package oracle.AQ Description

Accessing Java AQ Classes

Setup for oracle.AQ Examples

1. Create an oracle.AQ user named aqjava

2. Set up main class

3. Create an AQ Session

Package oracle.AQ Summary

Table 2-1 Package oracle.AQ member summary

AQDriverManager

Methods

getDrivers

getAQSession

Parameter

Multithreaded Program Support

Loading the Java AQ Driver

Example

AQSession

Methods

createQueueTable

Returns

getQueueTable

Returns

createQueue

Returns

getQueue

Returns

getDB Connection

Example

listen

Returns

Throws

Example

AQConstants

Visibility constants

Payload type, Object

Payload type, RAW

AQAgent

Constructor

Methods

getName

setName

getAddress

setAddress

getProtocol

setProtocol

AQQueueTableProperty

Constants

Constructor

Methods

getPayloadType

setPayloadType

setStorageClause

getSortOrder

Returns

setSortOrder

isMulticonsumerEnabled

Returns

setMultiConsumer

getMessageGrouping

Returns

setMessageGrouping

getComment

setComment

getCompatible

setCompatible

getPrimaryInstance

setPrimaryInstance

getSecondaryInstance

setSecondaryInstance

Example

AQQueueProperty

Constants

Constructor

Methods

getQueueType

Returns

setQueueType

getMaxRetries

setMaxRetries

2
Package oracle.AQ

1. Create an oracle.AQ user named `aqjava`