Oracle9i Lite Developerís Guide for AQ Lite
Release 5.0

Part Number A90251-01
Go To Table Of Contents
Contents
Go To Index
Index

Go to previous page Go to next page

3
AQ Lite Queue Object Administration

This document describes the administration of AQ Lite queue objects using the AQ and AQ Lite Java API. For more information on using any of the methods discussed in this document see Appendix A, "AQ Lite Java API".

The tasks described in this document may also be performed using PL/SQL or the Oracle Call Interface (OCI) on the Oracle8i server. See the Oracle8i Application Developer's Guide - Advanced Queuing for more information.

Topics in this document include:

Creating an AQ Session

Before performing any of the operations described in this document, you must create an AQ session. To create an AQ session in AQ Lite:

  1. Establish an Oracle Lite Java Access Class (JAC) connection.

  2. Get the AQLiteDriver.

The following is an example of creating an AQ session in AQ Lite:

  // Establish Oracle Lite Connection
  POLConnection olite_conn =
  POLConnection.getConnection("C:/orant/oldb/polite.odb",0);

  // Initiate AQLite Driver
  AQLiteDriver aq_driver = new AQLiteDriver();

  // Create AQ Session
  AQSession aq_session = aq_driver.createAQSession(olite_conn);

In Oracle8i AQ you can establish an Oracle JDBC connection. Use the AQOracleDriver class to get the Oracle8i AQDriver. You can also use the AQDriverManager class to handle different AQ drivers and establish an AQ session.

Queue Object Overview

A queue is a repository for messages. Queues are stored within queue tables. A queue table is a database table class which contains one or more queues. Every queue has a subscriber list. The subscriber list contains a list of applications or users that may access messages in the queue.

AQ Lite queue and queue table information is stored in the following two catalog tables in Oracle Lite:

AQ$_Queue_Tables

Column Name  Description  Null?  Type 

OWNER  

The Queue schema name. 

 

VARCHAR2(30)  

QUEUE_TABLE 

The Queue table name. 

 

VARCHAR2(30)  

TYPE 

The Payload type. 

 

VARCHAR2(7)  

OBJECT_TYPE 

The Object type. 

 

VARCHAR2(61)  

SORT_ORDER 

The User specified sort order. 

 

VARCHAR2(22)  

RECIPIENTS  

The SINGLE or MULTIPLE. 

 

VARCHAR2(8)  

MESSAGE_GROUPING  

NONE or TRANSACTIONAL. 

 

VARCHAR2(13)  

USER_COMMENT 

The User comment for the queue table. 

 

VARCHAR2(50)  

AQ$_Queues

Column Name  Description  Null?  Type 

OWNER 

The Queue schema name. 

NOT NULL 

VARCHAR2(30)  

NAME 

The Queue name. 

NOT NULL 

VARCHAR2(30)  

QUEUE_TABLE 

The Queue table where this queue resides. 

NOT NULL 

VARCHAR2(30)  

QID 

A Unique queue identifier. 

NOT NULL 

NUMBER  

QUEUE_TYPE 

The Queue type. 

 

VARCHAR2(15)  

MAX_RETRIES 

The Number of dequeue attempts allowed. 

 

NUMBER  

RETRY_DELAY 

The Number of seconds before retry can be attempted. 

 

NUMBER  

ENQUEUE_ENABLED 

YES/NO. 

 

VARCHAR2(7)  

DEQUEUE_ENABLED 

YES/NO. 

 

VARCHAR2(7)  

RETENTION 

The Number of seconds the message is retained after dequeue. 

 

VARCHAR2(40)  

USER_COMMENT 

The User comment for the queue. 

 

VARCHAR2(50)  

Since AQ Lite is implemented in the Java object layer of Oracle Lite, you may view these objects through the Oracle Lite Designer. For more information on the Oracle Lite Designer, see the Oracle Lite Java Developer's Guide.

Oracle8i Queue and Queue Table Information

In Oracle8i you can access queue and queue table information in the following views:

In Oracle8i subscriber information is located in AQ$<q_tab_name>_s. In Oracle Lite subscriber information is located in AQ$_QueuesJAC Class.

Administering Queue Objects

The following sections provide the information necessary to create and manage queue and queue table objects using the AQ Lite Java API. The method you use to administer queue and queue table objects depends on your AQ Lite configuration. If you are administering the master-client configuration, you generally perform administrative tasks on the Oracle8i server and deploy to the Oracle Lite client devices. If you are administering the stand-alone configuration, you must administer queue and queue table objects from the Oracle Lite client. See

Preparing to Create Stand-Alone Queue Objects

