Contents

Title and Copyright Information

Send Us Your Comments

Preface

Audience

Organization

Related Documentation

Conventions

Documentation Accessibility

What's New in Advanced Queuing?

Oracle9i Release 2 (9.2.0) New Features

Oracle9i (9.0.1) New Features in Advanced Queuing

Oracle8i New Features in Advanced Queuing

1 Introduction to Oracle Advanced Queuing

What Is Advanced Queuing?

Advanced Queuing in Integrated Application Environments

Interfaces to Advanced Queuing

Queuing System Requirements

General Features of Advanced Queuing

Point-to-Point and Publish-Subscribe Messaging

Oracle Internet Directory

Oracle Enterprise Manager Integration

Message Format Transformation

SQL Access

Support for Statistics Views

Structured Payloads

Retention and Message History

Tracking and Event Journals

Queue-Level Access Control

Nonpersistent Queues

Support for Oracle9i Real Application Clusters

XMLType Payloads

Internet Integration and Internet Data Access Presentation

Nonrepudiation and the AQ$<QueueTableName> View

Enqueue Features

Correlation Identifiers

Subscription and Recipient Lists

Priority and Ordering of Messages in Enqueuing

Message Grouping

Propagation

Sender Identification

Time Specification and Scheduling

Rule-Based Subscribers

Asynchronous Notification

Dequeue Features

Recipients

Navigation of Messages in Dequeuing

Modes of Dequeuing

Optimization of Waiting for the Arrival of Messages

Retries with Delays

Optional Transaction Protection

Exception Handling

Listen Capability (Wait on Multiple Queues)

Dequeue Message Header with No Payload

Propagation Features

Automated Coordination of Enqueuing and Dequeuing

Propagation of Messages with LOBs

Propagation Scheduling

Enhanced Propagation Scheduling Capabilities

Third-Party Support

Elements of Advanced Queuing

Message

Queue

Queue Table

Agent

Recipient

Recipient and Subscription Lists

Rule

Rule-Based Subscribers

Transformation

Queue Monitor

Java Message Service Terminology

Demos

2 Basic Components

Data Structures

Object Name (object_name)

Type Name (type_name)

Agent Type (aq$_agent)

AQ Recipient List Type (aq$_recipient_list_t)

AQ Agent List Type (aq$_agent_list_t)

AQ Subscriber List Type (aq$_subscriber_list_t)

AQ Registration Info List Type (aq$_reg_info_list)

AQ Post Info List Type (aq$_post_info_list)

AQ Registration Info Type

AQ Notification Descriptor Type

AQ Post Info Type

Enumerated Constants in the Administrative Interface

Enumerated Constants in the Operational Interface

INIT.ORA Parameter File Considerations

AQ_TM_PROCESSES Parameter

JOB_QUEUE_PROCESSES Parameter

3 AQ Programmatic Environments

Programmatic Environments for Accessing AQ

Using PL/SQL to Access AQ

Using OCI to Access AQ

Examples

Using Visual Basic (OO4O) to Access AQ

For More Information

Using AQ Java (oracle.AQ) Classes to Access AQ

Accessing Java AQ Classes

Advanced Queuing Examples

Managing the Java AQ API

Using Oracle Java Message Service to Access AQ

Standard JMS Features

Oracle JMS Extensions

Accessing Standard and Oracle JMS

For More Information

Using the AQ XML Servlet to Access AQ

Comparing AQ Programmatic Environments

AQ Administrative Interfaces

AQ Operational Interfaces

4 Managing AQ

Security

Administrator Role

User Role

Access to AQ Object Types

Oracle 8.1-Style Queues

Compatibility

Security

Privileges and Access Control

LNOCI Applications

Security Required for Propagation

Queue Table Export-Import

Exporting Queue Table Data

Importing Queue Table Data

Creating AQ Administrators and Users

Oracle Enterprise Manager Support

Using Advanced Queuing with XA

Restrictions on Queue Management

Collection Types in Message Payloads

Synonyms on Queue Tables and Queues

Tablespace Point-in-Time Recovery

Nonpersistent Queues

Propagation Issues

Execute Privileges Required for Propagation

