3
AQ Programmatic Environments

This chapter describes the elements you need to work with and issues to consider in preparing your AQ application environment. The following topics are discussed:

Programmatic Environments for Accessing AQ

The following programmatic environments are used to access the Advanced Queuing functions of Oracle:

Native AQ Interface
- PL/SQL (DBMS_AQADM and DBMS_AQ packages): supports administrative and operational functions
- C (OCI): supports operational functions
- Visual Basic (OO4O): supports operational functions
- Java (oracle.AQ package using JDBC): supports administrative and operational functions
JMS Interface to AQ
- Java (javax.jms and oracle.jms packages using JDBC): supports the standard JMS administrative and operational functions and Oracle JMS extensions
XML Interface to AQ
- The AQ XML servlet supports operational functions using an XML message format.

Refer to Table 3-1, " AQ Programmatic Environments" for the AQ programmatic environments and syntax references.

Table 3-1 AQ Programmatic Environments

Language	Precompiler or Interface Program	Syntax Reference	In This Chapter See...
PL/SQL	`DBMS_AQADM` and `DBMS_AQ` Package	Oracle9i Supplied PL/SQL Packages and Types Reference	"Using PL/SQL to Access AQ"
C	Oracle Call Interface (OCI)	Oracle Call Interface Programmer's Guide	"Using OCI to Access AQ"
Visual Basic	Oracle Objects For OLE (OO4O)	Oracle Objects for OLE (OO4O) is a Windows-based product included with Oracle Client for Windows NT. There are no manuals for this product, only online help. Online help is available through the Application Development submenu of the Oracle installation.	"Using AQ Java (oracle.AQ) Classes to Access AQ"
Java (AQ)	`oracle.AQ` package using JDBC Application Programmatic Interface (API)	Oracle9i Supplied Java Packages Reference	"Using AQ Java (oracle.AQ) Classes to Access AQ"
Java (JMS)	`oracle.JMS` package using JDBC Application Programmatic Interface (API)	Oracle9i Supplied Java Packages Reference	"Using AQ Java (oracle.AQ) Classes to Access AQ" and "Using Oracle Java Message Service to Access AQ"
AQ XML Servlet	`oracle.AQ.xml.AQxmlServlet` using HTTP or SMTP	Oracle9i Supplied Java Packages Reference	"Using the AQ XML Servlet to Access AQ"

Using PL/SQL to Access AQ

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

Create: queue, queue table, nonpersistent queue, multiconsumer queue/topic, RAW message, message with structured data
Get: queue table, queue, multiconsumer queue/topic
Alter: queue table, queue/topic
Drop: queue/topic
Start or stop: queue/topic
Grant and revoke privileges
Add, remove, alter subscriber
Add, remove, alter AQ Internet agents
Grant or revoke privileges of database users to AQ Internet agents
Enable, disable, and alter propagation schedule
Enqueue messages to single consumer queue (point-to-point model)
Publish messages to multiconsumer queue/topic (publish-subscribe model)
Subscribing 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 LDAP server
Add or remove aliases to AQ objects in a LDAP server

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

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 AQ

Oracle Call Interface (OCI) provides an interface to Oracle Advanced Queuing functions using the native 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:

Oracle Call Interface Programmer's Guide: "OCI and Advanced Queuing" and "Publish-Subscribe Notification" sections, for syntax details.

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

Examples

LNOCI Interface

See Appendix A, "Oracle Advanced Queuing by Example" under "Enqueuing and Dequeuing Of Messages" for OCI Advanced Queuing interface examples.

Managing OCI Descriptor Memory

See Appendix A, "Oracle Advanced Queuing by Example" under "AQ and Memory Usage" for examples illustrating memory management of OCI descriptors.

Using Visual Basic (OO4O) to Access AQ

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

These functions include the following:

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

For More Information

For more information about OO4O, refer to the following Web site:

http://otn.oracle.com

Select Products > Internet Tools > Programmer. Scroll down to: Oracle Objects for OLE. At the bottom of the page is a list of useful articles for using the interfaces.
http://www.oracle.com/products

Search for articles on OO4O or Oracle Objects for OLE.

Using AQ Java (oracle.AQ) Classes to Access AQ

The Java AQ API supports both the administrative and operational features of Advanced Queueing. In developing Java programs for messaging applications, you use JDBC to open a connection to the database and to oracle.AQ, the Java AQ API for message queuing.

Oracle9i Supplied Java Packages Reference describes the common interfaces and classes based on current PL/SQL interfaces.

Common interfaces are prefixed with "AQ". These interfaces will have different implementations in Oracle8i and Oracle Lite.
In this document we describe the common interfaces and their corresponding Oracle8i implementations, that are in turn prefixed with "AQOracle".

