1. Advanced Queuing User's Guide
  2. Oracle Database Advanced Queuing: Programmatic Interfaces

3 Oracle Database Advanced Queuing: Programmatic Interfaces

These topics describe the various language options and elements you must work with and issues to consider in preparing your Oracle Database 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.

Topics:

3.1 Programmatic Interfaces for Accessing Oracle Database Advanced Queuing

The table lists Oracle Database Advanced Queuing programmatic interfaces, functions supported in each interface, and syntax references.

Table 3-1 Oracle Database 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

Java (JMS)

oracle.JMS package using JDBC API

Administrative and operational

Oracle Database Advanced Queuing Java API Reference

AQ XML servlet

Internet Data Access Presentation (IDAP)

Operational only

Oracle XML DB Developer's Guide

3.2 Using PL/SQL to Access Oracle Database Advanced Queuing

The PL/SQL packages DBMS_AQADM and DBMS_AQ support access to Oracle Database Advanced Queuing administrative and operational functions using the native Oracle Database Advanced Queuing interface.

These functions include:

  • Create queue, queue table, nonpersistent queue, sharded 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 Database Advanced Queuing Internet agent

  • Grant or revoke privileges of database users to Oracle Database 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 Database Advanced Queuing objects in a LDAP server

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

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

3.3 Using OCI and the Thin JDBC Driver to Access Oracle Database Advanced Queuing

An Oracle Call Interface (OCI) provides an interface to Oracle Database Advanced Queuing functions using the native Oracle Database 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. Sharded queues do not support OCI clients.

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 Database Advanced Queuing descriptors and the message payload.

See Also:

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

3.3.1 Comparing Oracle Database Advanced Queuing Programmatic Interfaces

These topics list and compare the Oracle Database Advanced Queuing Administrative Interfaces and the Oracle Database Advanced Queuing Operational Interfaces.

Available functions for the Oracle Database Advanced Queuing programmatic interfaces are listed by use case in Table 3-2 through Table 3-9. Use cases are described in Oracle Database Advanced Queuing Administrative Interface through Oracle Database Advanced Queuing Operations Using PL/SQL and Oracle Java Message Service Basic Operations through Oracle Java Message Service Shared Interfaces.

3.3.1.1 Oracle Database Advanced Queuing Administrative Interfaces

The table lists the equivalent Oracle Database Advanced Queuing administrative functions for the PL/SQL and Java (JMS) programmatic interfaces.

Table 3-2 Comparison of Oracle Database 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

Create a sharded queue

 DBMS_AQADM.CREATE_SHARDED_QUEUE AQjmsDestination.createJMSShardedQueue

Drop a sharded queue

 DBMS_AQADM.DROP_SHARDED_QUEUE AQjmsDestination.dropJMSShardedQueue

Alter a sharded queue

 DBMS_AQADM.ALTER_SHARDED_QUEUE

None. Use PL/SQL API.

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 Database Advanced Queuing Internet Agent

 
DBMS_AQADM.CREATE_AQ_AGENT

Not supported

Alter an Oracle Database Advanced Queuing Internet Agent

 
DBMS_AQADM.ALTER_AQ_AGENT

Not supported

Drop an Oracle Database Advanced Queuing Internet Agent

 
DBMS_AQADM.DROP_AQ_AGENT

Not supported

Grant database user privileges to an Oracle Database Advanced Queuing Internet Agent

 
DBMS_AQADM.ENABLE_AQ_AGENT

Not supported

Revoke database user privileges from an Oracle Database 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
3.3.1.2 Oracle Database Advanced Queuing Operational Interfaces

These tables list equivalent Oracle Database Advanced Queuing operational functions for the programmatic interfaces PL/SQL, OCI, Oracle Database Advanced Queuing XML Servlet, and JMS, for various use cases.

Table 3-3 Comparison of Oracle Database 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 Database 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

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

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

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

3.4 Using OCCI to Access Oracle Database Advanced Queuing

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

See Also:

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

3.5 Using Oracle Java Message Service (Oracle JMS) to Access Oracle Database 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 (Oracle JMS) provides a Java API for Oracle Database Advanced Queuing based on the JMS standard.

Oracle Java Message Service (Oracle JMS) supports the standard JMS interfaces and has extensions to support administrative operations and other features that are not a part of the standard.

Standard Java Message Service(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 Database Advanced Queuing for that subscriber.

    See Also:

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

Note that the Oracle Database does not support JDK 1.2, JDK 1.3, JDK 1.4, JDK5.n and all classes12*.* files. You need to use the ojdbc6.jar and ojbc7.jar files with JDK 6.n and JDK 7.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/ojdbc6.jar

For JDK 1.6.x, the CLASSPATH must contain: 

ORACLE_HOME/jdbc/lib/ojdbc7.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/rdbms/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.

3.6 Using Oracle Database Advanced Queuing XML Servlet to Access Oracle Database Advanced Queuing

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

Using the Oracle Database 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