Preface

This Guide describes features of application development on the Oracle Server having to do with Oracle Advanced Queuing, Release 8.1.5. Information in this Guide applies to versions of the Oracle Server that run on all platforms, and does not include system-specific information.

The Preface includes the following sections:

Information in This Guide

Oracle Advanced Queueing (Oracle AQ) provides message queuing as an integrated part of the Oracle server. Oracle AQ provides this functionality by integrating the queuing system with the database, thereby creating a message-enabled database. By providing an integrated solution Oracle AQ frees application developers to devote their efforts to their specific business logic rather than having to construct a messaging infrastructure.

The Oracle8i Application Developer's Guide - Advanced Queuing is intended for programmers developing new applications that use Oracle Advanced Queuing, as well as those who have already implemented this technology and now wish to take advantage of new features.

The increasing importance of Oracle AQ has led to its being presented as an independent volume within the Oracle Application Developers documentation set.

Feature Coverage and Availability

For information about the differences between Oracle8 and the Oracle8 Enterprise Edition and the features and options that are available to you, see Getting to Know Oracle8i.

New Features Introduced with Oracle 8.1

Queue Level Access Control
Non-Persistent Queues
Support for OPS Environments
Rule-based Subscribers forPublish/Subscribe
Asynchronous Notification
Sender Identification
Listen Capability (Wait on Multiple Queues)
Propagation of Messages with LOBs
Enhanced Propagation Scheduling Capabilities
Dequeue Message Header Only With No Payload
Support for Statistics Views
Separate storage of history management information
For more information about Oracle AQ features, see:

Chapter 2, "Implementing AQ -- A Sample Application"

Other Guides

Use the PL/SQL User's Guide and Reference to learn PL/SQL and to get a complete description of this high-level programming language, which is Oracle Corporation's procedural extension to SQL.

The Oracle Call Interface (OCI) is described in:

Oracle Call Interface Programmer's Guide

You can use the OCI to build third-generation language (3GL) applications that access the Oracle Server.

Oracle Corporation also provides the Pro* series of precompilers, which allow you to embed SQL and PL/SQL in your application programs. If you write 3GL application programs in Ada, C, C++, COBOL, or FORTRAN that incorporate embedded SQL, refer to the corresponding precompiler manual. For example, if you program in C or C++, refer to the Pro*C/C++ Precompiler Programmer's Guide.

For SQL information, see the Oracle8i SQL Reference and Oracle8i Administrator's Guide. For basic Oracle concepts, see Oracle8i Concepts.

How This Book Is Organized

The Application Developer's Guide - Advanced Queuing contains seven chapters and an appendix. A brief summary of what you will find in each chapter follows:

Chapter 1, "Introduction"

This chapter 'sets the bar' by describing the requirements for optimal messaging systems. Although Oracle AQ is a relatively new technology, and not all these goals have been realized, you can get an overview of the underlying design and a clear idea of the intended direction.

Chapter 2, "Implementing AQ -- A Sample Application"

This chapter describes features already present in Oracle AQ under three headings: General Features, Enqueue Features, and Dequeue Features.

Chapter 3, "Managing Oracle AQ"

This chapter describes the primary queuing entities (message, queue, queue table, agent, queue monitor), and the basics of connecting single/multiple producers of messages with single/multiple consumers of messages. Of particular interest is the way messages can directed toward specific subscribers implicitly, explicitly or on the basis of rules.

Chapter 4, "Administrative Interface: Basic Operations"

As its title indicates, this chapter presents the basic operations underlying the Administrative interface, such as Create Queue Table, Create Queue, Grant Queue Privilege, Add a Subscriber, and Schedule a Propagation. We have introduced a new way of presenting this information that utilizes the Unified Modelling Language (detailed notes are included below). On-line users will additionally be able to make use of hypertext links and image-based hot links

Chapter 5, "Administrative Interface: Views"

This chapter is dedicated to the various views that Oracle has provided for administrators and users that are projected as a result of queries, such as Select All Queue Tables in the Database, Select Messages in a Queue Table, and Select Queue Subscribers and their Rules.

Chapter 6, "Operational Interface: Basic Operations"