Accessing Java AQ Classes

The Java AQ classes are located in $ORACLE_HOME/rdbms/jlib/aqapi*.jar. In release 9.2, Oracle JMS conforms to Sun Microsystems' JMS 1.0.2b standard. These classes can be used with any OracleJDBC driver, version 8i and higher.

Using OCI8 or Thin JDBC Driver
- For JDK 1.3, include the following in the CLASSPATH:
  - $ORACLE_HOME/jdbc/lib/classes12.zip
  - $ORACLE_HOME/jlib/jndi.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.zip
  - $ORACLE_HOME/jlib/jndi.jar
  - $ORACLE_HOME/rdbms/jlib/aqapi12.jar
  - $ORACLE_HOME/rdbms/jlib/jmscommon.jar
- For JDK 1.1, include the following in the CLASSPATH:
  - $ORACLE_HOME/jdbc/lib/classes111.zip
  - $ORACLE_HOME/jlib/jndi.jar
  - $ORACLE_HOME/rdbms/jlib/aqapi11.jar
  - $ORACLE_HOME/rdbms/jlib/jmscommon.jar
Using Oracle Server Driver in JServer: If the application is using the Oracle Server driver and accessing the Java AQ API from Java stored procedures, the Java files are generally automatically preloaded in a Java-enabled database. If the Java files are not loaded, you must first load the jmscommon.jar and aqapi.jar files into the database using the loadjava utility.

Advanced Queuing Examples

Appendix A, "Oracle Advanced Queuing by Example" contains the following examples:

Enqueue and Dequeue of Object Type Messages (CustomDatum interface) Using Java
Enqueue and Dequeue of Object Type Messages (using SQLData interface) Using Java
Create a Queue Table and Queue Using Java
Create a Queue and Start Enqueue/Dequeue Using Java
Create a Multiconsumer Queue and Add Subscribers Using Java
Enqueue of RAW Messages using Java
Dequeue of Messages Using Java
Dequeue of Messages in Browse Mode Using Java
Enqueue of Messages with Priority Using Java
Enqueuing and Dequeuing Object Type Messages That Contain LOB Attributes Using Java

Managing the Java AQ API

The various implementations of the Java AQ API are managed with AQDriverManager. Both OLite and Oracle9i will have an AQDriver that is registered with the AQDriverManager. The driver manager is used to create an AQSession that can be used to perform messaging tasks.

The Oracle8i AQ driver is registered using the Class.forName ("oracle.AQ.AQOracleDriver") command.

When the AQDriverManager.createAQSession() method is invoked, it calls the appropriate AQDriver (among the registered drivers) depending on the parameter passed to the createAQSession() call.

The Oracle9i AQDriver expects a valid JDBC connection to be passed in as a parameter to create an AQSession. Users must have the execute privilege on the DBMS_AQIN package to use the AQ Java interfaces. Users can also acquire these rights through the AQ_USER_ROLE or the AQ_ADMINSTRATOR_ROLE. Users will also need the appropriate system and queue privileges for 8.1-style queue tables.

Using Oracle Java Message Service to Access AQ

Java Message Service (JMS): 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 Java Message Service provides a Java API for Oracle Advanced Queuing based on the JMS standard. Oracle JMS supports the standard JMS interfaces and has extensions to support the AQ administrative operations and other AQ features that are not a part of the standard.

Standard JMS Features

Standard JMS features include:

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

Oracle JMS Extensions

Oracle JMS extensions include the following:

Administrative API to create queue tables, queues and topics
Point-to-multipoint communication using recipient lists for topics
Message propagation between destinations. Allows the application to define remote subscribers.
Supports transacted sessions that enable you to perform JMS as well as SQL operations in one atomic transaction.
Message retention after messages have been dequeued
Message delay - messages can be made visible after a certain delay
Exception handling - messages are moved to exception queues if they cannot be processed successfully
In addition to the standard JMS message types, Oracle supports AdtMessages. These are stored in the database as Oracle objects and hence 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 - allows durable subscribers to browse through the messages in a publish-subscribe (topic) destination, and optionally allows these subscribers to purge the browsed messages (so that they are no longer retained by AQ for that subscriber).

Accessing Standard and Oracle JMS

Oracle JMS uses JDBC to connect to the database, hence it applications can run as follows:

Outside the database using the OCI8 or thin JDBC driver
Inside Oracle8i JServer using the Oracle Server driver

The standard JMS interfaces are in the javax.jms package.

The Oracle JMS interfaces are in the oracle.jms package.

