Oracle Streams Event Staging and Propagation Overview

Oracle Streams uses queues of type SYS.AnyData to stage events. There are two types of events that can be staged in an Oracle Streams queue:

Logical change records (LCRs). LCRs are objects that contain information about a change to a database object.

User messages. These are custom messages created by users or applications.

Both types of events are of type SYS.AnyData and can be used for information sharing within a single database or between databases.

Staged events can be consumed or propagated, or both. These events can be consumed by an apply process or by a user application that explicitly dequeues them. Even after an event is consumed, it can remain in the queue if you have also configured Oracle Streams to propagate the event to one or more other queues or if message retention is specified. These other queues can reside in the same database or in different databases. In either case, the queue from which the events are propagated is called the source queue, and the queue that receives the events is called the destination queue.

SYS.AnyData Queues and User Messages

Oracle Streams enables messaging with queues of type SYS.AnyData. SYS.AnyData queues can stage user messages whose payloads are of SYS.AnyData type. A SYS.AnyData payload can be a wrapper for payloads of different datatypes. Queues that can stage messages of only a particular type are called typed queues.

By using SYS.AnyData wrappers for message payloads, publishing applications can enqueue messages of different types into a single queue. Subscribing applications can then dequeue these messages, either explicitly using a dequeue API or implicitly using an apply process. If the subscribing application is remote, then the messages can be propagated to the remote site, and the subscribing application can dequeue the messages from a local queue in the remote database. Alternatively, a remote subscribing application can dequeue messages directly from the source queue using a variety of standard protocols, such as PL/SQL and Oracle Call Interface (OCI).

Oracle Streams interoperates with Oracle Streams AQ, which supports all the standard features of message queuing systems, including multiconsumer queues, publish and subscribe, content-based routing, internet propagation, transformations, and gateways to other messaging subsystems.

SYS.AnyData Wrapper for User Messages Payloads

You can wrap almost any type of payload in a SYS.AnyData payload. To do this, you use the Convertdata_type static functions of the SYS.AnyData type, where data_type is the type of object to wrap. These functions take the object as input and return a SYS.AnyData object.

Enqueuing User Messages Using PL/SQL

To enqueue a user message containing an LCR into a SYS.AnyData queue using PL/SQL, first create the LCR to be enqueued. You use the constructor for the SYS.LCR$_ROW_RECORD type to create a row LCR, and you use the constructor for the SYS.LCR$_DDL_RECORD type to create a DDL LCR. Then you use the SYS.AnyData.ConvertObject function to convert the LCR into SYS.AnyData payload and enqueue it using the DBMS_AQ.ENQUEUE procedure.

To enqueue a user message containing a non-LCR object into a SYS.AnyData queue using PL/SQL, you use one of the SYS.AnyData.Convert* functions to convert the object into SYS.AnyData payload and enqueue it using the DBMS_AQ.ENQUEUE procedure.

Enqueuing User Messages Using OCI or JMS

To enqueue a user message containing an LCR into a SYS.AnyData queue using JMS or OCI, you must represent the LCR in XML format. To construct an LCR, use the oracle.xdb.XMLType class. LCRs are defined in the SYSschema. The LCR schema must be loaded into the SYS schema using the catxlcr.sql script in Oracle home in the rdbms/admin/ directory.

To enqueue a message using OCI, perform the same actions that you would to enqueue a message into a typed queue. A typed queue is a queue that can stage messages of a particular type only. To enqueue a message using JMS, a user must have EXECUTE privilege on DBMS_AQ, DBMS_AQIN, and DBMS_AQJMS packages.

Note:

Enqueue of JMS types and XML types does not work with Oracle Streams Sys.Anydata queues unless you call DBMS_AQADM.ENABLE_JMS_TYPES(queue_table_name) after DBMS_STREAMS_ADM.SET_UP_QUEUE(). Enabling an Oracle Streams queue for these types may affect import/export of the queue table.

A non-LCR user message can be a message of any user-defined type or a JMS type. The JMS types include the following:

javax.jms.TextMessage

javax.jms.MapMessage

javax.jms.StreamMessage

javax.jms.ObjectMessage

javax.jms.BytesMessage

When using user-defined types, you must generate the Java class for the message using Jpublisher, which implements the ORAData interface. To enqueue a message into a SYS.AnyData queue, you can use methods QueueSender.send or TopicPublisher.publish.

Dequeuing User Messages Using PL/SQL

To dequeue a user message from SYS.AnyData queue using PL/SQL, you use the DBMS_AQ.DEQUEUE procedure and specify SYS.AnyData as the payload. The user message can contain an LCR or another type of object.

Dequeuing User Messages Using OCI or JMS

In a SYS.AnyData queue, user messages containing LCRs in XML format are represented as oracle.xdb.XMLType. Non-LCR messages can be one of the following formats:

To dequeue a message from a SYS.AnyData queue using JMS, you can use methods QueueReceiver, TopicSubscriber, or TopicReceiver. Because the queue can contain different types of objects wrapped in a SYS.AnyData wrapper, you must register a list of SQL types and their corresponding Java classes in the typemap of the JMS session. JMS types are already preregistered in the typemap.

