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 for Publish/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
Java API
Separate storage of history management information
For more information about Oracle AQ features, see:

Chapter 8, "A Sample Application Using AQ"

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 the following chapters and appendices:

Chapter 1, "What is Oracle Advanced Queuing?"

This chapter describes 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 design and a clear idea of the intended direction.

Chapter 2, "Basic Components"

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

Chapter 3, "AQ Programmatic Environments"

This chapter describes the elements you need to work with and issues you will want to take into consideration in preparing your AQ application environment.

Chapter 4, "Managing AQ"

This chapter discusses issues related to managing Advanced Queuing such as migrating queue tables (import-export), security, enterprise manager support, protocols, sample dba actions as preparation for working with AQ, and current restrictions.

Chapter 5, "Advanced Topics"

This chapter discusses advanced topics.

Chapter 6, "Frequently Asked Questions"

Frequently asked questions are answered here.

Chapter 7, "Modeling and Design"

This chapter covers the fundamentals of Advanced Queueing modeling and design.

Chapter 8, "A Sample Application Using AQ"

This chapter considers the features of Oracle Advanced Queuing in the context of a sample application.

Chapter 9, "Administrative Interface"

This chapter describes the administrative interface to Oracle Advanced Queuing.

Chapter 10, "Administrative Interface: Views"

In this chapter we describe the administrative interface with respect to views in terms of a hybrid of use cases and state diagrams.

Chapter 11, "Operational Interface: Basic Operations"

In this chapter we describe the operational interface to Oracle Advanced Queuing in terms of use cases.

Chapter 12, "Creating Applications Using JMS"

In this chapter we consider the features of the Oracle JMS interface to AQ in the context of a sample application based on that scenario.

Chapter 13, "JMS Administrative Interface: Basic Operations"

In this chapter we describe the administrative interface to Oracle Advanced Queuing in terms of use cases.

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

In this chapter we describe point to point operations.

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

In this chapter we describe publish-subscribe operations.

Chapter 16, "JMS Operational Interface: Basic Operations (Shared Interfaces)"

In this chapter we describe shared interface operations.

Appendix A, "Oracle Advanced Queuing by Example"

This appendix provides examples of operations using different programatic environments

Appendix B, "Oracle JMS Interfaces, Classes and Exceptions"

This appendix provideds a list of Oracle JMS interfaces, classes & exceptions.

Appendix C, "Scripts for Implementing 'BooksOnLine'"

This appendix contains scripts used in the "BooksOnLine" example.

Appendix D, "JMS Error Messages"

A list of error messages is provided here to aid you in troubleshooting problems.

How to Interpret the Diagrams

This manual makes use of the Universal Modeling Language (UML) as a way of explaining technology. A full presentation of the UML is beyond the scope of this documentation set, however we do provide a brief 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.
In the online versions of these diagrams, these are clickable areas that link to the related operation.

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. In the online versions of these diagrams, these are clickable areas that link to the related operation.
	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 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.

Links in Online Versions of this Document

The online (HTML and PDF) versions of these diagrams include active areas that either have blue perimeters or look like buttons. You can use these links to traverse the following relationships:

To move between Use Case Model Diagrams which encompass all the possible use cases for a given interface, and the Use Case Diagrams which detail the individual cases.
To traverse different branches of a Use Case which can be implemented in more that one way. The branching Use Case Diagrams have titles such as "Three Ways to..." and buttons marked by "a", "b", "c"...
To access the Sub-Usecases that are entailed as part of a more primary Use Case while retaining context.
To view details of the classes that underlie Use Cases accessible in Java.
To view the class structure in which specific Java classes are located (see Appendix B, "Oracle JMS Interfaces, Classes and Exceptions").

The following examples illustrate these relationships.

Graphic Element Description

Use Case Model Diagrams, which summarize all the use cases in a particular domain, have active areas which link to the individual Use Cases.

Buttons in the individual Use Case Diagrams lead back to the Use Case Model Diagram

Graphic Element

Description
This Use Case Diagram combines a number of the elements:

JMS Administrative Interface - this button leads back to the Use Case Model Diagram

AQjmsFactory - this button leads to the Class Diagram in which contains the method by which the this use case is implemented

a. Create a Topic Connection Factory with JDBC URL is the "a" branch of the use case

b. Create a Topic Connection Factory with JDBC Connection Parameters is the "b" branch of the use case

Graphic Element

Description
This Class Diagram has links to the individual class diagrams which form its components. This reduced view of the classes shows

whether classes, interfaces, and exceptions are entailed in the interrelationship by means of the <<>>, stereotype, such as <<interface>>

the name of the package in which the class is found, such as oracle.jms

the name of the class, such as AQjmsConnection

Graphic Element

Description
The expanded view of the Class Diagram

links to the Class Structure diagram via the button Oracle JMS Classes which describes its interrelationships. Although many classes share this button, each class is linked to the part of the structure specific to it.

contains the names of the attributes (fields) if these exist and are exposed (there are none in this case)

the name of the methods that comprise the public interface to the class

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.

Graphic Element	Description
	Use Case Model Diagrams, which summarize all the use cases in a particular domain, have active areas which link to the individual Use Cases.
	Buttons in the individual Use Case Diagrams lead back to the Use Case Model Diagram