3 Oracle Streams AQ: Programmatic Interfaces

This chapter describes the different language options and elements you must work with and issues to consider in preparing your Oracle Streams Advanced Queuing (AQ) application environment.

Note:

Java package oracle.AQ was deprecated in 10g Release 1 (10.1). Oracle recommends that you migrate existing Java AQ applications to Oracle JMS (or other Java APIs) and use Oracle JMS (or other Java APIs) to design your future Java AQ applications.

This chapter contains these topics:

Programmatic Interfaces for Accessing Oracle Streams AQ
Using PL/SQL to Access Oracle Streams AQ
Using OCI to Access Oracle Streams AQ
Using OCCI to Access Oracle Streams AQ
Using Visual Basic (OO4O) to Access Oracle Streams AQ
Using Oracle Java Message Service (OJMS) to Access Oracle Streams AQ
Using Oracle Streams AQ XML Servlet to Access Oracle Streams AQ
Comparing Oracle Streams AQ Programmatic Interfaces

3.1 Programmatic Interfaces for Accessing Oracle Streams AQ

Table 3-1 lists Oracle Streams AQ programmatic interfaces, functions supported in each interface, and syntax references.

Table 3-1 Oracle Streams AQ Programmatic Interfaces

Language	Precompiler or Interface Program	Functions Supported	Syntax References
PL/SQL	`DBMS_AQADM` and `DBMS_AQ` Packages	Administrative and operational	PL/SQL Packages and Types Reference
C	Oracle Call Interface (OCI)	Operational only	Oracle Call Interface Programmer's Guide
Visual Basic	Oracle Objects for OLE (OO4O)	Operational only	Online help available from Application Development submenu of Oracle installation.
Java (JMS)	`oracle.JMS` package using JDBC API	Administrative and operational	Oracle Streams Advanced Queuing Java API Reference
AQ XML servlet	Internet Data Access Presentation (IDAP)	Operational only	Chapter 6, "Internet Access to Oracle Streams AQ"

3.2 Using PL/SQL to Access Oracle Streams AQ

The PL/SQL packages DBMS_AQADM and DBMS_AQ support access to Oracle Streams AQ administrative and operational functions using the native Oracle Streams AQ interface. These functions include:

Create queue, queue table, nonpersistent queue, multiconsumer queue/topic, RAW message, or message with structured data
Get queue table, queue, or multiconsumer queue/topic
Alter queue table or queue/topic
Drop queue/topic
Start or stop queue/topic
Grant and revoke privileges
Add, remove, or alter subscriber
Add, remove, or alter an Oracle Streams AQ Internet agent
Grant or revoke privileges of database users to Oracle Streams AQ Internet agents
Enable, disable, or alter propagation schedule
Enqueue messages to single consumer queue (point-to-point model)
Publish messages to multiconsumer queue/topic (publish/subscribe model)
Subscribe for messages in multiconsumer queue
Browse messages in a queue
Receive messages from queue/topic
Register to receive messages asynchronously
Listen for messages on multiple queues/topics
Post messages to anonymous subscriptions
Bind or unbind agents in a Lightweight Directory Access Protocol (LDAP) server
Add or remove aliases to Oracle Streams AQ objects in a LDAP server

See Also:
PL/SQL Packages and Types Reference for detailed documentation of DBMS_AQADM and DBMS_AQ, including syntax, parameters, parameter types, return values, and examples

Available PL/SQL DBMS_AQADM and DBMS_AQ functions are listed in detail in Table 3-2 through Table 3-9.

3.3 Using OCI to Access Oracle Streams AQ

OCI provides an interface to Oracle Streams AQ functions using the native Oracle Streams AQ interface.

An OCI client can perform the following actions:

Enqueue messages
Dequeue messages
Listen for messages on sets of queues
Register to receive message notifications

In addition, OCI clients can receive asynchronous notifications for new messages in a queue using OCISubscriptionRegister.

See Also:

"OCI and Advanced Queuing" and "Publish-Subscribe Notification" in Oracle Call Interface Programmer's Guide for syntax details

Oracle Type Translator

For queues with user-defined payload types, the Oracle type translator must be used to generate the OCI/OCCI mapping for the Oracle type. The OCI client is responsible for freeing the memory of the Oracle Streams AQ descriptors and the message payload.

See Also:

Appendix C, "OCI Examples", which appears only in the HTML version of this guide, for OCI interface examples

3.4 Using OCCI to Access Oracle Streams AQ

C++ applications can use OCCI, which has a set of Oracle Streams AQ interfaces that enable messaging clients to access Oracle Streams AQ. OCCI AQ supports all the operational functions required to send/receive and publish/subscribe messages in a message-enabled database. Synchronous and asynchronous message consumption is available, based on a message selection rule.

See Also:

"Oracle Streams Advanced Queuing" in Oracle C++ Call Interface Programmer's Guide

