2
Basic Components

The following basic components are discussed in this chapter:

• Data Structures
• Enumerated Constants in the Administrative Interface
• Enumerated Constants in the Operational Interface
• INIT.ORA Parameter File Considerations

Data Structures

The following chapters discuss the Advanced Queuing administrative and operational interfaces in which data structures are used:

• Chapter 9, "Administrative Interface"
• Chapter 11, "Operational Interface: Basic Operations"

Object Name (object_name)

Purpose

To name database objects. This naming convention applies to queues, queue tables, and object types.

Syntax

object_name := VARCHAR2
object_name := [<schema_name>.]<name>

Usage

Names for objects are specified by an optional schema name and a name. If the schema name is not specified, then the current schema is assumed. The name must follow the reserved character guidelines in the Oracle9i SQL Reference. The schema name, agent name, and the object type name can each be up to 30 bytes long. However, queue names and queue table names can be a maximum of 24 bytes.

Type Name (type_name)

Purpose

To define queue types.

Syntax

type_name := VARCHAR2
type_name := <object_type> | "RAW"

Usage

Table 2-1 lists usage information for type_name.

Table 2-1 Type Name (type_name)

Agent Type (aq$_agent)

Purpose

To identify a producer or a consumer of a message.

Syntax

TYPE aq$_agent IS OBJECT (
   name            VARCHAR2(30), 
   address         VARCHAR2(1024),
   protocol        NUMBER)

Usage

All consumers that are added as subscribers to a multiconsumer queue must have unique values for the AQ$_AGENT parameters. You can add more subscribers by repeatedly using the DBMS_AQADM.ADD_SUBSCRIBER procedure up to a maximum of 1024 subscribers for a multiconsumer queue. Two subscribers cannot have the same values for the NAME, ADDRESS, and PROTOCOL attributes for the AQ$_AGENT type. At least one of the three attributes must be different for two subscribers.

Table 2-2 lists usage information for aq$_agent.

Table 2-2 Agent (aq$_agent)

AQ Recipient List Type (aq$_recipient_list_t)

Purpose

To identify the list of agents that will receive the message.

Syntax

TYPE aq$_recipient_list_t IS TABLE OF aq$_agent  
           INDEX BY BINARY_INTEGER; 

AQ Agent List Type (aq$_agent_list_t)

Purpose

To identify the list of agents for DBMS_AQ.LISTEN to listen for.

Syntax

TYPE aq$_agent_list_t IS TABLE OF aq$_agent 
           INDEX BY BINARY INTEGER; 

AQ Subscriber List Type (aq$_subscriber_list_t)

Purpose

To identify the list of subscribers that subscribe to this queue.

Syntax

TYPE aq$_subscriber_list_t IS TABLE OF aq$_agent  
          INDEX BY BINARY INTEGER; 

AQ Registration Info List Type (aq$_reg_info_list)

Purpose

To identify the list of registrations to a queue.

Syntax

TYPE aq$_reg_info_list AS VARRAY(1024) OF sys.aq$_reg_info

AQ Post Info List Type (aq$_post_info_list)

Purpose

To identify the list of anonymous subscriptions to which messages are posted.

Syntax

TYPE aq$_post_info_list AS VARRAY(1024) OF sys.aq$_post_info

AQ Registration Info Type

The aq$_reg_info data structure identifies a producer or a consumer of a message.

Syntax

TYPE sys.aq$_reg_info IS OBJECT (
   name      VARCHAR2(128),
   namespace NUMBER,
   callback  VARCHAR2(4000),
   context   RAW(2000));

Attributes

Table 2-3 AQ Registration Info Type Attributes

name

namespace

callback

context

Table 2-4 shows the actions performed when different notification mechanisms/presentations are specified for nonpersistent queues.

Table 2-4 Nonpersistent Queues

AQ Notification Descriptor Type

The aq$_descriptor data structure specifies the AQ Descriptor received by the AQ PL/SQL callbacks upon notification.

Syntax

TYPE sys.aq$_descriptor IS OBJECT (
  queue_name    VARCHAR2(30),
  consumer_name VARCHAR2(30),
  msg_id        RAW(16),
  msg_prop      msg_prop_t);

Attributes

Table 2-5 AQ Notification Descriptor Type

queue_name

consumer_name

msg_id

msg_prop

AQ Post Info Type

The aq$_post_info data structure specifies anonymous subscriptions to which you want to post messages.

Syntax

TYPE sys.aq$_post_info IS OBJECT (
  name       VARCHAR2(128),
  namespace  NUMBER,
  payload    RAW(2000));

Attributes

Table 2-6 AQ Post Info Type Attributes

name

namespace

payload

Enumerated Constants in the Administrative Interface

When enumerated constants such as INFINITE, TRANSACTIONAL, and NORMAL_QUEUE are selected as values, the symbol must be specified with the scope of the packages defining it. All types associated with the administrative interfaces must be prepended with DBMS_AQADM. For example:

DBMS_AQADM.NORMAL_QUEUE

Table 2-7 lists the enumerated constants.

Table 2-7 Enumerated Constants in the Administrative Interface

Enumerated Constants in the Operational Interface

When using enumerated constants such as BROWSE, LOCKED, and REMOVE, the PL/SQL constants must be specified with the scope of the packages defining them. All types associated with the operational interfaces must be prepended with DBMS_AQ. For example:

DBMS_AQ.BROWSE

Table 2-8 lists the enumerated constants.

Table 2-8 Enumerated Constants in the Operational Interface

namespace

NAMESPACE_AQ, NAMESPACE_ANONYMOUS

INIT.ORA Parameter File Considerations

You can specify the AQ_TM_PROCESSES and JOB_QUEUE_PROCESSES parameters in the init.ora parameter file.

AQ_TM_PROCESSES Parameter

A parameter called AQ_TM_PROCESSES should be specified in the init.ora parameter file if you want to perform time monitoring on queue messages. Use this for messages that have delay and expiration properties specified. This parameter should be set to at least 1. It can be set in a range from 0 to 10. Setting it to any other number will result in an error. If this parameter is set to 1, one queue monitor process (QMN) will be created as a background process. If the parameter is not specified, or is set to 0, the queue monitor process is not created.

Table 2-9 lists parameter information.

Table 2-9 AQ_TM_PROCESSES Parameter

JOB_QUEUE_PROCESSES Parameter

Propagation is handled by job queue (SNP) processes. The number of job queue processes started in an instance is controlled by the init.ora parameter JOB_QUEUE_PROCESSES. The default value of this parameter is 0. For message propagation to take place, this parameter must be set to at least 2. The database administrator can set it to higher values if there are many queues from which the messages have to be propagated, or if there are many destinations to which the messages have to be propagated, or if there are other jobs in the job queue.

The Java Advanced Queuing API supports both the administrative and operational features of Advanced Queuing. In developing Java programs for messaging applications, you will use JDBC to open a connection to the database and then use oracle.AQ, the Java AQ API for message queuing. This means that you will no longer need to use PL/SQL interfaces.