4 Oracle Streams AQ: Programmatic Environments

Programmatic Environments for Accessing Oracle Streams AQ

Table 4-1 lists Oracle Streams AQ programmatic environments, functions supported in each environment, and syntax references.

Using PL/SQL to Access Oracle Streams AQ

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

• Create queue, queue table, nonpersistent queue, multiconsumer queue/topic, RAW message, or message with structured data

• Get queue table, queue, or multiconsumer queue/topic

• Alter queue table or queue/topic

• Drop queue/topic

• Start or stop queue/topic

• Grant and revoke privileges

• Add, remove, or alter subscriber

• Add, remove, or alter an Oracle Streams AQ Internet agent

• Grant or revoke privileges of database users to Oracle Streams AQ Internet agents

• Enable, disable, or alter propagation schedule

• Enqueue messages to single consumer queue (point-to-point model)

• Publish messages to multiconsumer queue/topic (publish/subscribe model)

• Subscribe for messages in multiconsumer queue

• Browse messages in a queue

• Receive messages from queue/topic

• Register to receive messages asynchronously

• Listen for messages on multiple queues/topics

• Post messages to anonymous subscriptions

• Bind or unbind agents in a Lightweight Directory Access Protocol (LDAP) server

• Add or remove aliases to Oracle Streams AQ objects in a LDAP server

  
  

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

  
  

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

Using OCI to Access Oracle Streams AQ

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

An OCI client can perform the following actions:

• Enqueue messages

• Dequeue messages

• Listen for messages on sets of queues

• Register to receive message notifications

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

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.

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.

Using Visual Basic (OO4O) to Access Oracle Streams AQ

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

These functions include the following:

• Create a connection, RAW message, or message with structured data

• Enqueue messages to a single consumer queue (point-to-point model)

• Publish messages to a multiconsumer queue/topic (publish/subscribe model)

• Browse messages in a queue

• Receive messages from a queue/topic

• Register to receive messages asynchronously

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

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

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

Standard JMS features include:

• Point-to-point model of communication using queues

• Publish/subscribe model of communication using topics

• ObjectMessage, StreamMessage, TextMessage, BytesMessage, and MapMessage message types

• Asynchronous and synchronous delivery of messages

• Message selection based on message header fields or properties

Oracle JMS extensions include:

• Administrative API to create queue tables, queues and topics

• Point-to-multipoint communication using recipient lists for topics

• Message propagation between destinations, which allows the application to define remote subscribers

• Support for transactional sessions, enabling JMS and SQL operations in one transaction

• Message retention after messages have been dequeued

• Message delay, allowing messages to be made visible after a certain delay

• Exception handling, allowing messages to be moved to exception queues if they cannot be processed successfully

• Support for AdtMessages

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

• Topic browsing

  This allows durable subscribers to browse through the messages in a publish/subscribe (topic) destination. It optionally allows these subscribers to purge the browsed messages, so they are no longer retained by Oracle Streams AQ for that subscriber.

  
  

  See Also: Java Message Service Specification, version 1.1, March 18, 2002, Sun Microsystems, Inc. http://otn.oracle.com/docs/products/aq/doc_library/ojms/index.html for more information on Oracle JMS Part V, " Using Oracle JMS and Oracle Streams AQ " Oracle Streams Advanced Queuing Java API Reference

  
  

$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

$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 Streams AQ XML Servlet to Access Oracle Streams AQ

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

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

• Send messages to single-consumer queues

• Publish messages to multiconsumer queues/topics

• Receive messages from queues

• Register to receive message notifications

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 the Javasoft Servlet 2.0 or Servlet 2.2 interfaces. With Javasoft Servlet 2.0, you must define a class that extends oracle.AQ.xml.AQxmlServlet20. With Javasoft Servlet 2.2, you must define a class that extends oracle.AQ.xml.AQxmlServlet.

The servlet can be compiled using JDK 1.2.x, JDK 1.3.x, or JDK 1.4.x libraries.

For JDK 1.4.x the CLASSPATH must contain:

$ORACLE_HOME/jdbc/lib/classes12.jar
$ORACLE_HOME/jdbc/lib/ojdbc14.jar
$ORACLE_HOME/jdbc/lib/orai18n.jar
$ORACLE_HOME/jlib/jndi.jar
$ORACLE_HOME/jlib/jta.jar
$ORACLE_HOME/lib/servlet.jar
$ORACLE_HOME/lib/xmlparserv2.jar
$ORACLE_HOME/lib/xschema.jar
$ORACLE_HOME/lib/xsu12.jar
$ORACLE_HOME/rdbms/jlib/aqapi.jar
$ORACLE_HOME/rdbms/jlib/aqxml.jar
$ORACLE_HOME/rdbms/jlib/jmscommon.jar

For JDK 1.3.x the CLASSPATH must contain:

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

For JDK 1.2.x the CLASSPATH must contain:

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

Because the servlet uses JDBC OCI drivers to connect to the Oracle Database server, the Oracle Database client libraries must be installed on the computer that hosts the servlet. The LD_LIBRARY_PATH must contain $ORACLE_HOME/lib.

Comparing Oracle Streams AQ Programmatic Environments

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