3.5 Using Visual Basic (OO4O) to Access Oracle Streams AQ

Visual Basic (OO4O) supports access to Oracle Streams AQ operational functions using the native Oracle Streams AQ interface.

These functions include the following:

Create a connection, RAW message, or message with structured data
Enqueue messages to a single-consumer queue (point-to-point model)
Publish messages to a multiconsumer queue/topic (publish/subscribe model)
Browse messages in a queue
Receive messages from a queue/topic
Register to receive messages asynchronously

Note:

Because the database handles message propagation, OO4O does not differentiate between remote and local recipients. The same sequence of calls/steps are required to dequeue a message for local and remote recipients.

3.6 Using Oracle Java Message Service (OJMS) to Access Oracle Streams AQ

Java Message Service (JMS) is a messaging standard defined by Sun Microsystems, Oracle, IBM, and other vendors. JMS is a set of interfaces and associated semantics that define how a JMS client accesses the facilities of an enterprise messaging product.

Oracle Java Message Service (OJMS) provides a Java API for Oracle Streams AQ based on the JMS standard. OJMS supports the standard JMS interfaces and has extensions to support administrative operations and other features that are not a part of the standard.

Standard JMS features include:

Point-to-point model of communication using queues
Publish/subscribe model of communication using topics
ObjectMessage, StreamMessage, TextMessage, BytesMessage, and MapMessage message types
Asynchronous and synchronous delivery of messages
Message selection based on message header fields or properties

Oracle JMS extensions include:

Administrative API to create queue tables, queues and topics
Point-to-multipoint communication using recipient lists for topics
Message propagation between destinations, which allows the application to define remote subscribers
Support for transactional sessions, enabling JMS and SQL operations in one transaction
Message retention after messages have been dequeued
Message delay, allowing messages to be made visible after a certain delay
Exception handling, allowing messages to be moved to exception queues if they cannot be processed successfully
Support for AdtMessage

These are stored in the database as Oracle objects, so the payload of the message can be queried after it is enqueued. Subscriptions can be defined on the contents of these messages as opposed to just the message properties.
Topic browsing

This allows durable subscribers to browse through the messages in a publish/subscribe (topic) destination. It optionally allows these subscribers to purge the browsed messages, so they are no longer retained by Oracle Streams AQ for that subscriber.
See Also:
- Java Message Service Specification, version 1.1, March 18, 2002, Sun Microsystems, Inc.
- Part IV, "Using Oracle JMS and Oracle Streams AQ"
- Oracle Streams Advanced Queuing Java API Reference

3.6.1 Accessing Standard and Oracle JMS Applications

Standard JMS interfaces are in the javax.jms package. Oracle JMS interfaces are in the oracle.jms package. You must have EXECUTE privilege on the DBMS_AQIN and DBMS_AQJMS packages to use the Oracle JMS interfaces. You can also acquire these rights through the AQ_USER_ROLE or the AQ_ADMINSTRATOR_ROLE. You also need the appropriate system and queue or topic privileges to send or receive messages.

Because Oracle JMS uses Java Database Connectivity (JDBC) to connect to the database, its applications can run outside the database using the JDBC OCI driver or JDBC thin driver.

Using JDBC OCI Driver or JDBC Thin Driver

To use JMS with clients running outside the database, you must include the appropriate JDBC driver, Java Naming and Directory Interface (JNDI) jar files, and Oracle Streams AQ jar files in your CLASSPATH.

For JDK 1.3.x and higher, include the following in the CLASSPATH:

$ORACLE_HOME/jdbc/lib/classes12.jar
$ORACLE_HOME/jdbc/lib/orail8n.jar
$ORACLE_HOME/jdk/jre/lib/ext/jta.jar
$ORACLE_HOME/jdk/jre/lib/ext/jta.jar
$ORACLE_HOME/jlib/jndi.jar
$ORACLE_HOME/lib/xmlparserv2.jar
$ORACLE_HOME/rdbms/jlib/xdb.jar
$ORACLE_HOME/rdbms/jlib/aqapi13.jar 
$ORACLE_HOME/rdbms/jlib/jmscommon.jar

For JDK 1.2 include the following in the CLASSPATH:

$ORACLE_HOME/jdbc/lib/classes12.jar
$ORACLE_HOME/jdbc/lib/orail8n.jar
$ORACLE_HOME/jdk/jre/lib/ext/jta.jar
$ORACLE_HOME/jlib/jndi.jar
$ORACLE_HOME/lib/xmlparserv2.jar
$ORACLE_HOME/rdbms/jlib/xdb.jar
$ORACLE_HOME/rdbms/jlib/aqapi12.jar
$ORACLE_HOME/rdbms/jlib/jmscommon.jar

Using Oracle Server Driver in JServer

If your application is running inside the JServer, then you should be able to access the Oracle JMS classes that have been automatically loaded when the JServer was installed. If these classes are not available, then you must load jmscommon.jar followed by aqapi.jar using the $ORACLE_HOME/rdbms/admin/initjms SQL script.

