Merge pull request #1031 from oracle/txeventq-edits

TxEventQ Edits

Author: anders-swanson

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

@@ -6,7 +6,7 @@ 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.
+Advanced Queuing (AQ) has been Oracle’s database 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.
 

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

@@ -47,7 +47,7 @@ The migration tool interface provides the following functionalities:
 4. Once the AQ is drained or purged, the DBMS_AQMIGTOOL.COMMIT_MIGRATION procedure drops the AQ and renames the interim TxEventQ to the AQ's name, ensuring application compatibility.
    1. If using DBMS_AQMIGTOOL.AUTOMATIC migration mode, commit is not required.
 
-In the event of an error the prevents migration from continuing, AQ migration may be cancelled and the in-flight messages restored to the AQ without data loss.
+In the event of an error that prevents migration from continuing, AQ migration may be cancelled and the in-flight messages restored to the AQ without data loss.
 
 ### Checking Compatibility
 
@@ -71,7 +71,7 @@ If the output is similar to "Migration report unsupported events count: 0", then
 
 The [INIT_MIGRATION](https://docs.oracle.com/en/database/oracle/oracle-database/23/arpls/DBMS_AQMIGTOOL.html#GUID-4D2A3314-9ADF-43DE-9201-74A8F9DB03FE) procedure is used to begin AQ migration to TxEventQ. The `mig_mode` parameter is used to control the migration type and defaults to `DBMS_AQMIGTOOL.INTERACTIVE` which allows both enqueue and dequeue during migration. A full description of `mig_mode` options is available in the procedure documentation.
 
-The following SQL script starts migration for the AQ `my_queue` in the `testuser` schema. Once migration starts, an interim TxEventQ will be created named `my_queue_m` the includes a copy of the existing AQ configuration.
+The following SQL script starts migration for the AQ `my_queue` in the `testuser` schema. Once migration starts, an interim TxEventQ will be created named `my_queue_m` that includes a copy of the existing AQ configuration.
 
 ```sql
 begin
@@ -186,7 +186,7 @@ end;
 /
 ```
 
-The [RECOVER_MIGRATION](https://docs.oracle.com/en/database/oracle/oracle-database/23/arpls/DBMS_AQMIGTOOL.html#GUID-755EEB52-BFAE-4FEA-A933-07546D72DD98) procedure can be used to restore a migration to the nearest safe point, either before or after the execution of DBMS_AQMIGTOOL.CANCEL_MIGRATION, DBMS_AQMIGTOOL.COMMIT_MIGRATION, or DBMS_AQMIGTOOL.INIT_MIGRATION.
+The [RECOVER_MIGRATION](https://docs.oracle.com/en/database/oracle/oracle-database/23/arpls/DBMS_AQMIGTOOL.html#GUID-755EEB52-BFAE-4FEA-A933-07546D72DD98) procedure can be used to restore a migration to the nearest safe point, either before or after the execution of DBMS_AQMIGTOOL.CANCEL_MIGRATION, DBMS_AQMIGTOOL.COMMIT_MIGRATION, or DBMS_AQMIGTOOL.INIT_MIGRATION. You may wish to use the RECOVER_MIGRATION procedure if an unexpected error has occurred, or the use of an unsupported feature is detected in the [USER_TXEVENTQ_MIGRATION_STATUS](https://docs.oracle.com/en/database/oracle/oracle-database/23/refrn/USER_TXEVENTQ_MIGRATION_STATUS.html#REFRN-GUID-07BAF678-A893-4616-B559-E78E90EE1972) view.
 
 The following SQL script recovers migration to the nearest safe point, and outputs the recovery message:
 
@@ -209,11 +209,11 @@ end;
 The following features are unsupported in TxEventQ, and should be mitigated before migration:
 
 - Queue Retry Delay: Set `retry_delay` to zero using DBMS_AQADM.ALTER_QUEUE.
-- Message transactions on enqueue/dequeue: Move the transformation to the application layer.
+- Message transaction on enqueue/dequeue: Move the transformation to the application layer.
 - Multi-queue listeners: Implement single queue listening with dequeue browse.
 - Priority values outside the range 0-9: Adjust priority values to the range 0-9.
 
-The following features do support migration. Applications using these features must be modified before migration:
+The following features do not support migration. Applications using these features must be modified before migration:
 
 - Message grouping.
 - Sequence deviation and relative message id.

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

@@ -16,6 +16,6 @@ TxEventQ provides [administrative views](https://docs.oracle.com/en/database/ora
 
 ## Performance Tuning
 
-This module will cover several methods of optimizing TxEventQ performance, including the message cache, streams pool size, and more.
+This module will cover several methods of optimizing TxEventQ performance, including the message cache, Streams pool size, and more.
 
 By leveraging these techniques, you can ensure optimal performance and visibility for your TxEventQ implementations.

docs-source/transactional-event-queues/content/observability/tuning.md

@@ -7,7 +7,7 @@ weight = 3
 Performance tuning is critical for ensuring the efficiency, reliability, and responsiveness of TxEventQ event processing. As systems scale and the volume of events increases, poor optimizations can lead to latency, bottlenecks, or even system failures. By applying the techniques described in this section, TxEventQ administrators can significantly enhance throughput, reduce latency, and improve the stability of event driven applications.
 
 
-* [Partitioning/Sharding and Multiple Consumers](#partitioningsharding-and-multiple-consumers)
+* [Event Streams and Multiple Consumers](#event-streams-and-multiple-consumers)
   * [Creating a Partitioned Kafka Topic](#creating-a-partitioned-kafka-topic)
   * [Message Cache Optimization](#message-cache-optimization)
 * [Tuning System Parameters](#tuning-system-parameters)
@@ -21,30 +21,30 @@ Performance tuning is critical for ensuring the efficiency, reliability, and res
   * [STREAMS_POOL_SIZE](#streams_pool_size)
 
 
-## Partitioning/Sharding and Multiple Consumers
+## Event Streams and Multiple Consumers
 
-Oracle Database automatically manages the database table partitions of a queue. As queue volume fluctuates, partitions may be dynamically created as necessary, for example, when the queue table expands due to a message backlog. Once all messages are dequeued and no longer needed, the database table partition is truncated and made available for reuse.
+Oracle Database automatically manages the database table partitions of a queue. As queue volume fluctuates, table partitions may be dynamically created as necessary, for example, when the queue table expands due to a message backlog. Once all messages are dequeued and no longer needed, the database table partition is truncated and made available for reuse.
 
-Queue partitions (or shards) can be configured on a queue during creation. A higher number of partitions per queue improves dequeue performance through consumer parallelization, but requires additional memory and database resources. When messages are enqueued, each message is routed to a specific partition of the queue. Messages within a partition maintain a strict, session-level ordering.
+Queue event streams can be configured on a queue during creation. A higher number of event streams per queue improves dequeue performance through consumer parallelization, but requires additional memory and database resources. When messages are enqueued, each message is routed to a specific event stream of the queue. Messages within an event stream maintain a strict, session-level ordering.
 
-If you wish to manually set the number of partitions/shards for a queue, you may do so using the [SET_QUEUE_PARAMETER](https://docs.oracle.com/en/database/oracle/oracle-database/23/arpls/DBMS_AQADM.html#GUID-E592137F-BB8E-49A2-80C2-C055358566C9) procedure. The following SQL script creates a queue, and configures it to have 5 partitions/shards and key based enqueue. Key based enqueue allows message routing to a specific shard within a queue by providing a message key at enqueue time.
+If you wish to manually set the number of event streams for a queue, you may do so using the [SET_QUEUE_PARAMETER](https://docs.oracle.com/en/database/oracle/oracle-database/23/arpls/DBMS_AQADM.html#GUID-E592137F-BB8E-49A2-80C2-C055358566C9) procedure. The following SQL script creates a queue, and configures it to have 5 event streams and key based enqueue. Key based enqueue allows message routing to a specific event stream within a queue by providing a message key at enqueue time.
 
 ```sql
 begin
     dbms_aqadm.create_transactional_event_queue(
-            queue_name         => 'partitioned_queue',
+            queue_name         => 'my_queue',
             queue_payload_type => DBMS_AQADM.JMS_TYPE,
             multiple_consumers => true
     );
 
-    -- Set the queue to have 5 partitions/shards
-    dbms_aqadm.set_queue_parameter('partitioned_queue', 'SHARD_NUM', 5);
-    -- The partition/shard for enqueued messages is determined by the message key
-    dbms_aqadm.set_queue_parameter('partitioned_queue', 'KEY_BASED_ENQUEUE', 1);
+    -- Set the queue to have 5 event streams
+    dbms_aqadm.set_queue_parameter('my_queue', 'SHARD_NUM', 5);
+    -- The event stream for enqueued messages is determined by the message key
+    dbms_aqadm.set_queue_parameter('my_queue', 'KEY_BASED_ENQUEUE', 1);
 
     -- Start the queue
     dbms_aqadm.start_queue(
-            queue_name         => 'partitioned_queue'
+            queue_name         => 'my_queue'
     );
 end;
 /
@@ -54,7 +54,7 @@ It is recommended to avoid creating global indexes on the partitioned table that
 
 ### Creating a Partitioned Kafka Topic
 
-The following Java code snippet creates a TxEventQ topic with 5 partitions using the [Kafka Java Client for Oracle Database Transactional Event Queues](https://github.com/oracle/okafka). The `my_topic` topic may have up to 5 distinct consumer threads per consumer group, increasing parallelization.
+The following Java code snippet creates a TxEventQ topic with 5 Kafka partitions (5 TxEventQ event streams) using the [Kafka Java Client for Oracle Database Transactional Event Queues](https://github.com/oracle/okafka). When working with TxEventQ, we'll refer to Kafka topic partitions as event streams. The `my_topic` topic may have up to 5 distinct consumer threads per consumer group, increasing parallelization.
 
 ```java
 Properties props = // Oracle Database connection properties
@@ -72,7 +72,7 @@ Note that you can use as many producers per topic as required, though it is reco
 
 ### Message Cache Optimization
 
-TxEventQ includes a specialized message cache that allows administrators to balance [System Global Area (SGA)](https://docs.oracle.com/en/database/oracle/oracle-database/23/dbiad/db_sga.html) usage and queue performance. Management of TxEventQ's SGA usage benefits throughput, reduces latency, and allows greater concurrency. When paired with partitioning, message caching reduces the need for certain queries, DML operations, and indexes. The cache is most effective when consumers can keep up with producers, and when it is large enough to store the messages (including payloads) for all consumers and producers for using TxEventQ.
+TxEventQ includes a specialized message cache that allows administrators to balance [System Global Area (SGA)](https://docs.oracle.com/en/database/oracle/oracle-database/23/dbiad/db_sga.html) usage and queue performance. Management of TxEventQ's SGA usage benefits throughput, reduces latency, and allows greater concurrency. When paired with event streams, message caching reduces the need for certain queries, DML operations, and indexes. The cache is most effective when consumers can keep up with producers, and when it is large enough to store the messages (including payloads) for all consumers and producers for using TxEventQ.
 
 The message cache uses the Oracle Database Streams pool. You can fine-tune the memory allocation for the Streams pool using the DBMS_AQADM [SET_MIN_STREAMS_POOL](https://docs.oracle.com/en/database/oracle/oracle-database/23/arpls/DBMS_AQADM.html#GUID-773FA544-1450-4A9E-BAA7-08ACF059D3EB) and [SET_MAX_STREAMS_POOL](https://docs.oracle.com/en/database/oracle/oracle-database/23/arpls/DBMS_AQADM.html#GUID-9375E6C8-1BC0-4E45-8045-143927DD751C) procedures.
 
@@ -103,10 +103,6 @@ where  name = 'sga_target';
 
 The default block size of 8k is recommended. The block size of a database cannot be changed after database creation.
 
-### [JAVA_POOL_SIZE](https://docs.oracle.com/en/database/oracle/oracle-database/23/refrn/JAVA_POOL_SIZE.html)
-
-The JAVA_POOL_SIZE parameter specifies the size (in bytes) of the Java pool, used by the Java memory manager for Java-related operations like method and class definitions, and Java objects during execution. If the SGA_TARGET is not set, it defaults to 24 MB. JAVA_POOL_SIZE is modifiable via ALTER SYSTEM, and its range depends on the operating system.
-
 ### [OPEN_CURSORS](https://docs.oracle.com/en/database/oracle/oracle-database/23/refrn/OPEN_CURSORS.html)
 
 The OPEN_CURSORS parameter defines the maximum number of open cursors a session can have in Oracle. The default value is 50, and it can be adjusted between 0 and 65535. If you are running a large amount of producers and consumers, it’s essential to set this value high enough to avoid running out of cursors. You can modify OPEN_CURSORS using the ALTER SYSTEM command.
@@ -127,7 +123,7 @@ The SESSIONS parameter defines the maximum number of sessions that can be create
 
 ### [SGA_TARGET](https://docs.oracle.com/en/database/oracle/oracle-database/23/refrn/SGA_TARGET.html)
 
-The SGA_TARGET parameter specifies the total size of the Shared Global Area (SGA) in Oracle, allowing automatic memory management of its components like the buffer cache, shared pool, and others. Its value can range from 64 MB to SGA_MAX_SIZE. It is modifiable via ALTER SYSTEM. If set to zero, SGA autotuning is disabled. Systems that make heavy using of message queueing should configure SGA_TARGET to an appropriately large value to get the most out of queue [message caching](#message-cache).
+The SGA_TARGET parameter specifies the total size of the System Global Area (SGA) in Oracle, allowing automatic memory management of its components like the buffer cache, shared pool, and others. Its value can range from 64 MB to SGA_MAX_SIZE. It is modifiable via ALTER SYSTEM. If set to zero, SGA autotuning is disabled. Systems that make heavy using of message queuing should configure SGA_TARGET to an appropriately large value to get the most out of queue [message caching](#message-cache-optimization).
 
 If SGA_TARGET is specified, then the following memory pools are automatically sized:
 - Buffer cache (DB_CACHE_SIZE)
@@ -141,4 +137,4 @@ If SGA_TARGET is specified, then the following memory pools are automatically si
 
 The STREAMS_POOL_SIZE parameter defines the size of the Streams pool, a shared memory area used for TxEventQ and other database features. If SGA_TARGET and STREAMS_POOL_SIZE are both nonzero, Oracle Database Automatic Shared Memory Management uses this value as a minimum for the Streams pool. 
 
-If both the STREAMS_POOL_SIZE and the SGA_TARGET parameters are set to 0, then the first request for Streams pool memory will transfer 10% of the buffer cache shared pool is transferred to the Streams pool.
+If both the STREAMS_POOL_SIZE and the SGA_TARGET parameters are set to 0, then the first request for Streams pool memory will transfer 10% of the buffer cache shared pool to the Streams pool.

docs-source/transactional-event-queues/content/observability/views.md

@@ -50,7 +50,7 @@ The `V$EQ_NONDUR_SUBSCRIBER` view provides details about non-durable subscriptio
 
 ### [V$EQ_NONDUR_SUBSCRIBER_LWM](https://docs.oracle.com/en/database/oracle/oracle-database/23/refrn/V-EQ_NONDUR_SUBSCRIBER_LWM.html#REFRN-GUID-98D91CB7-5EA3-47EB-90D3-A8BF0047D3B8)
 
-The V$EQ_NONDUR_SUBSCRIBER_LWM view provides information about the low watermarks (LWMs) of non-durable subscribers in a Transactional Event Queue (TxEventQ). The LWM represents the lowest point in an event stream partition that a non-durable subscriber has processed.
+The V$EQ_NONDUR_SUBSCRIBER_LWM view provides information about the low watermarks (LWMs) of non-durable subscribers in a Transactional Event Queue (TxEventQ). The LWM of a subscriber represents a position within an event stream below which none of the messages are of interest to the subscriber.
 
 ### [V$EQ_PARTITION_STATS](https://docs.oracle.com/en/database/oracle/oracle-database/23/refrn/V-EQ_PARTITION_STATS.html#REFRN-GUID-4EA74E81-4664-436E-B58A-0857DDBD81F7)