We here describe the essentials of the operational interface in terms of the basic operations concerned with enqueuing a message, dequeuing a message, registering for messages based on defined rules, and listening to one or more queues for messages.

Chapter 7, "Advanced Queuing -- Java API"

This chapter introduces and details the Java Application Programmer's Interface for Advanced Queuing.

Chapter 8, "Oracle Advanced Queuing by Example"

As you can see by examining the Table of Contents, small examples are interspersed throughout the text, but this chapter is dedicated solely to providing examples in both PL/SQL and OCI.

Chapter A, "Scripts for Implementing 'BooksOnLine'"

This appendix has the scripts for implementing the sample application, BooksOnLine.

Visual Modelling

This release introduces the Universal Modeling Language (UML) as a way of explaining the technology that we hope will help you develop applications. A full presentation of the UML is beyond the scope of this documentation set, however we do provide a description of the subset of UML notation that we use in a chapter devoted to visual modelling inOracle8i Application Developer's Guide - Fundamentals. What follows here is a selection from that chapter of those elements that are used in this book.

Use Case Diagrams

Graphic Element Description

This release of the documentation introduces and makes heavy use of the Use Case Diagram. Each primary use case is instigated by an actor ('stickman') that could be a human user, an application, or a sub-program. The actor is connected to the primary use case which is depicted as an oval (bubble) enclosing the use case action.
The totality of primary use cases is described by means of a Use Case Model Diagram.

Primary use cases may require other operations to complete them. In this diagram fragment

specify queue name

is one of the sub-operations, or secondary use cases, needed to complete

ENQUEUE a message

The downward lines from the primary use case lead to the other required operations (not shown).

Secondary use cases that have drop shadows 'expand' in that they are described by means of their own use case diagrams. There are two reasons for doing this:
(a) it makes it easier to understand the logic of the operation;
(b) it would not have been possible to place all the operations and sub-operations on the same page.
In this example

specify message properties,

specify options

add payload

are all expanded in separate use case diagrams.

This diagram fragment shows the use case diagram expanded. While the standard diagram has the actor as the initiator), here the use case itself is the point of departure for the sub-operation. In this example, the expanded view of

add payload

represents a constituent operation of

ENQUEUE a message

This convention (a, b, c) shows that there are three different ways of creating a table that contains LOBs.

This fragment shows one of the uses of a NOTE box, here distinguishing which of the three ways of creating a table containing LOBs is being presented.

Graphic Element	Description
	This release of the documentation introduces and makes heavy use of the Use Case Diagram. Each primary use case is instigated by an actor ('stickman') that could be a human user, an application, or a sub-program. The actor is connected to the primary use case which is depicted as an oval (bubble) enclosing the use case action. The totality of primary use cases is described by means of a Use Case Model Diagram.
	Primary use cases may require other operations to complete them. In this diagram fragment `specify` `queue name` is one of the sub-operations, or secondary use cases, needed to complete `ENQUEUE` `a message` The downward lines from the primary use case lead to the other required operations (not shown).
	Secondary use cases that have drop shadows 'expand' in that they are described by means of their own use case diagrams. There are two reasons for doing this: (a) it makes it easier to understand the logic of the operation; (b) it would not have been possible to place all the operations and sub-operations on the same page. In this example `specify` `message properties,` `specify` `options` `add` `payload` are all expanded in separate use case diagrams.
	This diagram fragment shows the use case diagram expanded. While the standard diagram has the actor as the initiator), here the use case itself is the point of departure for the sub-operation. In this example, the expanded view of `add` `payload` represents a constituent operation of `ENQUEUE` `a message`
	This convention (a, b, c) shows that there are three different ways of creating a table that contains LOBs.
	This fragment shows one of the uses of a NOTE box, here distinguishing which of the three ways of creating a table containing LOBs is being presented.

Graphic Element

Description
This drawing shows two other common use of NOTE boxes:
(a) as a way of presenting an alternative name, as in this case the action SELECT propagation schedules in the user schema is represented by the view USER_QUEUE_SCHEDULES
(b) the action list attribute names is qualified by the note to the user that you must list at least one attribute if you elect not to list all the propagation schedule attributes.

Graphic Element Description