3.7 Using Oracle Streams AQ XML Servlet to Access Oracle Streams AQ

You can use Oracle Streams AQ XML servlet to access Oracle Streams AQ over HTTP using Simple Object Access Protocol (SOAP) and an Oracle Streams AQ XML message format called Internet Data Access Presentation (IDAP).

Using the Oracle Streams AQ servlet, a client can perform the following actions:

Send messages to single-consumer queues
Publish messages to multiconsumer queues/topics
Receive messages from queues
Register to receive message notifications

See Also:

"Deploying the Oracle Streams AQ XML Servlet" for more information on the Oracle Streams AQ XML servlet

3.8 Comparing Oracle Streams AQ Programmatic Interfaces

Available functions for the Oracle Streams AQ programmatic interfaces are listed by use case in Table 3-2 through Table 3-9. Use cases are described in Chapter 8 through Chapter 10 and Chapter 12 through Chapter 15.

3.8.1 Oracle Streams AQ Administrative Interfaces

Table 3-2 lists the equivalent Oracle Streams AQ administrative functions for the PL/SQL and Java (JMS) programmatic interfaces.

Table 3-2 Comparison of Oracle Streams AQ Programmatic Interfaces: Administrative Interface

Use Case	PL/SQL	Java (JMS)
Create a connection factory	N/A	AQjmsFactory.getQueue ConnectionFactory AQjmsFactory.getTopic ConnectionFactory
Register a ConnectionFactory in an LDAP server	N/A	AQjmsFactory.register ConnectionFactory
Create a queue table	DBMS_AQADM.CREATE_QUEUE_TABLE	AQjmsSession.createQueueTable
Get a queue table	Use `schema`.`queue_table_name`	AQjmsSession.getQueueTable
Alter a queue table	DBMS_AQADM.ALTER_QUEUE_TABLE	AQQueueTable.alter
Drop a queue table	DBMS_AQADM.DROP_QUEUE_TABLE	AQQueueTable.drop
Create a queue	DBMS_AQADM.CREATE_QUEUE	AQjmsSession.createQueue
Get a queue	Use `schema.queue_name`	AQjmsSession.getQueue
Create a multiconsumer queue/topic in a queue table with multiple consumers enabled	DBMS_AQADM.CREATE_QUEUE	AQjmsSession.createTopic
Get a multiconsumer queue/topic	Use `schema.queue_name`	AQjmsSession.getTopic
Alter a queue/topic	DBMS_AQADM.ALTER_QUEUE	AQjmsDestination.alter
Start a queue/topic	DBMS_AQADM.START_QUEUE	AQjmsDestination.start
Stop a queue/topic	DBMS_AQADM.STOP_QUEUE	AQjmsDestination.stop
Drop a queue/topic	DBMS_AQADM.DROP_QUEUE	AQjmsDestination.drop
Grant system privileges	DBMS_AQADM.GRANT_SYSTEM_ PRIVILEGE	AQjmsSession.grantSystem Privilege
Revoke system privileges	DBMS_AQADM.REVOKE_SYSTEM_ PRIVILEGE	AQjmsSession.revokeSystem Privilege
Grant a queue/topic privilege	DBMS_AQADM.GRANT_QUEUE_ PRIVILEGE	AQjmsDestination.grantQueue Privilege AQjmsDestination.grantTopic Privilege
Revoke a queue/topic privilege	DBMS_AQADM.REVOKE_QUEUE_ PRIVILEGE	AQjmsDestination.revokeQueue Privilege AQjmsDestination.revokeTopic Privilege
Verify a queue type	DBMS_AQADM.VERIFY_QUEUE_TYPES	Not supported
Add a subscriber	DBMS_AQADM.ADD_SUBSCRIBER	See Table 3-6
Alter a subscriber	DBMS_AQADM.ALTER_SUBSCRIBER	See Table 3-6
Remove a subscriber	DBMS_AQADM.REMOVE_SUBSCRIBER	See Table 3-6
Schedule propagation	DBMS_AQADM.SCHEDULE_PROPAGATION	AQjmsDestination.schedule Propagation
Enable a propagation schedule	DBMS_AQADM.ENABLE_PROPAGATION_ SCHEDULE	AQjmsDestination.enable PropagationSchedule
Alter a propagation schedule	DBMS_AQADM.ALTER_PROPAGATION_ SCHEDULE	AQjmsDestination.alter PropagationSchedule
Disable a propagation schedule	DBMS_AQADM.DISABLE_PROPAGATION_ SCHEDULE	AQjmsDestination.disable PropagationSchedule
Unschedule a propagation	DBMS_AQADM.UNSCHEDULE_ PROPAGATION	AQjmsDestination.unschedule Propagation
Create an Oracle Streams AQ Internet Agent	DBMS_AQADM.CREATE_AQ_AGENT	Not supported
Alter an Oracle Streams AQ Internet Agent	DBMS_AQADM.ALTER_AQ_AGENT	Not supported
Drop an Oracle Streams AQ Internet Agent	DBMS_AQADM.DROP_AQ_AGENT	Not supported
Grant database user privileges to an Oracle Streams AQ Internet Agent	DBMS_AQADM.ENABLE_AQ_AGENT	Not supported
Revoke database user privileges from an Oracle Streams AQ Internet Agent	DBMS_AQADM.DISABLE_AQ_AGENT	Not supported
Add alias for queue, agent, ConnectionFactory in a LDAP server	DBMS_AQADM.ADD_ALIAS_TO_LDAP	Not supported
Delete alias for queue, agent, ConnectionFactory in a LDAP server	DBMS_AQADM.DEL_ALIAS_FROM_LDAP	Not supported

