1
Package oracle.AQ

Package oracle.AQ Description

Class Summary

Interfaces

AQSession

Open a session to the queuing system

AQQueueTable

AQ Queue Table interface

AQQueueAdmin

AQ Queue administrative interfaces

AQQueue

AQ Queue operational interfaces

AQMessage

AQ message

AQRawPayload

AQ Raw Payload

AQObjectPayload

AQ Object Payload

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

AQOracleSQLException

Class Summary
Interfaces
AQSession	Open a session to the queuing system
AQQueueTable	AQ Queue Table interface
AQQueueAdmin	AQ Queue administrative interfaces
AQQueue	AQ Queue operational interfaces
AQMessage	AQ message
AQRawPayload	AQ Raw Payload
AQObjectPayload	AQ Object Payload
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
AQOracleSQLException

Introduction

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

The following sections describe the common interfaces and classes based on current PL/SQL interfaces.

The common interfaces are prefixed with "AQ". These interfaces will have different implementations in Oracle8i and Oracle Lite.
This document describes the common interfaces and their corresponding Oracle8i implementations, which are prefixed with "AQOracle".

Location of Java AQ Classes

The Java AQ classes are located in $ORACLE_HOME/rdbms/jlib/aqapi.jar. These classes can be used with any Oracle8i JDBC driver.

If your application uses the OCI8 or thin JDBC driver, for JDK 1.2 you must include $ORACLE_HOME/rdbms/jlib/aqapi.jar in the CLASSPATH; for JDK 1.1 you must include $ORACLE_HOME/rdbms/jlib/aqapi11.jar in the CLASSPATH.

If the application is using the Oracle Server driver and accessing the java AQ API from java stored procedures, the Java files are generally automatically pre-loaded in a Java-enabled database. If they are not loaded, you must first load the aqapi.jar and jmscommon.jar files into the database using the loadjava utility.

Oracle8i Application Developer's Guide - Advanced Queuing, Appendix A, contains the following examples:

Enqueue and Dequeue of Object Type Messages (CustomDatum interface) Using Java
Enqueue and Dequeue of Object Type Messages (using SQLData interface) Using Java
Create a Queue Table and Queue Using Java
Create a Queue and Start Enqueue/Dequeue Using Java
Create a Multi-Consumer Queue and Add Subscribers Using Java
Enqueue of RAW Messages using Java
Dequeue of Messages Using Java
Dequeue of Messages in Browse Mode Using Java
Enqueue of Messages with Priority Using Java
Enqueuing and Dequeuing Object Type Messages That Contain LOB Attributes Using Java

Set up for the test_aqjava class is described in "Setup for oracle.AQ Examples".

The way to create a multi-consumer queue is described in the "AQSession".

AQDriverManager

The various implementations of the Java AQ API are managed via an AQDriverManager. Both OLite and Oracle8i will have an AQDriver which is registered with the AQDriverManager. The driver manager is used to create an AQSession which 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 Oracle8i 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 8.1 style queue tables.

Methods

getDrivers

public static java.util.Vector getDrivers()

This method returns the list of drivers registered with the driver manager. It returns a 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 Oracle8i, the driver is loaded using the Clas.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 Oracle8i 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 (as described in the first two tables). This will ensure that your applications are portable between Oracle8i and Olite AQ implementations.

oracle.AQ classes should not be used unless there is a method in these classes that is not available in the common interfaces. Note that since the AQQueue interface extends AQQueueAdmin, all queue administrative and operation 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 Meaning

owner

schema (user) in which to create the queue table

q_name

name of the queue table

property

queue table properties

Parameter	Meaning
`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 Meaning

owner

schema (user) in which the queue table resides

name

name of the queue table

Parameter	Meaning
`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 Meaning

q_table

queue table in which to create queue

name

name of the queue to be created

q_property

queue properties

Parameter	Meaning
`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 Meaning

owner

schema (user) in which the queue table resides

name

name of the queue

Parameter	Meaning
`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();

Setup for oracle.AQ Examples