Using OCI8 or Thin JDBC Driver: To use JMS with clients running outside the database, you must include the appropriate JDBC driver, JNDI jar files and the following AQ jar files in your CLASSPATH:
- For JDK 1.1 include the following:
  
  $ORACLE_HOME/rdbms/jlib/jmscommon.jar
  
  $ORACLE_HOME/rdbms/jlib/aqapi11.jar
  
  $ORACLE_HOME/jlib/jndi.jar
  
  $ORACLE_HOME/jdbc/lib/classes111.jar
- For JDK 1.2 include the following:
  
  $ORACLE_HOME/rdbms/jlib/jmscommon.jar
  
  $ORACLE_HOME/rdbms/jlib/aqapi.jar
  
  $ORACLE_HOME/jlib/jndi.jar
  
  $ORACLE_HOME/jdbc/lib/classes12.jar
Using Oracle Server Driver in JServer: If your application is running inside the JServer, 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, you may have to load jmscommon.jar followed by aqapi.jar using the $ORACLE_HOME/rdbms/admin/initjms SQL script.

Privileges

Users must have EXECUTE privilege on the DBMS_AQIN and DBMS_AQJMS packages to use the Oracle JMS interfaces. Users can also acquire these rights through the AQ_USER_ROLE or the AQ_ADMINSTRATOR_ROLE.

Users will also need the appropriate system and queue or topic privileges to send or receive messages.

For More Information

Oracle JMS interfaces are described in detail in the Oracle9i Supplied Java Packages Reference.

Using the AQ XML Servlet to Access AQ

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

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

The servlet can be created by defining a Java class that extends the oracle.AQ.xml.AQxmlServlet or oracle.AQ.xml.AQxmlServlet20 class. These classes in turn extend the javax.servlet.http.HttpServlet class.

The servlet can be deployed on any Web server or ServletRunner that implements Javasoft's Servlet 2.0 or Servlet 2.2 interfaces.

To deploy the AQ Servlet with a Web server that implements Javasoft's Servlet2.0 interfaces, you must define a class that extends the oracle.AQ.xml.AQxmlServle20 class.
To deploy the AQ Servlet with a Web server that implements Javasoft's Servlet2.2 interfaces, you must define a class that extends the oracle.AQ.xml.AQxmlServlet class.

The servlet can be compiled using JDK 1.1.x or JDK 1.2.x libraries.

For JDK 1.1.x the CLASSPATH must contain:

$ORACLE_HOME/jdbc/lib/classes111.jar 
$ORACLE_HOME/jlib/jta.jar
$ORACLE_HOME/jdbc/lib/nls_charset11.jar
$ORACLE_HOME/jlib/jndi.jar
$ORACLE_HOME/lib/lclasses11.zip
$ORACLE_HOME/lib/xmlparserv2.jar
$ORACLE_HOME/lib/xschema.jar
$ORACLE HOME/rdbms/jlib/aqapi11.jar
$ORACLE_HOME/rdbms/jlib/jmscommon.jar
$ORACLE_HOME/rdbms/jlib/aqxml.jar
$ORACLE_HOME/rdbms/jlib/xsu111.jar
$ORACLE_HOME/lib/servlet.jar

For JDK 1.2.x the CLASSPATH must contain:

$ORACLE_HOME/jdbc/lib/classes12.jar
$ORACLE_HOME/jlib/jta.jar
$ORACLE_HOME/jdbc/lib/nls_charset12.jar
$ORACLE_HOME/jlib/jndi.jar
$ORACLE_HOME/lib/lclasses12.zip
$ORACLE_HOME/lib/xmlparserv2.jar
$ORACLE_HOME/lib/xschema.jar
$ORACLE_HOME/rdbms/jlib/aqapi.jar
$ORACLE_HOME/rdbms/jlib/jmscommon.jar
$ORACLE_HOME/rdbms/jlib/aqxml.jar
$ORACLE_HOME/rdbms/jlib/xsu12.jar
$ORACLE_HOME/lib/servlet.jar

Since the servlet uses JDBC OCI drivers to connect to the Oracle9i database server, the 9i Oracle client libraries must be installed on the machine that hosts the servlet. The LD_LIBRARY_PATH must contain $ORACLE_HOME/lib.

Refer to Chapter 17, "Internet Access to Advanced Queuing" for more information on Internet access to Advanced Queuing.

Comparing AQ Programmatic Environments

Available functions for the AQ programmatic environments are listed by use case in Table 3-2 through Table 3-9. Use cases are described in Chapter 9 through Chapter 11 andChapter 13 through Chapter 16. Refer to Chapter E, "Unified Modeling Language Diagrams" for an explanation of use case diagrams.

AQ Administrative Interfaces

Table 3-2 lists the equivalent AQ administrative functions for three programmatic environments, PL/SQL, Java (native AQ), and Java (JMS).

Table 3-2 Comparison of AQ Programmatic Environments: Administrative Interface