3.8.2 Oracle Streams AQ Operational Interfaces

Table 3-3 through Table 3-9 list equivalent Oracle Streams AQ operational functions for the programmatic interfaces PL/SQL, OCI, Oracle Streams AQ XML Servlet, and JMS, for various use cases.

Table 3-3 Comparison of Oracle Streams AQ Programmatic Interfaces: Operational Interface—Create Connection, Session, Message Use Cases

Use Case	PL/SQL	OCI	AQ XML Servlet	JMS
Create a connection	N/A	OCIServer Attach	Open an HTTP connection after authenticating with the Web server	AQjmsQueueConnectionFactory .createQueueConnection AQjmsTopicConnectionFactory .createTopicConnection
Create a session	N/A	OCISession Begin	An HTTP servlet session is automatically started with the first SOAP request	QueueConnection.createQueue Session TopicConnection.createTopic Session
Create a RAW message	Use SQL RAW type for message	Use OCIRaw for Message	Supply the hex representation of the message payload in the XML message. For example, `<raw>023f4523</raw>`	Not supported
Create a message with structured data	Use SQL Oracle object type for message	Use SQL Oracle object type for message	For Oracle object type queues that are not JMS queues (that is, they are not type `AQ$_JMS_*`), the XML specified in `<message payload>` must map to the SQL type of the payload for the queue table. For JMS queues, the XML specified in the `<message_payload>` must be one of the following: `<jms_text_message>`, `<jms_map_message>`, `<jms_bytes_message>`, `<jms_object_message>`	Session.createTextMessage Session.createObjectMessage Session.createMapMessage Session.createBytesMessage Session.createStreamMessage AQjmsSession.createAdtMessage
Create a message producer	N/A	N/A	N/A	QueueSession.createSender TopicSession.createPublisher

Table 3-4 Comparison of Oracle Streams AQ Programmatic Interfaces: Operational Interface—Enqueue Messages to a Single-Consumer Queue, Point-to-Point Model Use Cases

Use Case	PL/SQL	OCI	AQ XML Servlet	JMS
Enqueue a message to a single-consumer queue	DBMS_AQ.enqueue	OCIAQEnq	<AQXmlSend>	QueueSender.send
Enqueue a message to a queue and specify visibility options	DBMS_AQ.enqueue Specify visibility in ENQUEUE_OPTIONS	OCIAQEnq Specify `OCI_ATTR_VISIBILITY` in `OCIAQEnqOptions` OCIAQEnqOptions	<AQXmlSend> Specify `<visibility>` in <producer_options>	Not supported
Enqueue a message to a single-consumer queue and specify message properties priority and expiration	DBMS_AQ.enqueue Specify priority, expiration in MESSAGE_PROPERTIES	OCIAQEnq Specify `OCI_ATTR_PRIORITY`, `OCI_ATTR_EXPIRATION` in OCIAQMsgProperties	<AQXmlSend> Specify `<priority>`, `<expiration>` in <message_header>	Specify `priority` and `TimeToLive` during QueueSender.send or .setTimeToLive and MessageProducer. setPriority followed by QueueSender.send
Enqueue a message to a single-consumer queue and specify message properties correlationID, delay, and exception queue	DBMS_AQ.enqueue Specify correlation, delay, exception_queue in MESSAGE_PROPERTIES	OCIAQEnq Specify `OCI_ATTR_CORRELATION`, `OCI_ATTR_DELAY`, `OCI_ATTR_EXCEPTION_QUEUE` in OCIAQMsgProperties	<AQXmlSend> Specify `<correlation_id>`, `<delay>`, `<exception_queue>` in <message_header>	Message.setJMS CorrelationI Delay and exception queue specified as provider specific message properties JMS_OracleDelay JMS_OracleExcpQ followed by QueueSender.send
Enqueue a message to a single-consumer queue and specify user-defined message properties	Not supported Properties should be part of payload	Not supported Properties should be part of payload	<AQXmlSend> Specify `<name>` and `<int_value>`, `<string_value>`, `<long_value>,` and so on in <user_properties>	Message.setInt Property Message.setString Property Message.setBoolean Property and so forth, followed by QueueSender.send
Enqueue a message to a single-consumer queue and specify message transformation	DBMS_AQ.enqueue Specify transformation in ENQUEUE_OPTIONS	OCIAQEnq Specify `OCI_ATTR_TRANSFORMATION` in OCIAQEnqOptions	<AQXmlSend> Specify `<transformation>` in <producer_options>	AQjmsQueueSender. setTransformation followed by QueueSender.send