1. Create an oracle.AQ User

Here an 'aqjava' user is setup 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 we set up the main class from which we will call subsequent examples and handle exceptions.

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, an AQ Session is created for the 'aqjava' user as shown in the AQDriverManager section above:

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 Oracle8i 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;
   }

Example

1. Create a queue table and a queue

Now, with the 'runTest' class, called from the above main class, we will 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 Meaning

name

agent name

address

agent address

protocol

agent protocol (required only in the first constructor); default is 0

Parameter	Meaning
`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 Meaning

name

Agent name

Parameter	Meaning
`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 Meaning

address

queue at a specific destination

Parameter	Meaning
`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 Meaning

protocol

Agent protocol

Parameter	Meaning
`protocol`	Agent protocol

AQQueueTableProperty

This class represents queue table properties.

Constants for Message Grouping

public static final int NONE
public static final int TRANSACTIONA

Constructor

public AQQueueTableProperty(java.lang.String p_type)

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

Parameter Meaning

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

Parameter	Meaning
`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 Meaning

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

Parameter	Meaning
`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 Meaning

s_clauses

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

Parameter	Meaning
`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 Meaning

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.

Parameter	Meaning
`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 Meaning

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

Parameter	Meaning
`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 Meaning

m_grouping

NONE or TRANSACTIONAL

Parameter	Meaning
`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 Meaning

qt_comment

comment

Parameter	Meaning
`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 Meaning

qt_compatible

compatible property

Parameter	Meaning
`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 Meaning

inst

primary instance

Parameter	Meaning
`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 Meaning

inst

secondary instance

Parameter	Meaning
`inst`	secondary instance

Examples:

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 Meaning

q_type

NORMAL_QUEUE or EXCEPTION_QUEUE

Parameter	Meaning
`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 Meaning

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.

Parameter	Meaning
`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 Meaning

interval

retry interval; specifying NULL will use the default