Before creating stand-alone queues and queue tables on an Oracle Lite client you must create the necessary catalog tables by running a non-server deployment on the client device as shown in the following code:

 AQLIteDeploymentClient deplc = 
 AQLIteDeploymentClient(aqConn,anyName", null, null, "anyID");
 deplc.execDeployment(true, false);


If you later decide to use the stand-alone queues in a master-client queue configuration, set the first parameter to "false" in the execDeployment method call, and run the non-server deployment again.

Create Queue Table

This section describes how to create a queue table using the AQ and AQ Lite Java API. Queue tables may also be created using PL/SQL or the Oracle Call Interface (OCI) on the Oracle8i server. See the Oracle8i Application Developer's Guide - Advanced Queuing for more information.

If you are administering the master-client configuration, you must create queue tables on the Oracle8i server and deploy them to each client device. See Chapter 2, "AQ Lite Deployment" for more information.

If you are administering a stand-alone client configuration, you must create queue tables on the client device using the AQ Lite Java API.

createQueueTable

Purpose

Creates a queue table on the Oracle8i server or Oracle Lite client.

Syntax

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

Methods

The following table describes the methods used to set table properties in AQQueueTableProperty:

Method  Description 

setMultiConsumer  

Specifies whether the queue allows more than one consumer. Options include: True - enable, False - disable (default). 

setStorageClause  

Sets storage parameter. This is only supported by Oracle8i server queues. During deployment, this queue property is not set in Oracle Lite queue tables. 

setCompatible  

Specifies the Oracle8 backward compatibility option. This is only supported by Oracle8i server queues. During deployment, this queue property is not set in Oracle Lite queue tables. 

setMessageGrouping  

Specifies the option used for message grouping. If it is set to TRANSACTIONAL, only messages enqueued in the same transaction are dequeued. If it is set to NONE, all messages are dequeued until there are no more messages. The default is NONE. 

setPrimaryInstance  

Specifies whether to set the queue table as the primary instance. This is only supported by Oracle8i server queues. Deployment does not set this property for Oracle Lite queue tables. 

setSecondaryInstance  

Specifies whether multiple instances are allowed. This is only supported by Oracle8i server queues. Deployment does not set this property for Oracle Lite queue tables. 

setSortOrder 

Sets the sorting order of messages in queues. Messages can be sorted by enqueue time (default) or priority. 

setComment  

Specifies a comment. 

Example

 AQSession aq_conn;
 .
 .
 .
 AQQueueTableProperty qt_property = new AQQueueTableProperty("RAW");
 qt_prop.setMultiConsumer(true);   // allow more than one consumer
 qt_prop.setStorageClause("");     // use default storage parameter
 qt_prop.setCompatible("");        // backward compatibility
 qt_prop.setMessageGrouping
    (AQQueueTableProperty.NONE);    // no message grouping
 qt_prop.setPrimaryInstance(1);    // set as primary instance
 qt_prop.setSecondaryInstance(0);  // do not allow multiple instance
 qt_prop.setSortOrder("ENQ_TIME"); // order messages by enqueue time
 qt_prop.setComment("AQLite Sample Application");  // comments

 AQQueueTable q_table = aq_conn.createQueueTable("Scott", // queue user 
                                                 "Q_Table1", // queue name
                                                  qt_property);

Notes

AQ Lite does not support the following methods:

For information on methods used to retrieve queue table properties see Appendix A, "AQ Lite Java API".

Drop Queue Table

This section describes how to drop a queue table using the AQ Lite Java API. Queue tables may also be dropped using PL/SQL or Oracle Call Interface (OCI) on the Oracle8i server. See the Oracle8i Application Developer's Guide - Advanced Queuing for more information.

Regardless of the configuration, queue tables must be dropped on both the client and server side. Queue tables residing on a client device cannot be removed through the Oracle8i server interface. Before dropping a queue table you must drop all queues belonging to it.

drop()

Purpose

To remove a queue table from the Oracle8i server or Oracle Lite client.

Syntax

public void drop(boolean force) throws AQException

Example

 AQQueueTable queue_table;
 AQQueue queue;
 .
 .
 .
 queue.drop();
 queue_table.drop(true);

Create Queue

This section describes how to create a queue using the AQ Lite Java API. Queues may be also created using PL/SQL or Oracle the Call Interface (OCI) on the Oracle8i server. See the Oracle8i Application Developer's Guide - Advanced Queuing for more information.

If you are administering the master-client configuration you must create queues on the Oracle8i server and deploy them to each client device. See Chapter 2, "AQ Lite Deployment" for more information.

Queues must be started using Oracle8i methods before messages can be enqueued and dequeued. The start() method is not operational in Oracle Lite. Using it has no effect on client queues.

If you are administering a stand-alone queue configuration, you must create queues on the client device using the AQ Lite Java API.

createQueue

Purpose

To create a queue table on the Oracle8i server or Oracle Lite client.

Syntax

In AQSession:

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

In AQQueueTable:

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

Example

   AQQueueTable q_table;
   .
   .
   .
   AQQueueProperty q_property = new AQQueueProperty();
   q_property.setQueueType(AQQueueProperty.NORMAL_QUEUE);
   q_property.setRetentionTime(0.0) ;
   q_property.setComment("AQLite Sample Application");
   
   AQQueue queue = aq_conn.createQueue (q_table,      // Queue table object
                                       "Queue1",     // Queue name
                                       q_property);  // Queue property
   queue.start();
   

Methods

The following table describes the methods used to set queue properties in AQQueueProperty:

Method  Description 

setQueueType  

Sets the queue type. Options include: NORMAL_QUEUE or EXCEPTION_QUEUE.

The exception queue type is not available for Oracle Lite queues. Exception queues can not be deployed to Oracle Lite clients. 

setComment 

Specifies a comment. 

Notes

AQ Lite does not support the following methods:

Drop Queue

This section describes how to drop a queue using the AQ Lite Java API. Queues may also be dropped using PL/SQL or the Oracle Call Interface (OCI) on the Oracle8i server. See the Oracle8i Application Developer's Guide - Advanced Queuing for more information.

Regardless of the configuration, queues must be dropped on both the client and server side. Queues residing on a client device cannot be removed through the Oracle8i server interface. You must stop a queue before you can drop it from the Oracle8i server. The stop() method is not operational in Oracle Lite. Using it will not have any effect on client queues.

dropQueue

Purpose

To remove a queue from the Oracle8i server or Oracle Lite client.

Syntax

In AQQueueTable:

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

In AQQueue:

public void drop()
   throws AQException

Example

 AQQueue queue;
 .
 .
 .
 queue.stop();
 queue.drop();

Add Subscriber

This section describes how to add a subscriber to a queue using the AQ Lite Java API. Subscribers may also be added using PL/SQL or the Oracle Call Interface (OCI) on the Oracle8i server. See the Oracle8i Application Developer's Guide - Advanced Queuing for more information.

Subscribers are the default recipients of all messages in a queue. Each queue can have multiple subscribers. A subscriber can be an application on an Oracle8i server or on a client device. The subscriber list can be overridden by adding a recipient list to a message at enqueue.

Subscribers to an Oracle8i server queue can reside on any Oracle8i server or an Oracle Lite client. Messages propagated from an Oracle Lite client to an Oracle8i server queue can be delivered to another Oracle8i server queue or an Oracle Lite client.

In the master-client configuration messages from the server are assigned recipients by the Propagator. Messages propagated from client to server use the Oracle8i master queue's subscriber list if no recipients are set in the messages at enqueue.

In the stand-alone configuration, all message consumers on the local device must be represented in the queue subscriber list.

Subscribers are of the AQAgent type. The first step in adding a subscriber is to create an AQAgent object.

addSubscriber

Purpose

To add a subscriber to an Oracle Lite queue.

Syntax

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

Example

//Create AQAgent objects
AQAgent subscriber1 = new AQAgent("order_entry_consumer", null, 0);
AQAgent subscriber2 = new AQAgent("delivery_consumer", null, 0);

//Add subscribers
AQQueue queue;
.
.
.
queue.addSubscriber(subscriber1, null);
queue.addSubscriber(subscriber2, null);

Remove Subscriber

This section describes how to remove a subscriber from a queue using the AQ Lite Java API. Subscribers may also be removed using PL/SQL or the Oracle Call Interface (OCI) on the Oracle8i server. See the Oracle8i Application Developer's Guide - Advanced Queuing for more information.

removeSubscriber

Purpose

To remove a subscriber from an Oracle Lite queue.

Syntax

public void removeSubscriber(AQAgent subscriber)
   throws AQException

Example

AQQueue queue;
.
.
.
AQAgent[] subscriber = queue.getSubscribers();
queue.removeSubscriber(subscriber[0]);

Get Queue and QueueTable Objects

The following table summarizes the location of methods for getting Queue and QueueTable objects. For more information about these methods, see Appendix A, "AQ Lite Java API".

Method  Interface 

getQueueTable 

AQSession 

getQueue 

AQSession and AQQueueTable 

getSubscribers 

AQQueue 


Go to previous page Go to next page
Oracle
Copyright © 2001 Oracle Corporation.

All Rights Reserved.
Go To Table Of Contents
Contents
Go To Index
Index