Table 3-5 Comparison of Oracle Streams AQ Programmatic Interfaces: Operational Interface—Publish Messages to a Multiconsumer Queue/Topic, Publish/Subscribe Model Use Cases

Use Case PL/SQL OCI AQ XML Servlet JMS

Publish a message to a multiconsumer queue/topic using default subscription list

Use Case	PL/SQL	OCI	AQ XML Servlet	JMS
Publish a message to a multiconsumer queue/topic using default subscription list	DBMS_AQ.enqueue Set `recipient_list` to `NULL` in MESSAGE_PROPERTIES	OCIAQEnq Set `OCI_ATTR_RECIPIENT_LIST` to `NULL` in OCIAQMsgProperties	<AQXmlPublish>	TopicPublisher. publish
Publish a message to a multiconsumer queue/topic using specific recipient list See footnote-1	DBMS_AQ.enqueue Specify recipient list in MESSAGE_PROPERTIES	OCIAQEnq Specify `OCI_ATTR_RECIPIENT_LIST` in OCIAQMsgProperties	<AQXmlPublish> Specify `<recipient_list>` in <message_header>	AQjmsTopic Publisher.publish Specify recipients as an array of `AQjmsAgent`
Publish a message to a multiconsumer queue/topic and specify message properties priority and expiration	DBMS_AQ.enqueue Specify priority, expiration in MESSAGE_PROPERTIES	OCIAQEnq Specify `OCI_ATTR_PRIORITY`, `OCI_ATTR_EXPIRATION` in OCIAQMsgProperties	<AQXmlPublish> Specify `<priority>`, `<expiration>` in <message_header>	Specify `priority` and `TimeToLive` during TopicPublisher. publish or MessageProducer. setTimeToLive and MessageProducer. setPriority followed by TopicPublisher. publish
Publish a message to a multiconsumer queue/topic and specify send options correlationID, delay, and exception queue	DBMS_AQ.enqueue Specify correlation, delay, `exception_queue` in MESSAGE_PROPERTIES	OCIAQEnq Specify `OCI_ATTR_CORRELATION`, `OCI_ATTR_DELAY`, `OCI_ATTR_EXCEPTION_QUEUE` in OCIAQMsgProperties	<AQXmlPublish> Specify `<correlation_id>`, `<delay>`, `<exception_queue>` in <message_header>	Message.setJMS CorrelationID Delay and exception queue specified as provider-specific message properties JMS_OracleDelay JMS_OracleExcpQ followed by TopicPublisher. publish
Publish a message to a topic and specify user-defined message properties	Not supported Properties should be part of payload	Not supported Properties should be part of payload	<AQXmlPublish> Specify `<name>` and `<int_value>`, `<string_value>`, `<long_value>,` and so on in <user_properties>	Message.setInt Property Message.setString Property Message.setBoolean Property and so forth, followed by TopicPublisher. publish
Publish a message to a topic and specify message transformation	DBMS_AQ.enqueue Specify transformation in ENQUEUE_OPTIONS	OCIAQEnq Specify `OCI_ATTR_TRANSFORMATION` in OCIAQEnqOptions	<AQXmlPublish> Specify `<transformation>` in <producer_options>	AQjmsTopic Publisher.set Transformation followed by TopicPublisher. publish

DBMS_AQ.enqueue

Set recipient_list to NULL in

MESSAGE_PROPERTIES

OCIAQEnq

Set OCI_ATTR_RECIPIENT_LIST to NULL in

OCIAQMsgProperties

<AQXmlPublish>

TopicPublisher.
publish

Publish a message to a multiconsumer queue/topic using specific recipient list

See footnote-1

DBMS_AQ.enqueue

Specify recipient list in

MESSAGE_PROPERTIES

OCIAQEnq

Specify OCI_ATTR_RECIPIENT_LIST in

OCIAQMsgProperties

<AQXmlPublish>

Specify <recipient_list> in

<message_header>

AQjmsTopic
Publisher.publish

Specify recipients as an array of AQjmsAgent

Publish a message to a multiconsumer queue/topic and specify message properties priority and expiration

DBMS_AQ.enqueue

Specify priority, expiration in

MESSAGE_PROPERTIES

OCIAQEnq

Specify OCI_ATTR_PRIORITY, OCI_ATTR_EXPIRATION in