Use Case	PL/SQL	Java (Native)	Java (JMS)
Create a Connection Factory	N/A	N/A	AQjmsFactory.getQueueConnectionFactory AQjmsFactory.getTopicConnectionFactory
Register a Connection Factory in a LDAP server	N/A	N/A	AQjmsFactory.registerConnectionFactory
Create a Queue Table	DBMS_AQADM.create_queue_table	Create AQQueueTableProperty, then AQSession.createQueueTable	AQjmsSession.createQueueTable
Get a Queue Table	Use <schema>.<queue_table_name>	AQSession.getQueueTable	AQjmsSession.getQueueTable
Alter a Queue Table	DBMS_AQADM.alter_queue_table	AQQueueTable.alter	AQQueueTable.alter
Drop a Queue Table	DBMS_AQADM.drop_queue_table	AQQueueTable.drop	AQQueueTable.drop
Create a Queue	DBMS_AQADM.create_queue	AQSession.createQueue	AQjmsSession.createQueue
Get a Queue	Use <schema>.<queue_name>	AQSession.getQueue	AQjmsSession.getQueue
Create a Nonpersistent Queue	DBMS_AQADM.create_np_queue	Not supported	Not supported
Create a Multiconsumer Queue/Topic	DBMS_AQADM.create_queue in a queue table with multiple consumers enabled	AQSession.createQueue in a queue table with multiple consumers enabled	AQjmsSession.createTopic in a queue table with multiple consumers enabled
Get a Multiconsumer Queue/Topic	Use <schema>.<queue_name>	AQSession.getQueue	AQjmsSession.getTopic
Alter a Queue/Topic	DBMS_AQADM.alter_queue	AQQueue.alterQueue	AQjmsDestination.alter
Start a Queue/Topic	DBMS_AQADM.start_queue	AQQueue.start AQQueue.startEnqueue AQQueue.startDequeue	AQjmsDestination.start
Stop a Queue/Topic	DBMS_AQADM.stop_queue	AQQueue.stop AQQueue.stopEnqueue AQQueue.stopDequeue	AQjmsDestination.stop
Drop a Queue/Topic	DBMS_AQADM.drop_queue	AQQueue.drop AQQueueTable.dropQueue	AQjmsDestination.drop
Grant System Privileges	DBMS_AQADM.grant_system_privilege	Not supported	AQjmsSession.grantSystemPrivilege
Revoke System Privileges	DBMS_AQADM.revoke_system_privilege	Not supported	AQjmsSession.revokeSystemPrivilege
Grant a Queue/Topic Privilege	DBMS_AQADM.grant_queue_privilege	AQQueue.grantQueuePrivilege	AQjmsDestination.grantQueuePrivilege AQjmsDestination.grantTopicPrivilege
Revoke a Queue/Topic Privilege	DBMS_AQADM.revoke_queue_privilege	AQQueue.revokeQueuePrivilege	AQjmsDestination.revokeQueuePrivilege AQjmsDestination.revokeTopicPrivilege
Verify a Queue Type	DBMS_AQADM.verify_queue_types	Not supported	Not supported
Add a Subscriber	DBMS_AQADM.add_subscriber	AQQueue.addSubscriber	See Table 3-6, " Comparison of AQ Programmatic Environments: Operational Interface--Subscribing for Messages in a Multiconsumer Queue/Topic, Publish-Subscribe Model Use Cases"
Alter a Subscriber	DBMS_AQADM.alter_subscriber	AQQueue.alterSubscriber	See Table 3-6, " Comparison of AQ Programmatic Environments: Operational Interface--Subscribing for Messages in a Multiconsumer Queue/Topic, Publish-Subscribe Model Use Cases"
Remove a Subscriber	DBMS_AQADM.remove_subscriber	AQQueue.removeSubscriber	See Table 3-6, " Comparison of AQ Programmatic Environments: Operational Interface--Subscribing for Messages in a Multiconsumer Queue/Topic, Publish-Subscribe Model Use Cases"
Schedule Propagation	DBMS_AQADM.schedule_propagation	AQQueue.schedulePropagation	AQjmsDestination.schedulePropagation
Enable a Propagation Schedule	DBMS_AQADM.enable_propagation_schedule	AQQueue.enablePropagationSchedule	AQjmsDestination.enablePropagationSchedule
Alter a Propagation Schedule	DBMS_AQADM.alter_propagation_schedule	AQQueue.alterPropagationSchedule	AQjmsDestination.alterPropagationSchedule
Disable a Propagation Schedule	DBMS_AQADM.disable_propagation_schedule	AQQueue.disablePropagationSchedule	AQjmsDestination.disablePropagationSchedule
Unschedule a Propagation	DBMS_AQADM.unschedule_propagation	AQQueue.unschedulePropagation	AQjmsDestination.unschedulePropagation
Create an AQ Internet Agent	DBMS_AQADM.create_aq_agent	not supported	not supported
Alter an AQ Internet Agent	DBMS_AQADM.alter_aq_agent	not supported	not supported
Drop an AQ Internet Agent	DBMS_AQADM.drop_aq_agent	not supported	not supported
Grant Database User privileges to an AQ Internet Agent	DBMS_AQADM.enable_db_agent	not supported	not supported
Revoke Database User privileges from an AQ Internet Agent	DBMS_AQADM.disable_db_agent	not supported	not supported
Add alias for queue, agent, ConnectionFactory in a LDAP server	DBMS_AQADM.add_alias_to_ldap	not supported	not supported
Delete alias for queue, agent, ConnectionFactory in a LDAP server	DBMS_AQADM.del_alias_from_ldap	not supported	not supported