For example, suppose a queue contains LCR messages represented as oracle.xdb.XMLType and messages of type person and address. The classes JPerson.java and JAddress.java are the ORAData mappings for person and address, respectively. Before dequeuing the message, the type map must be populated as follows:

Message Propagation and SYS.AnyData Queues

SYS.AnyData queues can interoperate with typed queues in an Oracle Streams environment. A typed queue can stage messages of a particular type only. Table 23-1 shows the types of propagation possible between queues.

To propagate messages containing a payload of a certain type from a SYS.AnyData source queue to a typed destination queue, you must perform a transformation. Only messages containing a payload of the same type as the typed queue can be propagated to the typed queue.

Although you cannot use Simple Object Access Protocol (SOAP) to interact directly with a SYS.AnyData queue, you can use SOAP with Oracle Streams by propagating messages between a SYS.AnyData queue and a typed queue. If you want to enqueue a message into a SYS.AnyData queue using SOAP, then you can configure propagation from a typed queue to SYS.AnyData queue. Then, you can use SOAP to enqueue a message into the typed queue. The message is propagated automatically from the typed queue to the SYS.AnyData queue.

If you want to use SOAP to dequeue a message that is in a SYS.AnyData queue, then you can configure propagation from a SYS.AnyData queue to a typed queue. The message is propagated automatically from the SYS.AnyData queue to the typed queue. Then, the message would be available for access using SOAP.

Note:

Certain Oracle Streams capabilities, such as capturing changes using a capture process and applying changes with an apply process, can be configured only with SYS.AnyData queues.

User-Defined Type Messages

If you plan to enqueue, propagate, or dequeue user-defined type messages in an Oracle Streams environment, then each type used in these messages must exist at every database where the message can be staged in a queue. Some environments use directed networks to route messages through intermediate databases before they reach their destination. In such environments, the type must exist at each intermediate database, even if the messages of this type are never enqueued or dequeued at a particular intermediate database.

Managing an Oracle Streams Messaging Environment

Oracle Streams enables messaging with queues of type SYS.AnyData. These queues stage user messages whose payloads are of SYS.AnyData type, and a SYS.AnyData payload can be a wrapper for payloads of different datatypes.

This section provides instructions for completing the following tasks:

To dequeue messages, you must know the consumer of the messages. To find the consumer for the messages in a queue, connect as the owner of the queue and query the AQ$queue_table_name, where queue_table_name is the name of the queue table. For example, to find the consumers of the messages in the oe_q_any queue, run the following query:

Create a procedure that takes as an input the consumer of the messages you want to dequeue. The following example procedure dequeues messages of oe.cust_address_typ and prints the contents of the messages.

Propagating Messages Between a SYS.AnyData Queue and a Typed Queue

SYS.AnyData queues can interoperate with typed queues in an Oracle Streams environment. A typed queue is a queue that can stage messages of a particular type only. To propagate a message from a SYS.AnyData queue to a typed queue, the message must be transformed to match the type of the typed queue. The following sections provide examples of propagating non-LCR user messages and LCRs between a SYS.AnyData queue and a typed queue.

The following steps set up propagation from a SYS.AnyData queue named oe_q_any to a typed queue of type oe.cust_address_typ named oe_q_address. The source queue oe_q_any is at the dbs1.net database, and the destination queue oe_q_address is at the dbs2.net database. Both queues are owned by strmadmin.

Connect as an administrative user who can grant privileges at dbs1.net.

Grant the following privilege to strmadmin, if it was not already granted.

GRANT EXECUTE ON DBMS_TRANSFORM TO strmadmin;

Grant strmadminEXECUTE privilege on oe.cust_address_typ at dbs1.net and dbs2.net.

Create a function called any_to_cust_address_typ in the strmadmin schema at dbs1.net that takes a SYS.AnyData payload containing a oe.cust_address_typ object and returns the oe.cust_address_typ object.

Create a subscriber for the typed queue if one does not already exist. The subscriber must contain a rule that ensures that only messages of the appropriate type are propagated to the destination queue.

To propagate LCRs from a SYS.AnyData queue to a typed queue, you complete the same steps as you do for non-LCR events, but Oracle supplies the transformation functions. You can use the following functions in the DBMS_STREAMS package to transform LCRs in SYS.AnyData queues to messages in typed queues:

You can propagate user-enqueued LCRs to an appropriate typed queue, but propagation of captured LCRs to a typed queue is not supported.

The following example sets up propagation of row LCRs from a SYS.AnyData queue named oe_q_any to a typed queue of type SYS.LCR$_ROW_RECORD named oe_q_lcr. The source queue oe_q_any is at the dbs1.net database, and the destination queue oe_q_lcr is at the dbs3.net database.

Connect as an administrative user who can grant privileges at dbs1.net.

Grant the following privilege to strmadmin, if it was not already granted.