OCIAQMsgProperties

<AQXmlPublish>

Specify <priority>, <expiration> in

<message_header>

Specify priority and TimeToLive during

TopicPublisher.
publish

MessageProducer.
setTimeToLive

and

MessageProducer.
setPriority

followed by

TopicPublisher.
publish

Publish a message to a multiconsumer queue/topic and specify send options correlationID, delay, and exception queue

DBMS_AQ.enqueue

Specify correlation, delay, exception_queue in

MESSAGE_PROPERTIES

OCIAQEnq

Specify OCI_ATTR_CORRELATION, OCI_ATTR_DELAY, OCI_ATTR_EXCEPTION_QUEUE in

OCIAQMsgProperties

<AQXmlPublish>

Specify <correlation_id>, <delay>, <exception_queue> in

<message_header>

Message.setJMS
CorrelationID

Delay and exception queue specified as provider-specific message properties

JMS_OracleDelay
JMS_OracleExcpQ

followed by

TopicPublisher.
publish

Publish a message to a topic and specify user-defined message properties

Not supported

Properties should be part of payload

Not supported

Properties should be part of payload

<AQXmlPublish>

Specify <name> and <int_value>, <string_value>, <long_value>, and so on in

<user_properties>

Message.setInt
Property

Message.setString
Property

Message.setBoolean
Property

and so forth, followed by

TopicPublisher.
publish

Publish a message to a topic and specify message transformation

DBMS_AQ.enqueue

Specify transformation in

ENQUEUE_OPTIONS

OCIAQEnq

Specify OCI_ATTR_TRANSFORMATION in

OCIAQEnqOptions

<AQXmlPublish>

Specify <transformation> in

<producer_options>

AQjmsTopic
Publisher.set
Transformation

followed by

TopicPublisher.
publish

Table 3-6 Comparison of Oracle Streams AQ Programmatic Interfaces: Operational Interface—Subscribing for Messages in a Multiconsumer Queue/Topic, Publish/Subscribe Model Use Cases

Use Case	PL/SQL	OCI	AQ XML Servlet	JMS
Add a subscriber	See administrative interfaces	Not supported	Not supported	TopicSession. createDurable Subscriber AQjmsSession. createDurable Subscriber
Alter a subscriber	See administrative interfaces	Not supported	Not supported	TopicSession. createDurable Subscriber AQjmsSession. createDurable Subscriber using the new selector
Remove a subscriber	See administrative interfaces	Not supported	Not supported	AQjmsSession. unsubscribe

Use Case

PL/SQL

OCI

AQ XML Servlet

JMS

Add a subscriber

See administrative interfaces

Not supported

TopicSession.
createDurable
Subscriber

AQjmsSession.
createDurable
Subscriber

Alter a subscriber

See administrative interfaces

Not supported

TopicSession.
createDurable
Subscriber

AQjmsSession.
createDurable
Subscriber

using the new selector

Remove a subscriber

See administrative interfaces

Not supported

AQjmsSession.
unsubscribe

Table 3-7 Comparison of Oracle Streams AQ Programmatic Interfaces: Operational Interface—Browse Messages in a Queue Use Cases

Use Case PL/SQL OCI AQ XML Servlet JMS

Browse messages in a queue/topic

Use Case	PL/SQL	OCI	AQ XML Servlet	JMS
Browse messages in a queue/topic	DBMS_AQ. dequeue Set `dequeue_mode` to `BROWSE` in DEQUEUE_OPTIONS	OCIAQDeq Set `OCI_ATTR_DEQ_MODE` to `BROWSE` in OCIAQDeqOptions	<AQXmlReceive> Specify `<dequeue_mode>` `BROWSE` in <consumer_options>	QueueSession.createBrowser QueueBrowser.getEnumeration Not supported on topics oracle.jms.AQjmsSession. createBrowser oracle.jms.TopicBrowser. getEnumeration
Browse messages in a queue/topic and lock messages while browsing	DBMS_AQ.dequeue Set `dequeue_mode` to `LOCKED` in DEQUEUE_OPTIONS	OCIAQDeq Set `OCI_ATTR_DEQ_MODE` to `LOCKED` in OCIAQDeqOptions	<AQXmlReceive> Specify `<dequeue_mode> LOCKED` in <consumer_options>	AQjmsSession.createBrowser set `locked` to `TRUE`. QueueBrowser.getEnumeration Not supported on topics oracle.jms.AQjmsSession. createBrowser oracle.jms.TopicBrowser. getEnumeration

DBMS_AQ.
dequeue

Set dequeue_mode to BROWSE in

DEQUEUE_OPTIONS

OCIAQDeq

Set OCI_ATTR_DEQ_MODE to BROWSE in

OCIAQDeqOptions

<AQXmlReceive>

Specify <dequeue_mode> BROWSE in

<consumer_options>

QueueSession.createBrowser