The Number of Job Queue Processes

Optimizing Propagation

Propagation from Object Queues

Guidelines for Debugging AQ Propagation Problems

Oracle 8.0-Style Queues

Migrating To and From 8.0

Importing and Exporting with 8.0-Style Queues

Roles in 8.0

Security with 8.0-Style Queues

Access to AQ Object Types

LNOCI Application Access to 8.0-Style Queues

Pluggable Tablespaces and 8.0-Style Multiconsumer Queues

Autocommit Features in the DBMS_AQADM Package

5 Performance and Scalability

Performance Overview

Advanced Queuing in the Oracle Real Application Clusters Environment

Advanced Queuing in a Shared Server Environment

Basic Tuning Tips

Running Enqueue and Dequeue Processes Concurrently--Single Queue Table

Running Enqueue and Dequeue Processes in Serial--Single Queue Table

Propagation Tuning Tips

6 Frequently Asked Questions

General Questions

Messaging Gateway Questions

Propagation Questions

Transformation Questions

JMS Questions

Internet Access Questions

Oracle Internet Directory Questions--Global Agents, Global Events, and Global
Queues

Transformation Questions

Performance Questions

Installation Questions

7 Modeling and Design

Modeling Queue Entities

Basic Queuing

Basic Queuing Illustrated

AQ Client-Server Communication

Multiconsumer Dequeuing of the Same Message

Dequeuing of Specified Messages by Specified Recipients

AQ Implementation of Workflows

AQ Implementation of Publish/Subscribe

Message Propagation

Propagation and Advanced Queuing

8 A Sample Application Using AQ

A Sample Application

General Features of Advanced Queuing

System-Level Access Control

Queue-Level Access Control

Message Format Transformation

Structured Payloads

XMLType Queue Payloads

Nonpersistent Queues

Retention and Message History

Publish-Subscribe Support

Support for Oracle Real Application Clusters

Support for Statistics Views

Internet Access

Enqueue Features

Subscriptions and Recipient Lists

Priority and Ordering of Messages

Time Specification: Delay

Time Specification: Expiration

Message Grouping

Message Transformation During Enqueue

Enqueue Using the AQ XML Servlet

Dequeue Features

Dequeue Methods

Multiple Recipients

Local and Remote Recipients

Message Navigation in Dequeue

Modes of Dequeuing

Optimization of Waiting for Arrival of Messages

Retry with Delay Interval

Exception Handling

Rule-Based Subscription

Listen Capability

Message Transformation During Dequeue

Dequeue Using the AQ XML Servlet

Asynchronous Notifications

Registering for Notifications Using the AQ XML Servlet

Propagation Features

Propagation

Propagation Scheduling

Propagation of Messages with LOB Attributes

Enhanced Propagation Scheduling Capabilities

Exception Handling During Propagation

Message Format Transformation During Propagation

Propagation Using HTTP

9 Administrative Interface

Use Case Model: Administrative Interface -- Basic Operations

Creating a Queue Table

Creating a Queue Table [Set Storage Clause]

Altering a Queue Table

Dropping a Queue Table

Creating a Queue

Creating a Nonpersistent Queue

Altering a Queue

Dropping a Queue

Creating a Transformation

Modifying a Transformation

Applying a Transformation

Dropping a Transformation

Starting a Queue

Stopping a Queue

Granting System Privilege

Revoking System Privilege

Granting Queue Privilege

Revoking Queue Privilege

Adding a Subscriber

Altering a Subscriber

Removing a Subscriber

Scheduling a Queue Propagation

Unscheduling a Queue Propagation

Verifying a Queue Type

Altering a Propagation Schedule

Enabling a Propagation Schedule

Disabling a Propagation Schedule

Creating an AQ Agent

Altering an AQ Agent

Dropping an AQ Agent

Enabling Database Access

Disabling Database Access

Adding an Alias to the LDAP Server

Removing an Alias from the LDAP Server

10 Administrative Interface: Views

Use Case Model: Administrative Interface--Views

Selecting All Queue Tables in Database

Selecting User Queue Tables

Selecting All Queues in Database

Selecting All Propagation Schedules

