Merge pull request #1044 from oracle/txeventq-docs-update

TxEventQ docs update

Author: anders-swanson

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

@@ -18,7 +18,7 @@ Messages can be propagated within the same database or across a [database link](
 
 #### Queue to Queue Message Propagation
 
-Create and start two queues. `source` will be the source queue, and `dest` will be the propagated destination queue. 
+Create and start two queues. `source` will be the source queue, and `dest` will be the propagated destination queue. Note that `multiple_consumers` _must_ be `true` during queue creation to enable propagation.
 
 ```sql
 begin
@@ -63,6 +63,8 @@ declare
     message json;
     body varchar2(200) := '{"content": "this message is propagated!"}';
 begin
+    enqueue_options := dbms_aq.enqueue_options_t();
+    message_properties := dbms_aq.message_properties_t();
     select json(body) into message;
     dbms_aq.enqueue(
         queue_name => 'source',
@@ -128,6 +130,8 @@ declare
     message json;
     message_buffer varchar2(500);
 begin
+    dequeue_options := dbms_aq.dequeue_options_t();
+    message_properties := dbms_aq.message_properties_t();
     dequeue_options.navigation := dbms_aq.first_message;
     dequeue_options.wait := dbms_aq.no_wait;
 

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

@@ -16,25 +16,27 @@ This section provides the basic concepts of Transactional Event Queues, includin
 
 ### What are queues and topics?
 
-Queues and topics both provide high-throughput, asynchronous application communication, but have a few key differences that are relevant for developers and architects.
+Queues and topics provide high-throughput, asynchronous application communication, with a few key differences that are relevant for developers and architects.
 
 When using queues, messages follow a send/receive model that allows exactly one consumer. Once the message is consumed, it is discarded after a configurable interval. In contrast, topics may have multiple consumers for each message, and the message is persisted for as long as specified.
 
-Queues work best for applications that expect to dequeue messages to a single consumer. If you plan to broadcast messages to multiple consumers, or require message replay, you should use topics. In general, topics provide greater flexibility for event-streaming applications due to the ability of consumers to independently consume or replay messages, and the database's capability of persisting the message for a specified duration.
+Queues work best for applications that only need to dequeue messages with a single consumer. If you plan to broadcast messages to multiple consumers, require message replay, or need consumer parallelism, you should use topics. In general, topics provide greater flexibility for event-streaming applications due to the ability of consumers to independently consume or replay messages, and the database's capability of persisting the message for a specified duration.
 
-The following SQL script uses the `DBMS_AQADM.CREATE_TRANSACTIONAL_EVENT_QUEUE` procedure to create a topic by setting the `multiple_consumers` parameter to `true`. You can find the full parameter definition for the [`DBMS_AQADM.CREATE_TRANSACTIONAL_EVENT_QUEUE` procedure here](https://docs.oracle.com/en/database/oracle/oracle-database/23/arpls/DBMS_AQADM.html#GUID-93B0FF90-5045-4437-A9C4-B7541BEBE573).
+The following SQL script uses the [`DBMS_AQADM.CREATE_TRANSACTIONAL_EVENT_QUEUE` procedure](https://docs.oracle.com/en/database/oracle/oracle-database/23/arpls/DBMS_AQADM.html#GUID-6841A667-1021-4E5C-8567-F71913AA4773) to create a topic by setting the `multiple_consumers` parameter to `true`. If the `multiple_consumers` parameter is set to `false`, the created object will have queue semantics instead.
+
+You can find the full parameter definition for the [`DBMS_AQADM.CREATE_TRANSACTIONAL_EVENT_QUEUE` procedure here](https://docs.oracle.com/en/database/oracle/oracle-database/23/arpls/DBMS_AQADM.html#GUID-93B0FF90-5045-4437-A9C4-B7541BEBE573).
 
 ```sql
 begin
     dbms_aqadm.create_transactional_event_queue(
-            queue_name         => 'my_queue',
+            queue_name         => 'my_topic',
             queue_payload_type => DBMS_AQADM.JMS_TYPE,
             multiple_consumers => true
     );
 
     -- Start the queue
     dbms_aqadm.start_queue(
-            queue_name         => 'my_queue'
+            queue_name         => 'my_topic'
     );
 end;
 /

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

@@ -46,6 +46,8 @@ declare
     message json;
     body varchar2(200) := '{"content": "my first message"}';
 begin
+    enqueue_options := dbms_aq.enqueue_options_t();
+    message_properties := dbms_aq.message_properties_t();
     select json(body) into message;
     dbms_aq.enqueue(
         queue_name => 'json_queue',
@@ -69,6 +71,8 @@ declare
     message json;
     message_buffer varchar2(500);
 begin
+    dequeue_options := dbms_aq.dequeue_options_t();
+    message_properties := dbms_aq.message_properties_t();
     dequeue_options.navigation := dbms_aq.first_message;
     dequeue_options.wait := dbms_aq.no_wait;
 
@@ -307,6 +311,8 @@ declare
     message_handle raw(16);
     message sys.aq$_jms_text_message;
 begin
+    enqueue_options := dbms_aq.enqueue_options_t();
+    message_properties := dbms_aq.message_properties_t();
     message := sys.aq$_jms_text_message.construct();
     message.set_text('this is my message');
 
@@ -336,6 +342,8 @@ declare
     message_handle raw(16);
     message sys.aq$_jms_text_message;
 begin
+    enqueue_options := dbms_aq.enqueue_options_t();
+    message_properties := dbms_aq.message_properties_t();
     message := sys.aq$_jms_text_message.construct();
     message.set_text('this is my message');
 
@@ -365,6 +373,8 @@ declare
     message_handle raw(16);
     message sys.aq$_jms_text_message;
 begin
+    enqueue_options := dbms_aq.enqueue_options_t();
+    message_properties := dbms_aq.message_properties_t();
     message := sys.aq$_jms_text_message.construct();
     message.set_text('this is my message');
 
@@ -404,6 +414,8 @@ declare
     product_id number;
     quantity number;
 begin
+    enqueue_options := dbms_aq.enqueue_options_t();
+    message_properties := dbms_aq.message_properties_t();
     -- Convert the JSON string to a JSON object
     message := json(body);
 

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

@@ -98,17 +98,6 @@ end;
 /
 ```
 
-The `DBMS_AQADM.PURGE_QUEUE` procedure is used to clear messages from a queue.
-
-```sql
-begin
-    dbms_aqadm.purge_queue(
-        queue_name => 'my_queue'
-    );
-end;
-/
-```
-
 Use the [`DBMS_AQADM.STOP_QUEUE` procedure](https://docs.oracle.com/en/database/oracle/oracle-database/23/arpls/DBMS_AQADM.html#GUID-14EADFE9-D7C3-472D-895D-861BB5570EED) to stop a queue. A queue must be stopped before it can be dropped using the [`DBMS_AQADM.DROP_TRANSACTIONAL_EVENT_QUEUE` procedure](https://docs.oracle.com/en/database/oracle/oracle-database/23/arpls/DBMS_AQADM.html#GUID-99A161DB-85C7-439A-A85C-A7BEEBD0288F).
 
 ```sql
@@ -137,12 +126,9 @@ You should see queue data similar to the following, for the queues available on
 | CUSTOM_TYPE_QUEUE| CUSTOM_TYPE_QUEUE| 72535 | NORMAL_QUEUE   | 5           | 0           | YES             | YES             | 0         | null         | null         | TRUE    | Transactional Event Queue | SINGLE    |
 | MY_QUEUE         | MY_QUEUE         | 73283 | NORMAL_QUEUE   | 5           | 0           | YES             | YES             | 0         | null         | null         | TRUE    | Transactional Event Queue | SINGLE    |
 
-
-
-
 #### Kafka APIs
 
-You can use standard Kafka APIs to create a topic with the [Kafka Java Client for Oracle Database Transactional Event Queues](https://github.com/oracle/okafka). The following code configures connection properties for Oracle Database and creates a topic using the [`org.oracle.okafka.clients.admin.AdminClient` class](https://mvnrepository.com/artifact/com.oracle.database.messaging/okafka), which implements the `org.apache.kafka.clients.admin.Admin` interface.
+Using standard Kafka Java APIs, we can create a topic with the [Kafka Java Client for Oracle Database Transactional Event Queues](https://github.com/oracle/okafka). The following code configures connection properties for Oracle Database, and creates a topic using the [`org.oracle.okafka.clients.admin.AdminClient` class](https://mvnrepository.com/artifact/com.oracle.database.messaging/okafka). This class implements the Apache Kafka `org.apache.kafka.clients.admin.Admin` interface for API compatibility.
 
 ```java
 // Oracle Database Connection properties