AQ Operational Interfaces

Table 3-3 through Table 3-9 list equivalent AQ operational functions for the programmatic environments PL/SQL, Java (native AQ), OCI, AQ XML Servlet, and JMS, for various use cases.

Table 3-3 Comparison of AQ Programmatic Environments: Operational Interface--Create Connection, Session, Message Use Cases

Use Case	PL/SQL	Java (Native AQ)	OCI	AQ XML Servlet	JMS
Create a Connection	N/A	Create JDBC connection	OCIServerAttach	Open an HTTP connection after authenticating with the Web server	AQjmsQueueConnectionFactory.createQueueConnection AQjmsTopicConnectionFactory.createTopicConnecion
Create a Session	N/A	AQDriverManager.createAQSession	OCISessionBegin	An HTTP servlet session is automatically started with the first SOAP request	QueueConnection.createQueueSession TopicConnecion.createTopicSession
Create a RAW Message	Use SQL RAW type for message	AQQueue.createMessage Set AQRawPayload in message	Use OCIRaw for Message	Supply the hex representation of the message payload in the XML message. E.g.: `<raw>023f4523</raw>`	Not supported
Create a Message with Structured Data	Use SQL ADT type for message	AQQueue.createMessage Set AQObjectPayload in message	Use SQL ADT type for message	For ADT 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	N/A	QueueSession.createSender TopicSession.createPublisher

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