Selecting Queues for Which User Has Any Privilege

Selecting Queues for Which User Has Queue Privilege

Selecting Messages in Queue Table

Selecting Queue Tables in User Schema

Selecting Queues In User Schema

Selecting Propagation Schedules in User Schema

Selecting Queue Subscribers

Selecting Queue Subscribers and Their Rules

Selecting the Number of Messages in Different States for the Whole Database

Selecting the Number of Messages in Different States for Specific Instances

Selecting the AQ Agents Registered for Internet Access

Selecting User Transformations

Selecting User Transformation Functions

Selecting All Transformations

Selecting All Transformation Functions

11 Operational Interface: Basic Operations

Use Case Model: Operational Interface -- Basic Operations

Enqueuing a Message

Enqueuing a Message [Specify Options]

Enqueuing a Message [Specify Message Properties]

Enqueuing a Message [Specify Message Properties [Specify Sender ID]]

Enqueuing a Message [Add Payload]

Listening to One or More Single-Consumer Queues

Listening to One or More Multiconsumer Queues

Dequeuing a Message

Dequeuing a Message from a Single-Consumer Queue [SpecifyOptions]

Dequeuing a Message from a Multiconsumer Queue [Specify Options]

Registering for Notification

Registering for Notification [Specifying Subscription Name--Single-Consumer
Queue]

Registering for Notification [Specifying Subscription Name--Multiconsumer Queue]

Posting for Subscriber Notification

Adding an Agent to the LDAP Server

Removing an Agent from the LDAP Server

12 Creating Applications Using JMS

A Sample Application Using JMS

General Features of JMS

J2EE Compliance

JMS Connection and Session

JMS Destinations - Queue and Topic

System-Level Access Control in JMS

Destination-Level Access Control in JMS

Retention and Message History in JMS

Supporting Oracle Real Application Clusters in JMS

Supporting Statistics Views in JMS

Structured Payload/Message Types in JMS

Payload Used by JMS Examples

JMS Point-to-Point Model Features

Queues

Queue Sender

Queue Receiver

Queue Browser

JMS Publish-Subscribe Model Features

Topic

Durable Subscriber

Topic Publisher

Recipient Lists

TopicReceiver

Topic Browser

JMS Message Producer Features

Priority and Ordering of Messages

Time Specification - Delay

Time Specification - Expiration

Message Grouping

JMS Message Consumer Features

Receiving Messages

Message Navigation in Receive

Modes for Receiving Messages

Retry With Delay Interval

Asynchronously Receiving Message Using Message Listener

AQ Exception Handling

JMS Propagation

Remote Subscribers

Scheduling Propagation

Enhanced Propagation Scheduling Capabilities

Exception Handling During Propagation

Message Transformation with JMS AQ

Defining Message Transformations

Sending Messages to a Destination Using a Transformation

Receiving Messages from a Destination Using a Transformation

Specifying Transformations for Topic Subscribers

Specifying Transformations for Remote Subscribers

13 JMS Administrative Interface: Basic Operations

Use Case Model: JMS Administrative Interface -- Basic Operations

Registering a Queue/Topic Connection Factory Through the Database
--with JDBC Connection Parameters

Registering a Queue/Topic Connection Factory Through the Database
--with a JDBC URL

Registering a Queue/Topic Connection Factory Through LDAP
--with JDBC Connection Parameters

Registering a Queue/Topic Connection Factory Through LDAP--with a JDBC URL

Unregistering a Queue/Topic Connection Factory in LDAP Through the Database

Unregistering a Queue/Topic Connection Factory in LDAP Through LDAP

Getting a Queue Connection Factory with JDBC URL

Getting a Queue Connection Factory with JDBC Connection Parameters

Getting a Topic Connection Factory with JDBC URL

Getting a Topic Connection Factory with JDBC Connection Parameters

Getting a Queue/Topic Connection Factory in LDAP

Getting a Queue/Topic in LDAP

Creating a Queue Table

Creating a Queue Table [Specify Queue Table Property]

Getting a Queue Table

Specifying Destination Properties

Creating a Queue--Point-to-Point

Creating a Topic--Publish-Subscribe

Granting System Privileges

