Merge pull request #1028 from oracle/txeventq-typos-cleanup

TxEventQ Typos

Author: anders-swanson

docs-source/transactional-event-queues/content/_index.md

@@ -5,7 +5,7 @@ title = "Transactional Event Queues"
 
 [Oracle Transactional Event Queues (TxEventQ)](https://www.oracle.com/database/advanced-queuing/) is a messaging platform built into Oracle Database that combines the best features of messaging and pub/sub systems. TxEventQ was introduced as a rebranding of AQ Sharded Queues in Oracle Database 21c, evolving from the Advanced Queuing (AQ) technology that has been part of Oracle Database since version 8.0. TxEventQ continues to evolve in Oracle Database 23ai, with [Kafka Java APIs](https://github.com/oracle/okafka), Oracle REST Data Services (ORDS) integration, and many more features and integrations.
 
-TxEventQ is designed for high-throughput, reliable messaging in event-driven microservices and workflow applications. It supports multiple publishers and consumers, exactly-once delivery, and robust event streaming capabilities. On an 8-node Oracle Real Application Clusters (RAC) database, TxEventQ can handle approximately 1 million messages per second, demonstrating its scalability.
+TxEventQ is designed for high-throughput, reliable messaging in event-driven microservices and workflow applications. It supports multiple publishers and consumers, exactly-once message delivery, and robust event streaming capabilities. On an 8-node Oracle Real Application Clusters (RAC) database, TxEventQ can handle approximately 1 million messages per second, demonstrating its scalability.
 
 TxEventQ differs from traditional AQ (now referred to as AQ Classic Queues) in several ways:
 

docs-source/transactional-event-queues/content/aq-migration/_index.md

@@ -6,6 +6,8 @@ weight = 5
 
 Oracle Database 23ai includes a migration path from Advanced Queuing (AQ) to Transactional Event Queues (TxEventQ), to take advantage of enhanced performance and scalability for event-driven architectures.
 
+Advanced Queuing (AQ) has been Oracle’s traditional messaging system for managing asynchronous communication in enterprise applications, allowing reliable queuing and message delivery. TxEventQ leverages Kafka-based event queuing, offering improved throughput, lower latency, and greater scalability, making it ideal for modern event-driven architectures and high-volume event processing.
+
 The [DBMS_AQMIGTOOL](https://docs.oracle.com/en/database/oracle/oracle-database/23/arpls/DBMS_AQMIGTOOL.html) package facilitates a smooth migration process, designed to be non-disruptive and allowing the parallel operation of AQ and TxEventQ during the transition, enabling a smooth cut-over with minimal downtime for your applications.
 
 The migration from AQ to TxEventQ is suitable for various scenarios:

docs-source/transactional-event-queues/content/aq-migration/migration.md

@@ -4,7 +4,8 @@ title = "AQ Migration"
 weight = 1
 +++
 
-This section covers the use of the [DBMS_AQMIGTOOL](https://docs.oracle.com/en/database/oracle/oracle-database/23/arpls/DBMS_AQMIGTOOL.html) package for migrating Advanced Queuing (AQ) classic queues to TxEventQ. 
+
+This section provides a detailed guide for migrating from Oracle Advanced Queuing (AQ) to Transactional Event Queues (TxEventQ). The migration process uses the [DBMS_AQMIGTOOL](https://docs.oracle.com/en/database/oracle/oracle-database/23/arpls/DBMS_AQMIGTOOL.html) package to ensure minimal disruption of existing messaging workflows.
 
 Users of AQ are recommended to migrate to TxEventQ for increased support, performance, and access to new database features. It is recommended to read through the document fully before attempting migration.
 

docs-source/transactional-event-queues/content/getting-started/_index.md

@@ -11,20 +11,20 @@ This module will cover the following key topics:
 ## Core Concepts
 - Queues and topics
 - Enqueue/Dequeue vs. Publish/Subscribe models
-- Payload types: RAW, ADT, JSON, and JMS
+- Payload types: RAW, Abstract Data Type (ADT), JSON, and JMS
 
 ## Queue Management
 - Necessary grants, roles, and permissions for using queues
 - Creating, starting, stopping, and dropping queues/topics in various languages
-- SQLcl examples for queue operations
+- SQL examples for queue operations
 
 ## Message Operations
 - Producing and consuming messages
-- Message expiry and exception queues
+- Message expiration and exception queues
 - Message Delay
 - Message Priority
+- Transactional messaging: Combining messaging and DML in a single transaction
 
 ## Advanced Features
-- Transactional messaging: Combining messaging and DML in a single transaction
 - Message propagation between queues and databases
 - Exception queues and error handling

docs-source/transactional-event-queues/content/getting-started/advanced-features.md

@@ -4,71 +4,17 @@ title = "Advanced Features"
 weight = 4
 +++
 
-This section explains advanced features of Transactional Event Queues, including transactional messaging, message propagation between queues and the database, and error handling.
+This section explains advanced features of Transactional Event Queues, including message propagation between queues and the database, and error handling.
 
-* [Transactional Messaging: Combine Messaging with Database Queries](#transactional-messaging-combine-messaging-with-database-queries)
-  * [SQL Example](#sql-example)
 * [Message Propagation](#message-propagation)
     * [Queue to Queue Message Propagation](#queue-to-queue-message-propagation)
     * [Stopping Queue Propagation](#stopping-queue-propagation)
     * [Using Database Links](#using-database-links)
 * [Error Handling](#error-handling)
 
-
-## Transactional Messaging: Combine Messaging with Database Queries
-
-Enqueue and dequeue operations occur within database transactions, allowing developers to combine database queries (DML) with messaging operations. This is particularly useful when the message contains data relevant to other tables or services within your schema.
-
-### SQL Example
-
-In the following example, a DML operation (an `INSERT` query) is combined with an enqueue operation in the same transaction. If the enqueue operation fails, the `INSERT` is rolled back. The orders table serves as the example.
-
-```sql
-create table orders (
-    id number generated always as identity primary key,
-    product_id number not null,
-    quantity number not null,
-    order_date date default sysdate
-);
-
-declare
-    enqueue_options dbms_aq.enqueue_options_t;
-    message_properties dbms_aq.message_properties_t;
-    msg_id raw(16);
-    message json;
-    body varchar2(200) := '{"product_id": 1, "quantity": 5}';
-    product_id number;
-    quantity number;
-begin
-    -- Convert the JSON string to a JSON object
-    message := json(body);
-
-    -- Extract product_id and quantity from the JSON object
-    product_id := json_value(message, '$.product_id' returning number);
-    quantity := json_value(message, '$.quantity' returning number);
-
-    -- Insert data into the orders table
-    insert into orders (product_id, quantity)
-        values (product_id, quantity);
-
-    -- Enqueue the message
-    dbms_aq.enqueue(
-            queue_name => 'json_queue',
-            enqueue_options => enqueue_options,
-            message_properties => message_properties,
-            payload => message,
-            msgid => msg_id
-    );
-    commit;
-end;
-/
-```
-
-> Note: The same pattern applies to the `dbms_aq.dequeue` procedure, allowing developers to perform DML operations within dequeue transactions.
-
 ## Message Propagation
 
-Messages can be propagated within the same database or across a [database link](https://docs.oracle.com/en/database/oracle/oracle-database/23/sqlrf/CREATE-DATABASE-LINK.html) to different queues or topics. Message propagation is useful for workflows that require message processing d by different consumers or for event-driven actions that need to trigger subsequent processes.
+Messages can be propagated within the same database or across a [database link](https://docs.oracle.com/en/database/oracle/oracle-database/23/sqlrf/CREATE-DATABASE-LINK.html) to different queues or topics. Message propagation is useful for workflows that require processing by different consumers or for event-driven actions that need to trigger subsequent processes.
 
 #### Queue to Queue Message Propagation
 
@@ -137,7 +83,7 @@ alter system set job_queue_processes=10;
 
 #### Stopping Queue Propagation
 
-You can stop propagation using the DBMS_AQADM.STOP_PROPAGATION procedures:
+You can stop propagation using the [DBMS_AQADM.UNSCHEDULE_PROPAGATION](https://docs.oracle.com/en/database/oracle/oracle-database/23/arpls/DBMS_AQADM.html#GUID-4B4E25F4-E11F-4063-B1B8-7670C2537F47) procedure:
 
 ```sql
 begin
@@ -153,14 +99,16 @@ Your can view queue subscribers and propagation schedules from the respective `D
 
 #### Using Database Links
 
-To propagate messages between databases, a [database link](https://docs.oracle.com/en/database/oracle/oracle-database/23/sqlrf/CREATE-DATABASE-LINK.html) from the local database to the remote database must be created. The  subscribe and propagation commands must be altered to use the database link.
+To propagate messages between databases, a [database link](https://docs.oracle.com/en/database/oracle/oracle-database/23/sqlrf/CREATE-DATABASE-LINK.html) from the local database to the remote database must be created. The subscribe and propagation commands must be altered to use the database link.
 
 ```sql
 begin
     dbms_aqadm.schedule_propagation(
         queue_name => 'source',
-        destination => '<database link>.<schema name>', -- replace with your database link and schema name,
-        destination_queue => 'dest'
+        -- replace with your database link
+        destination => 'database_link',
+        -- replace with your remote schema and queue name
+        destination_queue => 'schema.queue_name' 
     );
 end;
 /
@@ -194,8 +142,8 @@ begin
     dbms_output.put_line('message: ' || message_buffer);
 exception
     when others then
+        rollback;
         dbms_output.put_line('error dequeuing message: ' || sqlerrm);
 end;
 /
 ```
-

docs-source/transactional-event-queues/content/getting-started/core-concepts.md

@@ -120,7 +120,7 @@ end;
 
 #### Object
 
-For structured, complex messages, you may choose to set the payload type as a custom object type that was defined using `create type`. Object types must reside in the same schema as the queue/topic, and the structure of each message must exactly match the payload type.
+For structured, complex messages, you may choose to set the payload type as a custom object type that was defined using `create type`. Object types must be accessible from the queue/topic, and the structure of each message must exactly match the payload type.
 
 The following SQL script defines a custom object type, and then creates a Transactional Event Queue using that type.
 
@@ -149,4 +149,6 @@ end;
 
 #### Kafka Message Payloads
 
-Topics created using the Kafka APIs for Transactional Event Queues use a Kafka message payload type, and so specifying the payload type is not necessary. Additionally, topics created using Kafka APIs should also be managed, produced and consumed from using the appropriate Kafka APIs.
+Topics created using the Kafka APIs for Transactional Event Queues use a Kafka message payload type, and specifying the payload type is not necessary. Additionally, topics created using Kafka APIs should also be managed and interacted with using the appropriate Kafka APIs.
+
+For more information on using Kafka APIs with TxEventQ, see the [Kafka chapter](../kafka/_index.md).

docs-source/transactional-event-queues/content/getting-started/message-operations.md

@@ -6,6 +6,7 @@ weight = 3
 
 This section explains message operations using queues, topics, and different programming interfaces (SQL, Java, Spring JMS, and more). You’ll learn how to enqueue, dequeue, and manage messages effectively.
 
+
 * [Enqueue and Dequeue, or Produce and Consume](#enqueue-and-dequeue-or-produce-and-consume)
   * [Queues](#queues)
   * [Topics](#topics)
@@ -19,6 +20,7 @@ This section explains message operations using queues, topics, and different pro
 * [Message Expiry and Exception Queues](#message-expiry-and-exception-queues)
 * [Message Delay](#message-delay)
 * [Message Priority](#message-priority)
+* [Transactional Messaging: Combine Messaging with Database Queries](#transactional-messaging-combine-messaging-with-database-queries)
 
 ### Enqueue and Dequeue, or Produce and Consume
 
@@ -159,7 +161,7 @@ public class SampleProducer<T> implements Runnable, AutoCloseable {
 
 The following Java snippet creates an org.oracle.okafka.clients.consumer.KafkaConsumer instance capable of records from Transactional Event Queue topics. Note the use of Oracle Database connection properties, and Kafka consumer-specific properties like `group.id` and `max.poll.records`.
 
-The org.oracle.okafka.clients.consumer.KafkaConsume class implements the org.apache.kafka.clients.consumer.Consumer interface, allowing it to be used in place of a Kafka Java client consumer.
+The org.oracle.okafka.clients.consumer.KafkaConsumer class implements the org.apache.kafka.clients.consumer.Consumer interface, allowing it to be used in place of a Kafka Java client consumer.
 
 ```java
 Properties props = new Properties();
@@ -181,7 +183,7 @@ props.put("value.deserializer", "org.apache.kafka.common.serialization.StringDes
 Consumer<String, String> okafkaConsumer = new KafkaConsumer<>(props);
 ```
 
-The following Java class consumes messages to a topic, using the [Kafka Java Client for Oracle Database Transactional Event Queues](https://github.com/oracle/okafka). Like the producer example, the consumer only does not use any Oracle classes, only Kafka interfaces.
+The following Java class consumes messages from a topic, using the [Kafka Java Client for Oracle Database Transactional Event Queues](https://github.com/oracle/okafka). Like the producer example, the consumer only does not use any Oracle classes, only Kafka interfaces.
 
 
 ```java
@@ -253,7 +255,7 @@ ConnectionFactory cf = AQjmsFactory.getConnectionFactory(ds);
 try (Connection conn = cf.createConnection()) {
     Session session = conn.createSession();
     Queue myQueue = session.createQueue("my_queue");
-    MessageConsumer consumer = session.createConsumer(queue);
+    MessageConsumer consumer = session.createConsumer(myQueue);
     conn.start();
     Message msg = consumer.receive(10000); // Wait for 10 seconds
     if (msg != null && msg instanceof TextMessage) {
@@ -336,7 +338,7 @@ begin
     message := sys.aq$_jms_text_message.construct();
     message.set_text('this is my message');
 
-    message_properties.delay := 7*24*60*60; -- Delay for 1 week
+    message_properties.delay := 7*24*60*60; -- Delay for 7 days
     dbms_aq.enqueue(
             queue_name => 'my_queue',
             enqueue_options => enqueue_options,
@@ -376,4 +378,58 @@ begin
     commit;
 end;
 /
-```
+```
+
+### Transactional Messaging: Combine Messaging with Database Queries
+
+Enqueue and dequeue operations occur within database transactions, allowing developers to combine database DML with messaging operations. This is particularly useful when the message contains data relevant to other tables or services within your schema.
+
+In the following example, a DML operation (an `INSERT` query) is combined with an enqueue operation in the same transaction. If the enqueue operation fails, the `INSERT` is rolled back. The orders table serves as the example.
+
+```sql
+create table orders (
+    id number generated always as identity primary key,
+    product_id number not null,
+    quantity number not null,
+    order_date date default sysdate
+);
+
+declare
+    enqueue_options dbms_aq.enqueue_options_t;
+    message_properties dbms_aq.message_properties_t;
+    msg_id raw(16);
+    message json;
+    body varchar2(200) := '{"product_id": 1, "quantity": 5}';
+    product_id number;
+    quantity number;
+begin
+    -- Convert the JSON string to a JSON object
+    message := json(body);
+
+    -- Extract product_id and quantity from the JSON object
+    product_id := json_value(message, '$.product_id' returning number);
+    quantity := json_value(message, '$.quantity' returning number);
+
+    -- Insert data into the orders table
+    insert into orders (product_id, quantity)
+        values (product_id, quantity);
+
+    -- Enqueue the message
+    dbms_aq.enqueue(
+            queue_name => 'json_queue',
+            enqueue_options => enqueue_options,
+            message_properties => message_properties,
+            payload => message,
+            msgid => msg_id
+    );
+    commit;
+exception
+    when others then
+        -- Rollback the transaction on error
+        rollback;
+        dbms_output.put_line('error dequeuing message: ' || sqlerrm);
+end;
+/
+```
+
+> Note: The same pattern applies to the `dbms_aq.dequeue` procedure, allowing developers to perform DML operations within dequeue transactions.