Skip Headers
Oracle® Streams Advanced Queuing User's Guide
11g Release 1 (11.1)

Part Number B28420-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

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:

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 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"

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:

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:

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:

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:

Oracle JMS extensions include:

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:

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

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

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

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