Revoking System Privileges

Granting Topic Privileges--Publish-Subscribe

Revoking Topic Privileges--Publish-Subscribe

Granting Queue Privileges--Point-to-Point

Revoking Queue Privileges--Point-to-Point

Starting a Destination

Stopping a Destination

Altering a Destination

Dropping a Destination

Scheduling a Propagation

Enabling a Propagation Schedule

Altering a Propagation Schedule

Disabling a Propagation Schedule

Unscheduling a Propagation

14 JMS Operational Interface: Basic Operations (Point-to-Point)

Use Case Model: Operational Interface -- Basic Operations

Creating a Queue Connection with Username/Password

Creating a Queue Connection with an Open JDBC Connection

Creating a Queue Connection with Default Connection Factory Parameters

Creating a Queue Connection with an Open OracleOCIConnection Pool

Creating a Queue Session

Creating a Queue Sender

Sending a Message Using a Queue Sender with Default Send Options

Sending Messages Using a Queue Sender by Specifying Send Options

Creating a Queue Browser for Queues with Text, Stream, Objects,
Bytes or Map Messages

Creating a Queue Browser for Queues with Text, Stream, Objects,
Bytes, Map Messages, Locking Messages

Creating a Queue Browser for Queues of Oracle Object Type (ADT) Messages

Creating a Queue Browser for Queues of Oracle Object Type (ADT) Messages,
Locking Messages While Browsing

Browsing Messages Using a Queue Browser

Creating a Queue Receiver for Queues of Standard JMS Type Messages

Creating a Queue Receiver for Queues of Oracle Object Type (ADT) Messages

Creating a Queue Connection with an Open OracleOCIConnection Pool

15 JMS Operational Interface: Basic Operations (Publish-Subscribe)

Use Case Model: JMS Operational Interface -- Basic Operations (Publish-Subscribe)

Creating a Topic Connection with Username/Password

Creating a Topic Connection with Open JDBC Connection

Creating a Topic Connection with Default Connection Factory Parameters

Creating a Topic Connection with an Open OracleOCIConnectionPool

Creating a Topic Session

Creating a Topic Publisher

Publishing a Message Using a Topic Publisher--with Minimal Specification

Publishing a Message Using a Topic Publisher--Specifying Correlation and Delay

Publishing a Message Using a Topic Publisher--Specifying Priority and Time-To-Live

Publishing a Message Using a Topic Publisher--Specifying a Recipient List
Overriding Topic Subscribers

Creating a Durable Subscriber for a JMS Topic without Selector

Creating a Durable Subscriber for a JMS Topic with Selector

Creating a Durable Subscriber for an ADT Topic without Selector

Creating a Durable Subscriber for an ADT Topic with Selector

Creating a Remote Subscriber for Topics of JMS Messages

Creating a Remote Subscriber for Topics of Oracle Object Type (ADT) Messages

Unsubscribing a Durable Subscription for a Local Subscriber

Unsubscribing a Durable Subscription for a Remote Subscriber

Creating a Topic Receiver for a Topic of Standard JMS Type Messages

Creating a Topic Receiver for a Topic of Oracle Object Type (ADT) Messages

Creating a Topic Browser for Topics with Text, Stream, Objects, Bytes
or Map Messages

Creating a Topic Browser for Topics with Text, Stream, Objects, Bytes,
Map Messages, Locking Messages While Browsing

Creating a Topic Browser for Topics of Oracle Object Type (ADT) Messages

Creating a Topic Browser for Topics of Oracle Object Type (ADT) Messages,
Locking Messages While Browsing

Browsing Messages Using a Topic Browser

16 JMS Operational Interface: Basic Operations (Shared Interfaces)

Use Case Model: JMS Operational Interface -- Basic Operations (Shared Interfaces)

Starting a JMS Connection

Getting the JMS Connection from a Session

Committing All Operations in a Session

Rolling Back All Operations in a Session

Getting the Underlying JDBC Connection from a JMS Session

Getting the Underlying OracleOCIConnectionPool from a JMS Connection

Creating a Bytes Message

Creating a Map Message

Creating a Stream Message

Creating an Object Message