Parameter	Meaning
`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

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 Meaning

qt_comment

queue comment

Parameter	Meaning
qt_comment	queue comment

Example

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 Meaning

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 Meaning

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 Meaning

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 Meaning

queue_name

name of the queue to be dropped

Example

Set up the test_aqjava class as described in the Setup for oracle.AQ Examples section on , above.

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 Meaning

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 Meaning

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 Meaning

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 Meaning

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 Meaning

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 Meaning

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 Meaning

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 Meaning

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 Meaning

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 Meaning

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 Meaning

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 Meaning

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 Meaning

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 Meaning

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 Meaning

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 Meaning

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 Meaning

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.

getSubscribers

public AQAgent[] getSubscribers() throws AQException

This method is used to get a subscriber list for the queue.

Returns

An array of AQAgents

AQEnqueueOption

This class is used to specify options available for the enqueue operation.

Constants

public static final int DEVIATION_NONE
public static final int DEVIATION_BEFORE
public static final int DEVIATION_TOP
public static final int VISIBILITY_ONCOMMIT
public static final int VISIBILITY_IMMEDIATE

Constructors

public AQEnqueueOption(int visibility,
                       byte[] relative_msgid,
                       int sequence_deviation)
public AQEnqueueOption()

There are two constructors available. The first creates an object with the specified options, the second creates an object with the default options.

Parameter Meaning

visibility

VISIBILITY_IMMEDIATE or VISIBILITY_ONCOMMIT (default)

relative_msgid

when DEVIATION_BEFORE is used, this parameter identifies the message identifier of the message before which the current message is to be enqueued

sequence_deviation

DEVIATION_TOP-- the message is enqueued ahead of any other messages
DEVIATION_BEFORE -- the message is enqueued ahead of the message specified by relative_msgid
DEVIATION_NONE -- default

getVisibility

public int getVisibility() throws AQException

This method gets the visibility.

Returns

VISIBILITY_IMMEDIATE or VISIBILITY_ONCOMMIT

setVisibility

public void setVisibility(int visibility) throws AQException

This method sets the visibility.

Parameter Meaning

visibility

VISIBILITY_IMMEDIATE or VISIBILITY_ONCOMMIT

getRelMessageId

public byte[] getRelMessageId() throws AQException

This method gets the relative message id.

getSequenceDeviation

public int getSequenceDeviation() throws AQException

This method gets the sequence deviation.

setSequenceDeviation

public void setSequenceDeviation(int sequence_deviation,
                                 byte[] relative_msgid) throws AQException

This method specifies whether the message being enqueued should be dequeued before other message(s) already in the queue.

Parameter Meaning

sequence_deviation

DEVIATION_TOP-- the message is enqueued ahead of any other messages
DEVIATION_BEFORE -- the message is enqueued ahead of the message specified by relative_msgid
DEVIATION_NONE -- default

relative_msgid

when DEVIATION_BEFORE is used, this parameter identifies the message identifier of the message before which the current message is to be enqueued

AQDequeueOption

This class is used to specify the options available for the dequeue option.

Constants

public static final int NAVIGATION_FIRST_MESSAGE
public static final int NAVIGATION_NEXT_TRANSACTION
public static final int NAVIGATION_NEXT_MESSAGE
public static final int DEQUEUE_BROWSE
public static final int DEQUEUE_LOCKED
public static final int DEQUEUE_REMOVE
public static final int DEQUEUE_REMOVE_NODATA
public static final int WAIT_FOREVER
public static final int WAIT_NONE
public static final int VISIBILITY_ONCOMMIT
public static final int VISIBILITY_IMMEDIATE

Constructor

public AQDequeueOption()

This method creates an object with the default options.

getConsumerName

public java.lang.String getConsumerName() throws AQException

This method gets consumer name.

setConsumerName

public void setConsumerName(java.lang.String consumer_name) 
   throws AQException

This method sets consumer name

Parameter Meaning

consumer_name

Agent name

getDequeueMode

public int getDequeueMode() throws AQException

This method gets dequeue mode.

Returns

DEQUEUE_BROWSE, DEQUEUE_LOCKED, DEQUEUE_REMOVE or DEQUEUE_REMOVE_NODATA

setDequeueMode

public void setDequeueMode(int dequeue_mode) throws AQException

This method sets the dequeue mode.

Parameter Meaning

dequeue_mode

DEQUEUE_BROWSE, DEQUEUE_LOCKED, DEQUEUE_REMOVE or DEQUEUE_REMOVE_NODATA

getNavigationMode

public int getNavigationMode() throws AQException

This method gets the navigation mode.

Returns

NAVIGATION_FIRST_MESSAGE or NAVIGATION_NEXT_MESSAGE or NAVIGATION_NEXT_TRANSACTION

setNavigationMode

public void setNavigationMode(int navigation) throws AQException

This method sets the navigation mode.

Parameter Meaning

navigation

NAVIGATION_FIRST_MESSAGE or NAVIGATION_NEXT_MESSAGE or NAVIGATION_NEXT_TRANSACTION

getVisibility

public int getVisibility() throws AQException

This method gets the visibility.

Returns

VISIBILITY_IMMEDIATE or VISIBILITY_ONCOMMIT

setVisibility

public void setVisibility(int visibility) throws AQException

This method sets the visibility.

Parameter Meaning

visibility

VISIBILITY_IMMEDIATE or VISIBILITY_ONCOMMIT

getWaitTime

public int getWaitTime() throws AQException

This method gets the wait time.

Returns

WAIT_FOREVER or WAIT_NONE or the actual time in seconds

setWaitTime

public void setWaitTime(int wait_time) throws AQException

This method sets the wait time.

Parameter Meaning

wait_time

WAIT_FOREVER or WAIT_NONE or time in seconds

getMessageId

public byte[] getMessageId() throws AQException

This method gets the message id.

setMessageId

public void setMessageId(byte[] message_id) throws AQException

This method sets the message id.

Parameter Meaning

message_id

message id

getCorrelation

public java.lang.String getCorrelation() throws AQException

This method gets the correlation id.

setCorrelation

public void setCorrelation(java.lang.String correlation) 
   throws AQException

This method sets the correlation id.

Parameter Meaning

correlation

user-supplied information

AQMessage

This interface contains methods for AQ messages with raw or object payloads.

Methods

getMessageId

public byte[] getMessageId() throws AQException

This method gets the message id.

getRawPayload

public AQRawPayload getRawPayload() throws AQException

This method gets the raw payload

Returns

AQRawPayload object

setRawPayload

public void setRawPayload(AQRawPayload message_payload) 
   throws AQException

This method sets the raw payload. It throws AQException if this is called on messages created from object type queues.

Parameter Meaning

message_payload

AQRawPayload object containing raw user data

getObjectPayload

public AQObjectPayload getObjectPayload() throws AQException

Get the object payload

Returns

AQObjectPayload object

setObjectPayload

public void setObjectPayload(AQObjectPayload message_payload)
   throws AQException

Set the object payload.

Parameter Meaning

message_payload

AQObjectPayload object containing object user data. Throws AQException if this is called on Messages created from raw type queues.

getMessageProperty

public AQMessageProperty getMessageProperty() throws AQException

This method gets the message properties

Returns

AQMessageProperty object

setMessageProperty

public void setMessageProperty(AQMessageProperty property) 
   throws AQException

This method sets the message properties.

Parameter Meaning

property

AQMessageProperty object

AQMessageProperty

The AQMessageProperty class contains information that is used by AQ to manage individual messages. The properties are set at enqueue time and their values are returned at dequeue time.

Constants

public static final int DELAY_NONE
public static final int EXPIRATION_NEVER
public static final int STATE_READY
public static final int STATE_WAITING
public static final int STATE_PROCESSED
public static final int STATE_EXPIRED

Constructor

public AQMessageProperty()

This method creates the AQMessageProperty object with default property values.

Methods

getPriority

public int getPriority() throws AQException

This method gets the message priority.

setPriority

public void setPriority(int priority) throws AQException

This method sets the message priority.

Parameter Meaning

priority

priority of the message; this can be any number, including negative number - a smaller number indicates a higher priority

getDelay

public int getDelay() throws AQException

This method gets the delay value.

setDelay

public void setDelay(int delay) throws AQException

This method sets delay value.

Parameter Meaning

delay

the delay represents the number of seconds after which the message is available for dequeuing; with NO_DELAY the message is available for immediate dequeuing

getExpiration

public int getExpiration() throws AQException

This method gets expiration value.

setExpiration

public void setExpiration(int expiration) throws AQException

This method sets expiration value.

Parameter Meaning

expiration

the duration the message is available for dequeuing; this parameter is an offset from the delay; if NEVER, the message will not expire

getCorrelation

public java.lang.String getCorrelation() throws AQException

This method gets correlation.

setCorrelation

public void setCorrelation(java.lang.String correlation) 
   throws AQException

This method sets correlation.

Parameter Meaning

correlation

user-supplied information

getAttempts

public int getAttempts() throws AQException

This method gets the number of attempts.

getRecipientList

public java.util.Vector getRecipientList() throws AQException

This method gets the recipient list.

Returns

A vector of AQAgents.This parameter is not returned to a consumer at dequeue time.

setRecipientList

public void setRecipientList(java.util.Vector r_list) 
   throws AQException

This method sets the recipient list.

Parameter Meaning

r_list

vector of AQAgents; the default recipients are the queue subscribers

getOrigMessageId

public byte[] getOrigMessageId() throws AQException

This method gets original message id.

getSender

public AQAgent getSender() throws AQException

This method gets the sender of the message.

setSender

public void setSender(AQAgent sender) throws AQException

This method sets the sender of the message.

Parameter Meaning

sender

AQAgent

getExceptionQueue

public java.lang.String getExceptionQueue() throws AQException

This method gets the exception queue name.

setExceptionQueue

public void setExceptionQueue(java.lang.String queue) 
   throws AQException

This method sets the exception queue name.

Parameter Meaning

queue

exception queue name

getEnqueueTime

public java.util.Date getEnqueueTime() throws AQException

This method gets the enqueue time.

getState

public int getState() throws AQException

This method gets the message state.

Returns

STATE_READY or STATE_WAITING or STATE_PROCESSED or STATE_EXPIRED

AQRawPayload

This object represents the raw user data that is included in AQMessage.

getStream

public int getStream(byte[] value, int len) throws AQException

This method reads some portion of the raw payload data into the specified byte array.

Parameter Meaning

value

byte array to hold the raw data

len

number of bytes to be read

Returns

The number of bytes read

getBytes

public byte[] getBytes() throws AQException

This method retrieves the entire raw payload data as a byte array.

Returns

byte - the raw payload as a byte array

setStream

public void setStream(byte[] value,
                      int len) throws AQException

This method sets the value of the raw payload.

Parameter Meaning

value

byte array containing the raw payload

len

number of bytes to be written to the raw stream

AQObjectPayload

This object represents the structured user data (for object queues) that is included in the AQMessage

Methods

setPayloadData

public void setPayloadData(java.lang.Object obj) throws AQException

This method is used to fill in the payload into the AQObjectPayload object

Parameter Meaning

obj

User-data to be put. Depending on which AQ driver you use, there may be certain restrictions on the types of objects that can be passed in. The Oracle8i AQ driver accepts objects which implement the SQLData or CustomDatum interface inside the payload.

Please refer to the JDBC developer's guide for more information on SQLData and CustomDatum interfaces

getPayloadData

public java.lang.Object getPayloadData() throws AQException

This method is used to retrieve the message payload from the AQObjectPayload object

Returns

Object payload in message - This will depend on the SQLData class or CustomDatum Factory specified during dequeue.

AQException

public class AQException extends java.lang.RuntimeException

This exception is raised when the user encounters any error while using the Java AQ API.

This interface supports all methods supported by Java exceptions and some additional methods.

Methods

getMessage

This method gets the error message.

getErrorCode

This method gets the error number (Oracle error code).

getNextException

This method gets the next exception in the chain if any.

AQOracleSQLException

AQOracleSQLException extends AQException.

When using Oracle8i AQ driver, some errors may be raised from the client side and some from the RDBMS. The Oracle8i driver raises AQOracleSQLException for all errors that occur while performing SQL.

For sophisticated users interested in differentiating between the two types of exceptions, this interface might be useful. In general you will only use AQException.

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

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

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

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

Parameter	Meaning
`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