Use Case	PL/SQL	Java (Native AQ)	OCI	AQ XML Servlet	JMS
Enqueue a Message to a single-consumer queue	DBMS_AQ.enqueue	AQQueue.enqueue	LNOCIAQEnq	`<AQXmlSend>`	QueueSender.send
Enqueue a Message to a queue - specify visibility options	DBMS_AQ.enqueue Specify visibility in ENQUEUE_OPTIONS	AQQueue.enqueue Specify visibility in AQEnqueueOption	LNOCIAQEnq Specify OCI_ATTR_VISIBILITY in LNOCIAQEnqOptions	`<AQXmlSend>` Specify `<visibility>` in `<producer_options>`	Not supported
Enqueue a Message to a single-consumer queue - specify message properties - priority, expiration	DBMS_AQ.enqueue Specify priority, expiration in MESSAGE_PROPERTIES	AQQueue.enqueue Specify priority, expiration in AQMessageProperty	LNOCIAQEnq Specify LNOCI_ATTR_PRIORITY, LNOCI_ATTR_EXPIRATION in LNOCIAQMsgProperties	`<AQXmlSend>` Specify `<priority>`, `<expiration>` in `<message_header>`	Specify priority and TimeToLive during QueueSender.send OR MessageProducer.setTimeToLive & MessageProducer.setPriority followed by QueueSender.send
Enqueue a Message to a single-consumer Queue - specify message properties - correlationID, delay, exception queue	DBMS_AQ.enqueue Specify correlation, delay, exception_queue in MESSAGE_PROPERTIES	AQQueue.enqueue Specify correlation, delay, exception queue in AQMessageProperty	LNOCIAQEnq Specify OCI_ATTR_CORRELATION, OCI_ATTR_DELAY, LNOCI_ATTR_EXCEPTION_QUEUE in LNOCIAQMsgProperties	`<AQXmlSend>` Specify `<correlation_id>`, `<delay>`, `<exception_queue>` in `<message_header>`	Message.setJMSCorrelationID 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 - specify Message Properties (user-defined)	Not supported Properties should be part of payload	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>,` etc. in `<user_properties>`	Message.setIntProperty Message.setStringProperty Message.setBooleanProperty etc. followed by QueueSender.send
Enqueue a Message to a single-consumer Queue - specify Message Transformation	DBMS_AQ.enqueue Specify transformation in ENQUEUE_OPTIONS	AQQueue.enqueue Specify transformation in AQDequeueOption	LNOCIAQEnq Specify OCI_ATTR_TRANSFORMATION in LNOCIAQEnqOptions	`<AQXmlSend>` Specify `<transformation>` in `<producer_options>`	AQjmsQueueSender.setTransformation followed by QueueSender.send

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

Use Case PL/SQL Java (Native AQ) OCI AQ XML Servlet JMS

Use Case	PL/SQL	Java (Native AQ)	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	AQQueue.enqueue Set recipient_list to NULL in AQMessageProperty	LNOCIAQEnq Set OCI_ATTR_RECIPIENT_LIST to NULL in LNOCIAQMsgProperties	`<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	AQQueue.enqueue Specify recipient_list in AQMessageProperty	LNOCIAQEnq Specify OCI_ATTR_RECIPIENT_LIST in LNOCIAQMsgProperties	`<AQXmlPublish>` Specify `<recipient_list>` in `<message_header>`	AQjmsTopicPublisher.pubish Specify recipients as an array of AQjmsAgent
Publish a Message to a multiconsumer Queue/Topic - specify message properties - priority, expiration	DBMS_AQ.enqueue Specify priority, expiration in MESSAGE_PROPERTIES	AQQueue.enqueue Specify priority, expiration in AQMessageProperty	LNOCIAQEnq Specify OCI_ATTR_PRIORITY, LNOCI_ATTR_EXPIRATION in LNOCIAQMsgProperties	`<AQXmlPublish>` Specify `<priority>`, `<expiration>` in the `<message_header>`	Specify priority and TimeToLive during TopicPublisher.publish OR MessageProducer.setTimeToLive & MessageProducer.setPriority followed by TopicPublisher.publish
Publish a Message to a multiconsumer queue/topic - specify send options - correlationID, delay, exception queue	DBMS_AQ.enqueue Specify correlation, delay, exception_queue in MESSAGE_PROPERTIES	AQQueue.enqueue Specify correlation, delay, exception queue in AQMessageProperty	LNOCIAQEnq Specify OCI_ATTR_CORRELATION, OCI_ATTR_DELAY, LNOCI_ATTR_EXCEPTION_QUEUE in LNOCIAQMsgProperties	`<AQXmlPublish>` Specify `<correlation_id>`, `<delay>`, `<exception_queue>` in `<message_header>`	Message.setJMSCorrelationID Delay and exception queue specified as provider specific message properties JMS_OracleDelay JMS_OracleExcpQ followed by TopicPublisher.publish
Publish a Message to a topic- specify Message Properties (user-defined)	Not supported Properties should be part of payload	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>,` etc. in `<user_properties>`	Message.setIntProperty Message.setStringProperty Message.setBooleanProperty etc. followed by TopicPublisher.publish
Publish a Message to a topic- specify Message Transformation	DBMS_AQ.enqueue Specify transformation in ENQUEUE_OPTIONS	AQQueue.enqueue Specify transformation in AQDequeueOption	LNOCIAQEnq Specify OCI_ATTR_TRANSFORMATION in LNOCIAQEnqOptions	`<AQXmlPublish>` Specify `<transformation>` in `<producer_options>`	AQjmsTopicPublisher.setTransformation 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

AQQueue.enqueue

Set recipient_list to NULL in AQMessageProperty

LNOCIAQEnq

Set OCI_ATTR_RECIPIENT_LIST to NULL in LNOCIAQMsgProperties

<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

AQQueue.enqueue

Specify recipient_list in AQMessageProperty

LNOCIAQEnq

Specify OCI_ATTR_RECIPIENT_LIST in LNOCIAQMsgProperties

<AQXmlPublish> Specify <recipient_list> in <message_header>

AQjmsTopicPublisher.pubish

Specify recipients as an array of AQjmsAgent

Publish a Message to a multiconsumer Queue/Topic - specify message properties - priority, expiration

DBMS_AQ.enqueue

Specify priority, expiration in MESSAGE_PROPERTIES

AQQueue.enqueue

Specify priority, expiration in AQMessageProperty

LNOCIAQEnq

Specify OCI_ATTR_PRIORITY, LNOCI_ATTR_EXPIRATION in LNOCIAQMsgProperties

<AQXmlPublish> Specify <priority>, <expiration> in the <message_header>

Specify priority and TimeToLive during TopicPublisher.publish OR MessageProducer.setTimeToLive & MessageProducer.setPriority followed by

TopicPublisher.publish

Publish a Message to a multiconsumer queue/topic - specify send options - correlationID, delay, exception queue

DBMS_AQ.enqueue

Specify correlation, delay, exception_queue in MESSAGE_PROPERTIES

AQQueue.enqueue

Specify correlation, delay, exception queue in AQMessageProperty

LNOCIAQEnq

Specify OCI_ATTR_CORRELATION, OCI_ATTR_DELAY, LNOCI_ATTR_EXCEPTION_QUEUE in LNOCIAQMsgProperties

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

Message.setJMSCorrelationID

Delay and exception queue specified as provider specific message properties

JMS_OracleDelay

JMS_OracleExcpQ

followed by TopicPublisher.publish

Publish a Message to a topic- specify Message Properties (user-defined)

Not supported

Properties should be part of payload

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>, etc. in <user_properties>

Message.setIntProperty

Message.setStringProperty

Message.setBooleanProperty etc. followed by

TopicPublisher.publish

Publish a Message to a topic- specify Message Transformation

DBMS_AQ.enqueue

Specify transformation in ENQUEUE_OPTIONS

AQQueue.enqueue

Specify transformation in AQDequeueOption

LNOCIAQEnq

Specify OCI_ATTR_TRANSFORMATION in LNOCIAQEnqOptions

<AQXmlPublish> Specify <transformation> in <producer_options>

AQjmsTopicPublisher.setTransformation

followed by

TopicPublisher.publish

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

Use Case	PL/SQL	Java (Native AQ)	OCI	AQ XML Servlet	JMS
Add a Subscriber	See administrative interfaces	See administrative interfaces	Not supported	Not supported	TopicSession.createDurableSubscriber AQjmsSession.createDurableSubscriber
Alter a Subscriber	See administrative interfaces	See administrative interfaces	Not supported	Not supported	TopicSession.createDurableSubscriber AQjmsSession.createDurableSubscriber using the new selector
Remove a Subscriber	See administrative interfaces	See administrative interfaces	Not supported	Not supported	AQjmsSession.unsubscriber

Use Case

PL/SQL

Java (Native AQ)

OCI

AQ XML Servlet

JMS

Add a Subscriber

See administrative interfaces

Not supported

TopicSession.createDurableSubscriber

AQjmsSession.createDurableSubscriber

Alter a Subscriber

See administrative interfaces

Not supported

TopicSession.createDurableSubscriber

AQjmsSession.createDurableSubscriber

using the new selector

Remove a Subscriber

See administrative interfaces

Not supported

AQjmsSession.unsubscriber

Table 3-7 Comparison of AQ Programmatic Environments: Operational Interface--Browse Messages in a Queue Use Cases

Use Case PL/SQL Java (Native AQ) OCI AQ XML Servlet JMS

Use Case	PL/SQL	Java (Native AQ)	OCI	AQ XML Servlet	JMS
Browse messages in a Queue/Topic	DBMS_AQ.dequeue Set dequeue_mode to BROWSE in DEQUEUE_OPTIONS	AQQueue.dequeue Set dequeue_mode to BROWSE in AQDequeueOption	LNOCIAQDeq Set OCI_ATTR_DEQ_MODE to BROWSE in LNOCIAQDeqOptions	`<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 - locking messages while browsing	DBMS_AQ.dequeue Set dequeue_mode to LOCKED in DEQUEUE_OPTIONS	AQQueue.dequeue Set dequeue_mode to LOCKED in AQDequeueOption	LNOCIAQDeq Set OCI_ATTR_DEQ_MODE to LOCKED in LNOCIAQDeqOptions	`<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

AQQueue.dequeue

Set dequeue_mode to BROWSE in AQDequeueOption

LNOCIAQDeq

Set OCI_ATTR_DEQ_MODE to BROWSE in LNOCIAQDeqOptions

<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 - locking messages while browsing

DBMS_AQ.dequeue

Set dequeue_mode to LOCKED in DEQUEUE_OPTIONS

AQQueue.dequeue

Set dequeue_mode to LOCKED in AQDequeueOption

LNOCIAQDeq

Set OCI_ATTR_DEQ_MODE to LOCKED in LNOCIAQDeqOptions

<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 AQ Programmatic Environments: Operational Interface--Receive Messages from a Queue/Topic Use Cases

Use Case	PL/SQL	Java (Native AQ)	OCI	AQ XML Servlet	JMS
Start a connection for receiving messages	N/A	N/A	N/A	N/A	Connection.start
Create a Message Consumer	N/A	N/A	N/A	N/A	QueueSession.createQueueReceiver TopicSession.createDurableSubscriber AQjmsSession.createTopicReceiver
Dequeue a message from a queue/topic - specify visibility	DBMS_AQ.dequeue Specify visibility in DEQUEUE_OPTIONS	AQQueue.dequeue Specify visibility in AQDequeueOption	LNOCIAQDeq Specify OCI_ATTR_VISIBILITY in LNOCIAQDeqOptions	`<AQXmlReceive>` Specify `<visibility>` in `<consumer_options>`	Not supported
Dequeue a message from a queue/topic - specify transformation	DBMS_AQ.dequeue Specify transformation in DEQUEUE_OPTIONS	DBMS_AQ.dequeue Specify transformation in AQDequeueOption	LNOCIAQDeq Specify OCI_ATTR_TRANSFORMATION in LNOCIAQDeqOptions	`<AQXmlReceive>` Specify `<transformation>` in `<consumer_options>`	AQjmsQueueReceiver.setTransformation AQjmsTopicSubscriber.setTransformation AQjmsTopicReceiver.setTransformation
Dequeue a message from a queue/topic - specify navigation mode	DBMS_AQ.dequeue Specify navigation in DEQUEUE_OPTIONS	DBMS_AQ.dequeue Specify navigation in AQDequeueOption	LNOCIAQDeq Specify OCI_ATTR_NAVIGATION in LNOCIAQDeqOptions	`<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	AQQueue.dequeue Set dequeue_mode to REMOVE in AQDequeueOption	LNOCIAQDeq Set OCI_ATTR_DEQ_MODE to REMOVE in LNOCIAQDeqOptions	`<AQXmlReceive>`	QueueReceiver.receive or QueueReceiver.receiveNoWait 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	AQQueue.dequeue Set dequeue_mode to REMOVE and Set consumer_name to subscription name in AQDequeueOption	LNOCIAQDeq Set OCI_ATTR_DEQ_MODE to REMOVE and Set OCI_ATTR_CONSUMER_NAME to subscription name in LNOCIAQDeqOptions	`<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	AQQueue.dequeue Set dequeue_mode to REMOVE and Set consumer_name to recipient name inAQDequeueOption	LNOCIAQDeq Set OCI_ATTR_DEQ_MODE to REMOVE and Set OCI_ATTR_CONSUMER_NAME to recipient name in LNOCIAQDeqOptions	`<AQXmlReceive>` Specify `<consumer_name>` in `<consumer_options>`	Create a TopicReceiver on the Topic using the recipient name, then AQjmsSession.createTopicReceiver AQjmsTopicReceiver.receive or AQjmsTopicReceiver.receiveNoWait or AQjmsTopicReceiver.receiveNoData

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

Use Case	PL/SQL	Java (Native AQ)	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	Not supported	LNOCISubscriptionRegister Specify queue_name as subscription name LNOCISubscriptionEnable	`<AQXmlRegister>` Specify queue name in `<destination>` and notification mechanism in `<notify_url>`	Create a QueueReceiver on the queue, then QueueReceiver.setMessageListener
Receive messages Asynchronously from a multiconsumer queue/Topic	Define a PL/SQL callback procedure Register it using DBMS_AQ.register	Not supported	LNOCISubscriptionRegister Specify queue:OCI_ATTR_CONSUMER_NAME as subscription name LNOCISubscriptionEnable	`<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 TopicReceiver.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	Not supported	LNOCIAQListen Use agent_name as NULL for all agents in agent_list	Not supported	Create multiple QueueReceivers on a QueueSession, then QueueSession.setMessageListener
Listen for messages on one(many) multiconsumer queues/Topics	DBMS_AQ.listen Specify agent_name for all agents in agent_list	Not supported	LNOCIAQListen Specify agent_name for all agents in agent_list	Not supported	Create multiple TopicSubscribers or TopicReceivers on a TopicSession, then TopicSession.setMessageListener

3 AQ Programmatic Environments

Programmatic Environments for Accessing AQ

Table 3-1 AQ Programmatic Environments

Using PL/SQL to Access AQ

Using OCI to Access AQ

Examples

LNOCI Interface

Managing OCI Descriptor Memory

Using Visual Basic (OO4O) to Access AQ

For More Information

Using AQ Java (oracle.AQ) Classes to Access AQ

Accessing Java AQ Classes

Advanced Queuing Examples

Managing the Java AQ API

Using Oracle Java Message Service to Access AQ

Standard JMS Features

Oracle JMS Extensions

Accessing Standard and Oracle JMS

Privileges

For More Information

Using the AQ XML Servlet to Access AQ

Comparing AQ Programmatic Environments

AQ Administrative Interfaces

Table 3-2 Comparison of AQ Programmatic Environments: Administrative Interface

AQ Operational Interfaces

Table 3-3 Comparison of AQ Programmatic Environments: Operational Interface--Create Connection, Session, Message Use Cases

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

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

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

Table 3-7 Comparison of AQ Programmatic Environments: Operational Interface--Browse Messages in a Queue Use Cases

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

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

3
AQ Programmatic Environments