Creating a Text Message

Creating a JMS Message

Creating a JMS Message (Header Only)

Creating an ADT Message

Specifying Message Correlation ID

Specifying JMS Message Property

Specifying JMS Message Property as Boolean

Specifying JMS Message Property as String

Specifying JMS Message Property as Int

Specifying JMS Message Property as Double

Specifying JMS Message Property as Float

Specifying JMS Message Property as Byte

Specifying JMS Message Property as Long

Specifying JMS Message Property as Short

Specifying JMS Message Property as Object

Setting Default TimeToLive for All Messages Sent by a Message Producer

Setting Default Priority for All Messages Sent by a Message Producer

Creating an AQjms Agent

Receiving a Message Synchronously Using a Message Consumer
by Specifying Timeout

Receiving a Message Synchronously Using a Message Consumer Without Waiting

Specifying the Navigation Mode for Receiving Messages

Specifying a Message Listener to Receive a Message Asynchronously
at the Message Consumer

Specifying a Message Listener to Receive a Message Asynchronously at the Session

Getting the Correlation ID of a Message

Getting the Message ID of a Message as Bytes

Getting the Message ID of a Message as a String

Getting the JMS Message Property

Getting the JMS Message Property as a Boolean

Getting the JMS Message Property as a String

Getting the JMS Message Property as Int

Getting the JMS Message Property as Double

Getting the JMS Message Property as Float

Getting the JMS Message Property as Byte

Getting the JMS Message Property as Long

Getting the JMS Message Property as Short

Getting the JMS Message Property as Object

Closing a Message Producer

Closing a Message Consumer

Stopping a JMS Connection

Closing a JMS Session

Closing a JMS Connection

Getting the Error Code for the JMS Exception

Getting the Error Number for the JMS Exception

Getting the Error Message for the JMS Exception

Getting the Exception Linked to the JMS Exception

Printing the Stack Trace for the JMS Exception

Setting the Exception Listener

Getting the Exception Listener

Setting the Ping Period for the Exception Listener

Getting the Ping Period for the Exception Listener

17 Internet Access to Advanced Queuing

Overview of Advanced Queuing Operations Over the Internet

The Internet Data Access Presentation (IDAP)

SOAP Message Structure

SOAP Method Invocation

IDAP Documents

SOAP and AQ XML Schemas

The SOAP Schema

IDAP Schema

Deploying the AQ XML Servlet

Creating the AQ XML Servlet Class

Compiling the AQ XML Servlet

User Authentication

User Authorization

Using an LDAP Server with an AQ XML Servlet

Setup for Receiving AQ XML Requests Using SMTP (E-mail)

Using HTTP to Access the AQ XML Servlet

User Sessions and Transactions

Using HTTP and HTTPS for Advanced Queuing Propagation

High-Level Architecture

Using SMTP to Access the AQ Servlet

Customizing the AQ Servlet

Setting the Connection Pool Size

Setting the Session Timeout

Setting the Style Sheet for All Responses from the Servlet

Callbacks Before and After AQ Operations

18 Messaging Gateway

Messaging Gateway Functionality

Messaging Gateway Architecture

Administration Package

Gateway Agent

Propagation Processing Overview

Setting Up Messaging Gateway

Oracle9i Database Prerequisites

Non-Oracle Messaging System Prerequisites

Loading and Setup Tasks

Setup Verification

Unloading Messaging Gateway

Working with Messaging Gateway

Managing the Messaging Gateway Agent

Configuring Messaging Gateway Links

Registering Non-Oracle Messaging System Queues

Configuring Propagation Jobs

Monitoring the Messaging Gateway Log File

Converting Messages

The Message Conversion Process

Messaging Gateway Canonical Types

Message Conversion for Advanced Queuing

Message Conversion for MQSeries

Message Header Conversions

Using Header Properties: Examples

Using XML Message Propagation: Examples

The mgw.ora Initialization File

File Contents

Initialization Parameters

Environment Variables

Java Properties

A Oracle Advanced Queuing by Example

Creating Queue Tables and Queues

Creating a Queue Table and Queue of Object Type

Creating a Queue Table and Queue of Raw Type

