3 Oracle Streams Advanced Queuing: 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 Advanced Queuing
Using PL/SQL to Access Oracle Streams Advanced Queuing
Using OCI to Access Oracle Streams Advanced Queuing
Using OCCI to Access Oracle Streams Advanced Queuing
Using Visual Basic (OO4O) to Access Oracle Streams Advanced Queuing
Using Oracle Java Message Service (OJMS) to Access Oracle Streams Advanced Queuing
Using Oracle Streams Advanced Queuing XML Servlet to Access Oracle Streams Advanced Queuing
Comparing Oracle Streams Advanced Queuing Programmatic Interfaces

Programmatic Interfaces for Accessing Oracle Streams Advanced Queuing

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

Table 3-1 Oracle Streams Advanced Queuing Programmatic Interfaces

Language	Precompiler or Interface Program	Functions Supported	Syntax References
PL/SQL	`DBMS_AQADM` and `DBMS_AQ` Packages	Administrative and operational	Oracle Database 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"

Using PL/SQL to Access Oracle Streams Advanced Queuing

The PL/SQL packages DBMS_AQADM and DBMS_AQ support access to Oracle Streams Advanced Queuing administrative and operational functions using the native Oracle Streams Advanced Queuing 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 Advanced Queuing Internet agent
Grant or revoke privileges of database users to Oracle Streams Advanced Queuing 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 Advanced Queuing objects in a LDAP server

See Also:
Oracle Database 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.

Using OCI to Access Oracle Streams Advanced Queuing

OCI provides an interface to Oracle Streams Advanced Queuing functions using the native Oracle Streams Advanced Queuing 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.

Using OCCI to Access Oracle Streams Advanced Queuing

C++ applications can use OCCI, which has a set of Oracle Streams Advanced Queuing interfaces that enable messaging clients to access Oracle Streams Advanced Queuing. 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.

Using Visual Basic (OO4O) to Access Oracle Streams Advanced Queuing

Visual Basic (OO4O) supports access to Oracle Streams Advanced Queuing operational functions using the native Oracle Streams Advanced Queuing 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.

Using Oracle Java Message Service (OJMS) to Access Oracle Streams Advanced Queuing

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 Advanced Queuing 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 Advanced Queuing for that subscriber.
See Also:
- Java Message Service Specification, version 1.1, March 18, 2002, Sun Microsystems, Inc.
- Oracle Streams Advanced Queuing Java API Reference

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 Advanced Queuing jar files in your CLASSPATH.

Note that the Oracle Database does not support JDK 1.2, JDK 1.3, JDK 1.4, and all classes12*.* files. You need to use the ojdbc5.jar and ojbc6.jar files with JDK 5.n and JDK 6.n, respectively. The following jar and zip files should be in the CLASSPATH based on the release of JDK you are using.

For JDK 1.5.x, the CLASSPATH must contain:

ORACLE_HOME/jdbc/lib/ojdbc5.jar

For JDK 1.6.x, the CLASSPATH must contain:

ORACLE_HOME/jdbc/lib/ojdbc6.jar

The following files are used for either JDK version:

ORACLE_HOME/lib/jta.jar
ORACLE_HOME/xdk/lib/xmlparserv2.jar
ORACLE_HOME/rdbms/jlib/xdb.jar
ORACLE_HOME/jlib/aqapi.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.

Using Oracle Streams Advanced Queuing XML Servlet to Access Oracle Streams Advanced Queuing

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

Using the Oracle Streams Advanced Queuing 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

Comparing Oracle Streams Advanced Queuing Programmatic Interfaces

Available functions for the Oracle Streams Advanced Queuing 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.

Oracle Streams Advanced Queuing Administrative Interfaces

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

Table 3-2 Comparison of Oracle Streams Advanced Queuing 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 Advanced Queuing Internet Agent	DBMS_AQADM.CREATE_AQ_AGENT	Not supported
Alter an Oracle Streams Advanced Queuing Internet Agent	DBMS_AQADM.ALTER_AQ_AGENT	Not supported
Drop an Oracle Streams Advanced Queuing Internet Agent	DBMS_AQADM.DROP_AQ_AGENT	Not supported
Grant database user privileges to an Oracle Streams Advanced Queuing Internet Agent	DBMS_AQADM.ENABLE_AQ_AGENT	Not supported
Revoke database user privileges from an Oracle Streams Advanced Queuing 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

Oracle Streams Advanced Queuing Operational Interfaces

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

Table 3-3 Comparison of Oracle Streams Advanced Queuing 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 Advanced Queuing 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

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

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

.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 Advanced Queuing 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

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

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

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 Advanced Queuing 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 Advanced Queuing Programmatic Interfaces: Operational Interface—Browse Messages in a Queue Use Cases

Use Case PL/SQL OCI AQ XML Servlet JMS

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

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

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

Use Case PL/SQL OCI AQ XML Servlet JMS

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

Start a connection for receiving messages

N/A

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 Advanced Queuing 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