The dotted arrow in the use case diagram indicates dependency. In this example

free a temporary LOB

requires that you first

create a temporary LOB

Put another way: you should not execute the free operation on a LOB that is not temporary.
What you need to remember is that the target of the arrow shows the operation that must be performed first.

Use cases and their sub-operations can be linked in complex relationships. In this example of a callback, you must earlier

REGISTER for notification

in order to later

receive a notification

Graphic Element

Description
In this case the branching paths of an OR condition are shown. In invoking the view, you may choose either to list all the attributes or you may view one or more attributes. The fact that you may stipulate which of the attributes you wish made visible is indicated by the grayed arrow.

Graphic Element

Description
Not all linked operations are mandatory. While the black dashed-line and arrow indicate that you must perform the targeted operation to complete the use case, actions that are optional are shown by the grey dashed-line and arrow. In this example, executing

write append

on a LOB requires that you first

SELECT a LOB

As a facilitating operations, you may choose to

OPEN a LOB and/or get chunk size

However, note that if you do OPEN a LOB, you will later have to CLOSE it.

State Diagrams

Graphic Element

Description
All the previous notes have dealt with use case diagrams. Here we introduce the very basic application of a state diagram that we utilize in this book to present the attributes of view. In fact, attributes of a view have only two states -- visible or invisible. We are not interested in showing the permutations of state but in showing what you might make visible in invoking a view. Accordingly, we have extended the UML to join a partial state diagram onto a use case diagram to show the totality of attributes, and thereby all the view sub-states of the view that you can see. We have demarcated the use case from the view state by coloring the background of the state diagram grey.
In this example, the view AQ$<queue_table_name>_S allows you to query queue subscribers. You can stipulate one attribute, or some combination of the four attributes, or all of the four attributes.

Graphic Element Description

Use Case Model Diagrams summarize all the use cases in a particular domain, such as Internal temporary LOBs. Often these diagrams are too complex to contain within a single page. When that happens we have resorted to dividing the diagram into two parts. Please note that there is no sequence implied in this division.

In some cases we have had to split a diagram simply because it is too long for the page. In such cases, we have included this marker.

Conventions Used in this Guide

The following notational and text formatting conventions are used in this guide:

[ ]

Square brackets indicate that the enclosed item is optional. Do not type the brackets.

{ }

Braces enclose items of which only one is required.

|

A vertical bar separates items within braces, and may also be used to indicate that multiple values are passed to a function parameter.

...

In code fragments, an ellipsis means that code not relevant to the discussion has been omitted.

font change

SQL or C code examples are shown in monospaced font.

italics

Italics are used for OCI parameters, OCI routines names, file names, and data fields.

UPPERCASE

Uppercase is used for SQL keywords, like SELECT or UPDATE.

This guide uses special text formatting to draw the reader's attention to some information. A paragraph that is indented and begins with a bold text label may have special meaning. The following paragraphs describe the different types of information that are flagged this way.

Note: The "Note" flag indicates that the reader should pay particular attention to the information to avoid a common problem or increase understanding of a concept.

Warning: An item marked as "Warning" indicates something that an OCI programmer must be careful to do or not do in order for an application to work correctly.

See Also: Text marked "See Also" points you to another section of this guide, or to other documentation, for additional information about the topic being discussed.

Your Comments Are Welcome

We value and appreciate your comment as an Oracle user and reader of our manuals. As we write, revise, and evaluate our documentation, your opinions are the most important feedback we receive.

You can send comments and suggestions about this manual to the following e-mail address:

infodev@us.oracle.com

If you prefer, you can send letters or faxes containing your comments to the following address:

Server Technologies Documentation Manager

Oracle Corporation

500 Oracle Parkway

Redwood Shores, CA 94065

Fax: (650) 506-7228

Graphic Element	Description
	Use Case Model Diagrams summarize all the use cases in a particular domain, such as `Internal` `temporary` `LOBs`. Often these diagrams are too complex to contain within a single page. When that happens we have resorted to dividing the diagram into two parts. Please note that there is no sequence implied in this division.
	In some cases we have had to split a diagram simply because it is too long for the page. In such cases, we have included this marker.