Parameter	Meaning
`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)

Parameter	Meaning
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)

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

Parameter	Meaning
`value`	byte array to hold the raw data
`len`	number of bytes to be read

Parameter	Meaning
`value`	byte array containing the raw payload
`len`	number of bytes to be written to the raw stream

1 Package oracle.AQ

Package oracle.AQ Description

Introduction

Location of Java AQ Classes

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

Setup for oracle.AQ Examples

1. Create an oracle.AQ User

2. Set up main class

3. Create an AQ Session;

Example

1. Create a queue table and a queue

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

AQConstants

Visibility constants

Payload type, Object

Payload type, RAW

AQAgent

Constructor

Methods

getName

setName

getAddress

setAddress

getProtocol

setProtocol

AQQueueTableProperty

Constants for Message Grouping

Constructor

Methods

getPayloadType

setPayloadType

setStorageClause

getSortOrder

Returns

setSortOrder

isMulticonsumerEnabled

Returns

setMultiConsumer

getMessageGrouping

Returns

setMessageGrouping

getComment

setComment

getCompatible

setCompatible

getPrimaryInstance

setPrimaryInstance

getSecondaryInstance

setSecondaryInstance

Examples:

AQQueueProperty

Constants

Constructor

Methods

getQueueType

Returns

setQueueType

getMaxRetries

setMaxRetries

setRetryInterval

getRetryInterval

1
Package oracle.AQ