QueueBrowser.getEnumeration

Not supported on topics

oracle.jms.AQjmsSession.
createBrowser

oracle.jms.TopicBrowser.
getEnumeration

Browse messages in a queue/topic and lock messages while browsing

DBMS_AQ.dequeue

Set dequeue_mode to LOCKED in

DEQUEUE_OPTIONS

OCIAQDeq

Set OCI_ATTR_DEQ_MODE to LOCKED in

OCIAQDeqOptions

<AQXmlReceive>

Specify <dequeue_mode> LOCKED in

<consumer_options>

AQjmsSession.createBrowser

set locked to TRUE.

QueueBrowser.getEnumeration

Not supported on topics

oracle.jms.AQjmsSession.
createBrowser

oracle.jms.TopicBrowser.
getEnumeration

Table 3-8 Comparison of Oracle Streams AQ Programmatic Interfaces: Operational Interface—Receive Messages from a Queue/Topic Use Cases

Use Case PL/SQL OCI AQ XML Servlet JMS

Start a connection for receiving messages

N/A

Use Case	PL/SQL	OCI	AQ XML Servlet	JMS
Start a connection for receiving messages	N/A	N/A	N/A	Connection.start
Create a message consumer	N/A	N/A	N/A	QueueSession. createQueueReceiver TopicSession.create DurableSubscriber AQjmsSession.create TopicReceiver
Dequeue a message from a queue/topic and specify visibility	DBMS_AQ.dequeue Specify visibility in DEQUEUE_OPTIONS	OCIAQDeq Specify `OCI_ATTR_VISIBILITY` in OCIAQDeqOptions	<AQXmlReceive> Specify `<visibility>` in <consumer_options>	Not supported
Dequeue a message from a queue/topic and specify transformation	DBMS_AQ.dequeue Specify transformation in DEQUEUE_OPTIONS	OCIAQDeq Specify `OCI_ATTR_TRANSFORMATION` in OCIAQDeqOptions	<AQXmlReceive> Specify `<transformation>` in <consumer_options>	AQjmsQueueReceiver. setTransformation AQjmsTopicSubscriber. setTransformation AQjmsTopicReceiver. setTransformation
Dequeue a message from a queue/topic and specify navigation mode	DBMS_AQ.dequeue Specify navigation in DEQUEUE_OPTIONS	OCIAQDeq Specify `OCI_ATTR_NAVIGATION` in OCIAQDeqOptions	<AQXmlReceive> Specify `<navigation>` in <consumer_options>	AQjmsQueueReceiver. setNavigationMode AQjmsTopicSubscriber. setNavigationMode AQjmsTopicReceiver. setNavigationMode
Dequeue a message from a single-consumer queue	DBMS_AQ.dequeue Set `dequeue_mode` to `REMOVE` in DEQUEUE_OPTIONS	OCIAQDeq Set `OCI_ATTR_DEQ_MODE` to `REMOVE` in OCIAQDeqOptions	<AQXmlReceive>	QueueReceiver.receive or QueueReceiver.receive NoWait or AQjmsQueueReceiver. receiveNoData
Dequeue a message from a multiconsumer queue/topic using subscription name	DBMS_AQ.dequeue Set `dequeue_mode` to `REMOVE` and set `consumer_name` to subscription name in DEQUEUE_OPTIONS	OCIAQDeq Set `OCI_ATTR_DEQ_MODE` to `REMOVE` and set `OCI_ATTR_CONSUMER_NAME` to subscription name in OCIAQDeqOptions	<AQXmlReceive> Specify `<consumer_name>` in <consumer_options>	Create a durable TopicSubscriber on the topic using the subscription name, then TopicSubscriber. receive or TopicSubscriber. receiveNoWait or AQjmsTopicSubscriber. receiveNoData
Dequeue a message from a multiconsumer queue/topic using recipient name	DBMS_AQ.dequeue Set `dequeue_mode` to `REMOVE` and set `consumer_name` to recipient name in DEQUEUE_OPTIONS	OCIAQDeq Set `OCI_ATTR_DEQ_MODE` to `REMOVE` and set `OCI_ATTR_CONSUMER_NAME` to recipient name in OCIAQDeqOptions	<AQXmlReceive> Specify `<consumer_name>` in <consumer_options>	Create a `TopicReceiver` on the topic using the recipient name, then AQjmsSession.create TopicReceiver AQjmsTopicReceiver. receive or AQjmsTopicReceiver. receiveNoWait or AQjmsTopicReceiver. receiveNoData

Connection.start

Create a message consumer

N/A

QueueSession.
createQueueReceiver

TopicSession.create
DurableSubscriber

AQjmsSession.create
TopicReceiver

Dequeue a message from a queue/topic and specify visibility

DBMS_AQ.dequeue

Specify visibility in

DEQUEUE_OPTIONS

OCIAQDeq