Creating a Prioritized Message Queue Table and Queue

Creating a Multiconsumer Queue Table and Queue

Creating a Queue to Demonstrate Propagation

Setting Up Java AQ Examples

Creating an Java AQ Session

Creating a Queue Table and Queue Using Java

Creating a Queue and Start Enqueue/Dequeue Using Java

Creating a Multiconsumer Queue and Add Subscribers Using Java

Enqueuing and Dequeuing Of Messages

Enqueuing and Dequeuing of Object Type Messages Using PL/SQL

Enqueuing and Dequeuing of Object Type Messages Using Pro*C/C++

Enqueuing and Dequeuing of Object Type Messages Using OCI

Enqueuing and Dequeuing of Object Type Messages (CustomDatum interface)
Using Java

Enqueuing and Dequeuing of Object Type Messages (using SQLData interface)
Using Java

Enqueuing and Dequeuing of RAW Type Messages Using PL/SQL

Enqueuing and Dequeuing of RAW Type Messages Using Pro*C/C++

Enqueuing and Dequeuing of RAW Type Messages Using OCI

Enqueue of RAW Messages using Java

Dequeue of Messages Using Java

Dequeue of Messages in Browse Mode Using Java

Enqueuing and Dequeuing of Messages by Priority Using PL/SQL

Enqueue of Messages with Priority Using Java

Dequeue of Messages after Preview by Criterion Using PL/SQL

Enqueuing and Dequeuing of Messages with Time Delay and Expiration
Using PL/SQL

Enqueuing and Dequeuing of Messages by Correlation and Message ID
Using Pro*C/C++

Enqueuing and Dequeuing of Messages by Correlation and Message ID Using OCI

Enqueuing and Dequeuing of Messages to/from a Multiconsumer Queue
Using PL/SQL

Enqueuing and Dequeuing of Messages to/from a Multiconsumer Queue using OCI

Enqueuing and Dequeuing of Messages Using Message Grouping Using PL/SQL

Enqueuing and Dequeuing Object Type Messages That Contain LOB Attributes
Using PL/SQL

Enqueuing and Dequeuing Object Type Messages That Contain LOB Attributes
Using Java

Propagation

Enqueue of Messages for remote subscribers/recipients to a Multiconsumer Queue
and Propagation Scheduling Using PL/SQL

Managing Propagation From One Queue To Other Queues In The Same Database
Using PL/SQL

Manage Propagation From One Queue To Other Queues In Another Database
Using PL/SQL

Unscheduling Propagation Using PL/SQL

Dropping AQ Objects

Revoking Roles and Privileges

Deploying AQ with XA

AQ and Memory Usage

Create_types.sql: Create Payload Types and Queues in Scott's Schema

Enqueuing Messages (Free Memory After Every Call) Using OCI

Enqueuing Messages (Reuse Memory) Using OCI

Dequeuing Messages (Free Memory After Every Call) Using OCI

Dequeuing Messages (Reuse Memory) Using OCI

B Oracle JMS Interfaces, Classes, and Exceptions

Oracle JMSClasses (part 1)

Oracle JMS Classes (part 2)

Oracle JMS Classes (part 3)

Oracle JMS Classes (part 4)

Oracle JMS Classes (part 5)

Oracle JMS Classes (part 6)

Oracle JMS Classes (part 6 continued)

Oracle JMS Classes (part 7)

Oracle JMS Classes (part 8)

Oracle JMS Classes (part 9)

Oracle JMS Classes (part 10)

Oracle JMS Classes (part 10 continued)

Interfaces, Classes, and Exceptions

C Scripts for Implementing BooksOnLine

tkaqdoca.sql: Script to Create Users, Objects, Queue Tables, Queues & Subscribers

tkaqdocd.sql: Examples of Administrative and Operational Interfaces

tkaqdoce.sql: Operational Examples

tkaqdocp.sql: Examples of Operational Interfaces

tkaqdocc.sql: Clean-Up Script

D JMS and AQ XML Servlet Error Messages

JMS Error Messages

AQ XML Servlet Error Messages

E Unified Modeling Language Diagrams

Use Case Diagrams

State Diagrams

Index