TxEventQ Chapters (#992)

Signed-off-by: Anders Swanson <[email protected]>

Author: anders-swanson

docs-source/cloudbank/content/_index.md

@@ -22,7 +22,7 @@ To complete the modules you will somewhere to run Oracle Backend for Microservic
 
 Regardless of which option you choose, the remainder of the modules will be virtually identical.  
 
-You will need a Java SDK and either Maven or Gradle to build your applicaitons. An IDE is not strictly required,
+You will need a Java SDK and either Maven or Gradle to build your applications. An IDE is not strictly required,
 but you will have a better overall experience if you use one.  We recommend Visual Studio Code or IntelliJ.
 
 ### Modules

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

@@ -3,7 +3,7 @@ archetype = "home"
 title = "Transactional Event Queues"
 +++
 
-[Oracle Transactional Event Queues (TxEventQ)]() 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.
+[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.
 
@@ -25,7 +25,7 @@ Key features of Oracle Database Transactional Event Queues include:
 
 4. Retention of messages for a specified time after consumption by subscribers.
 
-5. Capability to query of message queues and their metadata by standard SQL.
+5. Capability to query message queues and their metadata by standard SQL.
 
 6. Transactional outbox support: This simplifies event-driven application development for microservices.
 
@@ -36,4 +36,4 @@ Oracle Database Transactional Event Queues are free to use with Oracle Database
 Citations:
 1. [Oracle Database Transactional Event Queues homepage](https://www.oracle.com/database/advanced-queuing/)
 2. [Transactional Event Queue Documentation for Oracle Database 23ai](https://docs.oracle.com/en/database/oracle/oracle-database/23/adque/aq-introduction.html)
-2. [Kafka Java Client for Oracle Database Transactional Event Queues](https://github.com/oracle/okafka)
+3. [Kafka Java Client for Oracle Database Transactional Event Queues](https://github.com/oracle/okafka)

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

@@ -0,0 +1,15 @@
++++
+archetype = "chapter"
+title = "Migrating From AQ"
+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.
+
+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:
+
+- Scaling up existing AQ-based applications
+- Modernizing legacy messaging systems
+- Improving performance for high-volume event processing

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

@@ -0,0 +1,29 @@
++++
+archetype = "chapter"
+title = "Getting Started"
+weight = 1
++++
+
+Oracle Database Transactional Event Queues (TxEventQ) is a high-performance messaging platform built into Oracle Database, designed for application workflows, microservices, and event-driven architectures. This guide will provide you with a thorough understanding of Oracle Database Transactional Event Queues, enabling you to leverage its powerful features for building robust, scalable, and event-driven applications.
+
+This module will cover the following key topics:
+
+## Core Concepts
+- Enqueue/Dequeue vs. Publish/Subscribe models
+- Queues, topics, and Dead Letter Queues (DLQ)
+- Payload types: RAW, 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
+
+## Message Operations
+- Producing and consuming messages
+- Implementing message selectors and rules
+- Handling message delay, expiration, and priority
+
+## 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/kafka/_index.md

@@ -0,0 +1,48 @@
++++
+archetype = "chapter"
+title = "Kafka APIs"
+weight = 2
++++
+
+Oracle Database Transactional Event Queues (TxEventQ) offers comprehensive integration with Apache Kafka, providing developers with a powerful and flexible messaging platform. This module explores the synergy between TxEventQ and Kafka, covering essential concepts and practical implementations. In this module, we'll refer to _queues_ as _topics_ when working with TxEventQ and Kafka.
+
+Throughout this module, we'll explore practical examples using Java code and SQLcl commands to demonstrate:
+
+- Creating and managing topics using Kafka APIs with TxEventQ
+- Producing and consuming messages using Kafka client libraries
+- Implementing transactional messaging with database operations
+- Utilizing Kafka REST APIs for TxEventQ message handling
+- Configuring and using Kafka connectors for TxEventQ
+
+By the end of this module, you'll have a comprehensive understanding of how to leverage Oracle TxEventQ's Kafka compatibility features to build robust, scalable, and event-driven applications.
+
+## Kafka and TxEventQ Concepts
+
+TxEventQ and Kafka share several common architectural concepts, making it easier for developers familiar with Kafka to work with TxEventQ. Key concepts include:
+
+- Topics: Logical channels for message streams
+- Partitions: Subdivisions of topics for parallel processing
+- Offsets: Unique identifiers for messages within a partition
+- Hashing keys: Deterministic message routing within partitions
+- Brokers: Oracle Database servers hosting topics and partitions
+- Ordering: TxEventQ maintains message ordering within partitions, similar to Kafka. Developers can implement partition-level subscribers to ensure ordered message processing.
+
+## Developing with Kafka APIs on TxEventQ
+
+TxEventQ supports Kafka Java APIs through the [Kafka Java Client for Oracle Database Transactional Event Queues](https://github.com/oracle/okafka), allowing developers to leverage existing Kafka knowledge developing against TxEventQ. Key operations include:
+
+- Authenticating to Oracle Database with Kafka APIs
+- Creating topics and partitions using Kafka Admin
+- Producing messages to topics with Kafka Producers
+- Consuming messages from topics using Kafka Consumers
+
+## Kafka Connectors
+
+Oracle offers a Kafka connector for TxeventQ, enabling seamless integration of messages from both platforms. These connectors allow:
+
+- Syncing messages from Kafka topics to TxEventQ queues
+- Sourcing messages from TxEventQ for consumption by Kafka clients
+
+## Transactional Messaging
+
+One of TxEventQ's unique features is its ability to combine messaging and database operations within a single transaction. This capability, often referred to as the "transactional outbox" pattern, ensures data consistency across microservices. We'll explore this pattern through the Kafka Java Client for Oracle Database Transactional Event Queues.

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

@@ -0,0 +1,21 @@
++++
+archetype = "chapter"
+title = "Performance and Observability"
+weight = 4
++++
+
+Oracle TxEventQ offers powerful performance tuning and monitoring capabilities. This module explores advanced techniques for optimizing queue performance and enhancing observability.
+
+## TxEventQ Metrics
+
+TxEventQ provides several comprehensive views for monitoring performance, including insights to message cache statistics, partition level metrics, and subscriber load. This module will dive into accessing and understanding these database views and their content.
+
+## Oracle Database Metrics Exporter
+
+[The Oracle Database Metrics Exporter](https://github.com/oracle/oracle-db-appdev-monitoring) can be configured to export metrics about TxEventQ, providing access to the real-time broker, producer, and consumer metrics in a Grafana dashboard that allows teams to receiving alerts for issues and understand the state of their system.
+
+## Performance Tuning
+
+This module will cover several methods of optimizing TxEventQ performance, including the message cache, streams pool size, and more. Additionally, we'll look at how cross-instance message forwarding, or what happens when you enqueue and dequeue messages across multiple Oracle Database instances.
+
+By leveraging these techniques, you can ensure optimal performance and visibility for your TxEventQ implementations.

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

@@ -0,0 +1,23 @@
++++
+archetype = "chapter"
+title = "Spring Boot Integration"
+weight = 3
++++
+
+Oracle Transactional Event Queues (TxEventQ) features several Spring Boot integrations, allowing application developers to work with TxEventQ using common Spring idioms and starters. This module explores the various integration points and best practices for leveraging TxEventQ within the Spring ecosystem.
+
+## Spring Boot Starter for AQ/JMS
+
+The Oracle Spring Boot Starter for AQ/JMS simplifies TxEventQ integration with Spring and JMS. Key features include:
+
+- Automatic configuration of JMS ConnectionFactory
+- Support for transactional message processing
+- Easy setup with Maven or Gradle dependencies
+
+## Spring Boot Starter for Kafka Java Client for Oracle Database Transactional Event Queues
+
+The Kafka Java Client for TxEventQ Spring Boot Starter pulls in all necessary dependencies to work with TxEventQ's [Kafka Java API](https://github.com/oracle/okafka) using Spring Boot.
+
+## TxEventQ Spring Cloud Stream Binder
+
+[Spring Cloud Stream](https://spring.io/projects/spring-cloud-stream) is a Java framework designed for building event-driven microservices backed by a scalable, fault-tolerant messaging systems. The [Oracle Database Transactional Event Queues (TxEventQ) stream binder](https://github.com/oracle/spring-cloud-oracle/tree/main/database/spring-cloud-stream-binder-oracle-txeventq) implementation allows developers to leverage Oracle’s database messaging platform within the Spring Cloud Stream ecosystem, all while keeping your data within the converged database.