Specify OCI_ATTR_VISIBILITY in

OCIAQDeqOptions

<AQXmlReceive>

Specify <visibility> in

<consumer_options>

Not supported

Dequeue a message from a queue/topic and specify transformation

DBMS_AQ.dequeue

Specify transformation in

DEQUEUE_OPTIONS

OCIAQDeq

Specify OCI_ATTR_TRANSFORMATION in

OCIAQDeqOptions

<AQXmlReceive>

Specify <transformation> in

<consumer_options>

AQjmsQueueReceiver.
setTransformation

AQjmsTopicSubscriber.
setTransformation

AQjmsTopicReceiver.
setTransformation

Dequeue a message from a queue/topic and specify navigation mode

DBMS_AQ.dequeue

Specify navigation in

DEQUEUE_OPTIONS

OCIAQDeq

Specify OCI_ATTR_NAVIGATION in

OCIAQDeqOptions

<AQXmlReceive>

Specify <navigation> in

<consumer_options>

AQjmsQueueReceiver.
setNavigationMode

AQjmsTopicSubscriber.
setNavigationMode

AQjmsTopicReceiver.
setNavigationMode

Dequeue a message from a single-consumer queue

DBMS_AQ.dequeue

Set dequeue_mode to REMOVE in

DEQUEUE_OPTIONS

OCIAQDeq

Set OCI_ATTR_DEQ_MODE to REMOVE in

OCIAQDeqOptions

<AQXmlReceive>

QueueReceiver.receive

QueueReceiver.receive
NoWait

AQjmsQueueReceiver.
receiveNoData

Dequeue a message from a multiconsumer queue/topic using subscription name

DBMS_AQ.dequeue

Set dequeue_mode to REMOVE and set consumer_name to subscription name in

DEQUEUE_OPTIONS

OCIAQDeq

Set OCI_ATTR_DEQ_MODE to REMOVE and set OCI_ATTR_CONSUMER_NAME to subscription name in

OCIAQDeqOptions

<AQXmlReceive>

Specify <consumer_name> in

<consumer_options>

Create a durable TopicSubscriber on the topic using the subscription name, then

TopicSubscriber.
receive

TopicSubscriber.
receiveNoWait

AQjmsTopicSubscriber.
receiveNoData

Dequeue a message from a multiconsumer queue/topic using recipient name

DBMS_AQ.dequeue

Set dequeue_mode to REMOVE and set consumer_name to recipient name in

DEQUEUE_OPTIONS

OCIAQDeq

Set OCI_ATTR_DEQ_MODE to REMOVE and set OCI_ATTR_CONSUMER_NAME to recipient name in

OCIAQDeqOptions

<AQXmlReceive>

Specify <consumer_name> in

<consumer_options>

Create a TopicReceiver on the topic using the recipient name, then

AQjmsSession.create
TopicReceiver

AQjmsTopicReceiver.
receive

AQjmsTopicReceiver.
receiveNoWait

AQjmsTopicReceiver.
receiveNoData

Table 3-9 Comparison of Oracle Streams AQ Programmatic Interfaces: Operational Interface—Register to Receive Messages Asynchronously from a Queue/Topic Use Cases

Use Case	PL/SQL	OCI	AQ XML Servlet	JMS
Receive messages asynchronously from a single-consumer queue	Define a PL/SQL callback procedure Register it using DBMS_AQ.REGISTER	OCISubscription Register Specify `queue_name` as subscription name OCISubscription Enable	<AQXmlRegister> Specify queue name in `<destination>` and notification mechanism in <notify_url>	Create a `QueueReceiver` on the queue, then QueueReceiver.set MessageListener
Receive messages asynchronously from a multiconsumer queue/topic	Define a PL/SQL callback procedure Register it using DBMS_AQ.REGISTER	OCISubscription Register Specify `queue:OCI_ATTR_CONSUMER_NAME` as subscription name OCISubscription Enable	<AQXmlRegister> Specify queue name in `<destination>`, consumer in `<consumer_name>` and notification mechanism in `<notify_url>`	Create a `TopicSubscriber` or `TopicReceiver` on the topic, then TopicSubscriber. setMessageListener
Listen for messages on multiple queues/topics	-	-	-	-
Listen for messages on one (many) single-consumer queues	DBMS_AQ.LISTEN Use `agent_name` as `NULL` for all agents in `agent_list`	OCIAQListen Use `agent_name` as `NULL` for all agents in `agent_list`	Not supported	Create multiple `QueueReceivers` on a `QueueSession`, then QueueSession.set MessageListener
Listen for messages on one (many) multiconsumer queues/Topics	DBMS_AQ.LISTEN Specify `agent_name` for all agents in `agent_list`	OCIAQListen Specify `agent_name` for all agents in `agent_list`	Not supported	Create multiple `TopicSubscribers` or `TopicReceivers` on a `TopicSession`, then TopicSession.set MessageListener