TxEventQ Spring Docs (#1019)

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

Author: anders-swanson

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

@@ -15,7 +15,6 @@ This section explains message operations using queues, topics, and different pro
     * [Kafka Consumer](#kafka-consumer)
   * [Enqueuing and Dequeuing with JMS](#enqueuing-and-dequeuing-with-jms)
     * [JMS APIs](#jms-apis)
-    * [Spring JMS](#spring-jms)
     * [Message Operations in Other Languages and APIs](#message-operations-in-other-languages-and-apis)
 * [Message Expiry and Exception Queues](#message-expiry-and-exception-queues)
 * [Message Delay](#message-delay)
@@ -264,82 +263,6 @@ try (Connection conn = cf.createConnection()) {
 }
 ```
 
-##### Spring JMS
-
-To configure Spring JMS to use Oracle Database Transactional Event Queues, you'll need to ensure your Spring datasource configuration is setup for Oracle Database:
-
-```yaml
-spring:
-  datasource:
-    username: ${USERNAME}
-    password: ${PASSWORD}
-    url: ${JDBC_URL}
-
-    # Set these to use UCP over Hikari.
-    driver-class-name: oracle.jdbc.OracleDriver
-    type: oracle.ucp.jdbc.PoolDataSourceImpl
-    oracleucp:
-      initial-pool-size: 1
-      min-pool-size: 1
-      max-pool-size: 30
-      connection-pool-name: UCPSampleApplication
-      connection-factory-class-name: oracle.jdbc.pool.OracleDataSource
-```
-
-Additionally, you should define a JMS ConnectionFactory bean using the AQjmsFactory class. The presence of the ConnectionFactory bean ensures Spring JMS uses Oracle Database Transactional Event Queues as the JMS provider for message operations.
-
-```java
-@Bean
-public ConnectionFactory aqJmsConnectionFactory(DataSource ds) throws JMSException {
-    return AQjmsFactory.getConnectionFactory(ds);
-}
-```
-
-The following Spring JMS Producer class makes use of Spring’s JMSTemplate, which is available via autowiring. The JMSTemplate class provides a simple API for working with JMS — here we use the convertAndSend method to produce messages to a queue.
-
-The JMSTemplate class provides a variety of JMS functionality, and may also be used to receive messages.
-
-```java
-import org.springframework.beans.factory.annotation.Value;
-import org.springframework.jms.core.JmsTemplate;
-import org.springframework.stereotype.Component;
-
-@Component
-public class Producer {
-    private final JmsTemplate jmsTemplate;
-    private final String queueName;
-
-    public Producer(JmsTemplate jmsTemplate,
-                    @Value("${txeventq.queue.name:testqueue}") String queueName) {
-        this.jmsTemplate = jmsTemplate;
-        this.queueName = queueName;
-    }
-
-    public void enqueue(String message) {
-        jmsTemplate.convertAndSend(queueName, message);
-    }
-}
-```
-
-The following Spring JMS Consumer class uses Spring’s @JmsListener annotation to set up a message receiver for a given queue — in this case, a queue named “testqueue”. The basic consumer prints each message it receives to stdout.
-
-```java
-import java.util.concurrent.CountDownLatch;
-
-import org.springframework.beans.factory.annotation.Value;
-import org.springframework.jms.annotation.JmsListener;
-import org.springframework.stereotype.Component;
-
-@Component
-public class Consumer {
-    
-    @JmsListener(destination = "${txeventq.queue.name:testqueue}", id = "sampleConsumer")
-    public void receiveMessage(String message) {
-        System.out.printf("Received message: %s%n", message);
-    }
-}
-```
-
 ##### Message Operations in Other Languages and APIs
 
 For Python, Javascript, .NET, and ORDS, refer to the respective documentation for code samples:

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

@@ -46,3 +46,7 @@ Oracle offers a Kafka connector for TxeventQ, enabling seamless integration of m
 ## 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.
+
+## Spring Boot Integration
+
+Spring Boot integration is supported through the [Kafka Java Client for Oracle Database Transactional Event Queues' Spring Boot Starter](https://central.sonatype.com/artifact/com.oracle.database.spring/oracle-spring-boot-starter-okafka). You can read more about the starter in the [Spring Boot Kafka section](../spring-boot/kafka.md).

docs-source/transactional-event-queues/content/kafka/kafka-connectors.md

@@ -4,7 +4,7 @@ title = "Kafka Connectors"
 weight = 3
 +++
 
-This section provides examples using Kafka connectors to connect Oracle Database Transactional Event Queues with other data and messaging systems, like [Apache Kafka](https://github.com/oracle/okafka/tree/master/connectors).
+This section introduces Kafka connectors to connect Oracle Database Transactional Event Queues with other data and messaging systems, like [Apache Kafka](https://github.com/oracle/okafka/tree/master/connectors) topics.
 
 ## Kafka Connectors
 

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

@@ -16,7 +16,7 @@ The Oracle Spring Boot Starter for AQ/JMS simplifies TxEventQ integration with S
 
 ## 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.
+The Kafka Java Client for Oracle Database Transactional Event Queues Spring Boot Starter pulls in all necessary dependencies to work with Transactional Event Queues [Kafka Java API](https://github.com/oracle/okafka) using Spring Boot.
 
 ## TxEventQ Spring Cloud Stream Binder
 

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

@@ -3,3 +3,144 @@ archetype = "page"
 title = "Spring JMS"
 weight = 1
 +++
+
+Java Message Service (JMS) is an API that provides a standardized way for Java applications to create, send, receive, and read messages in messaging systems. [Spring JMS](https://spring.io/guides/gs/messaging-jms) uses idiomatic APIs to produce and consume messages with JMS, using the JMSTemplate class and @JMSListener annotations for producers and consumers, respectively.
+
+In this section, we’ll implement a producer/consumer example using Spring JMS with Oracle Database Transactional Event Queues JMS APIs.
+
+* [Project Dependencies](#project-dependencies)
+* [Configure Permissions and Create a JMS Queue](#configure-permissions-and-create-a-jms-queue)
+* [Connect Spring JMS to Oracle Database](#connect-spring-jms-to-oracle-database)
+* [JMSTemplate Producer](#jmstemplate-producer)
+* [Receive messages with @JMSListener](#receive-messages-with-jmslistener)
+
+## Project Dependencies
+
+To start developing with the Spring JMS for Oracle Database Transactional Event Queues, add the [oracle-spring-boot-starter-aqjms](https://central.sonatype.com/artifact/com.oracle.database.spring/oracle-spring-boot-starter-aqjms) dependency to your Maven project, along with Spring Boot JDBC:
+
+```xml
+<dependency>
+    <groupId>org.springframework.boot</groupId>
+    <artifactId>spring-boot-starter-data-jdbc</artifactId>
+    <version>${spring-boot.version}</version>
+</dependency>
+<dependency>
+    <groupId>com.oracle.database.spring</groupId>
+    <artifactId>oracle-spring-boot-starter-aqjms</artifactId>
+    <version>${oracle-database-starters.version}</version>
+</dependency>
+```
+
+For Gradle users, add the following dependency to your project:
+
+```groovy
+implementation "org.springframework.boot:spring-boot-starter-data-jdbc:${springBootVersion}"
+implementation "com.oracle.database.spring:oracle-spring-boot-starter-aqjms:${oracleDatabaseStartersVersion}"
+```
+
+## Configure Permissions and Create a JMS Queue
+
+The following SQL script grants the necessary permissions to use Transactional Event Queues with JMS to a database user, and then creates a Transactional Event Queue with a [JMS Payload Type](../getting-started/core-concepts.md#dbms_aqadmjms_type) for use by that user. We’ll dynamically invoke this script in our test later on, and it is provided here for reference purposes.
+
+```sql
+grant aq_user_role to testuser;
+grant execute on dbms_aq to testuser;
+grant execute on dbms_aqadm to testuser;
+grant execute ON dbms_aqin TO testuser;
+grant execute ON dbms_aqjms TO testuser;
+grant execute on dbms_teqk to testuser;
+
+begin
+    -- Create a JMS queue
+    dbms_aqadm.create_transactional_event_queue(
+            queue_name         => 'testuser.testqueue',
+            queue_payload_type => DBMS_AQADM.JMS_TYPE,
+        -- FALSE means queues can only have one consumer for each message. This is the default.
+        -- TRUE means queues created in the table can have multiple consumers for each message.
+            multiple_consumers => false
+    );
+
+    -- Start the queue
+    dbms_aqadm.start_queue(
+            queue_name         => 'testuser.testqueue'
+    );
+end;
+/
+```
+
+## Connect Spring JMS to Oracle Database
+
+Spring JMS with Oracle Database Transactional Event Queues uses a standard Oracle Database JDBC connection to produce and consume messages. To configure this with YAML-style Spring datasource properties, it'll look something like this (`src/main/resources/application.yaml`):
+
+```yaml
+spring:
+  datasource:
+    username: ${USERNAME}
+    password: ${PASSWORD}
+    url: ${JDBC_URL}
+
+    driver-class-name: oracle.jdbc.OracleDriver
+    type: oracle.ucp.jdbc.PoolDataSourceImpl
+    oracleucp:
+      initial-pool-size: 1
+      min-pool-size: 1
+      max-pool-size: 30
+      connection-pool-name: UCPSampleApplication
+      connection-factory-class-name: oracle.jdbc.pool.OracleDataSource
+```
+
+Additionally, you should define a JMS ConnectionFactory bean using the AQjmsFactory class. The presence of the ConnectionFactory bean ensures Spring JMS uses Oracle Database Transactional Event Queues as the JMS provider for message operations.
+
+```java
+@Bean
+public ConnectionFactory aqJmsConnectionFactory(DataSource ds) throws JMSException {
+    return AQjmsFactory.getConnectionFactory(ds);
+}
+```
+
+## JMSTemplate Producer
+
+The Spring JMSTemplate bean provides an interface for JMS operations, including producing and consuming messages. The following class uses the `jmsTemplate.convertAndSend()` method to produce a message to a queue.
+
+```java
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.jms.core.JmsTemplate;
+import org.springframework.stereotype.Component;
+
+@Component
+public class Producer {
+    private final JmsTemplate jmsTemplate;
+    private final String queueName;
+
+    public Producer(JmsTemplate jmsTemplate,
+                    @Value("${txeventq.queue.name:testqueue}") String queueName) {
+        this.jmsTemplate = jmsTemplate;
+        this.queueName = queueName;
+    }
+
+    public void enqueue(String message) {
+        jmsTemplate.convertAndSend(queueName, message);
+    }
+}
+```
+
+## Receive messages with @JMSListener
+
+The `@JMSListener` annotation may be applied to a method to configure a receiver for messages from a JMS queue. 
+
+The following class uses the @JMSListener annotation to read messages from a queue named `testqueue`, printing each message to stdout.
+
+```java
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.jms.annotation.JmsListener;
+import org.springframework.stereotype.Component;
+
+@Component
+public class Consumer {
+    
+    @JmsListener(destination = "${txeventq.queue.name:testqueue}", id = "sampleConsumer")
+    public void receiveMessage(String message) {
+        System.out.printf("Received message: %s%n", message);
+    }
+}
+```

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

@@ -3,3 +3,112 @@ archetype = "page"
 title = "Kafka Starter"
 weight = 2
 +++
+
+This section provides information on getting started using the Kafka Java Client for Oracle Database Transactional Event Queues from a Spring Boot application.
+
+You can learn more about the Kafka APIs of Oracle Database Transactional Event Queues in the [Kafka chapter](../kafka/_index.md).
+
+## Project Dependencies
+
+[The Kafka Java Client for Oracle Database Transactional Event Queues Spring Boot Starter](https://central.sonatype.com/artifact/com.oracle.database.spring/oracle-spring-boot-starter-okafka) pulls in all necessary dependencies for developers to work with Transactional Event Queues' Kafka Java API using Spring Boot.
+
+If you're using Maven, add the following dependency to your project:
+
+```xml
+<dependency>
+    <groupId>com.oracle.database.spring</groupId>
+    <artifactId>oracle-spring-boot-starter-okafka</artifactId>
+    <version>${oracle-database-starters.version}</version>
+</dependency>
+```
+
+Or, if you're using Gradle:
+
+```groovy
+implementation 'com.oracle.database.spring:oracle-spring-boot-starter-okafka:${oracleDatabaseStartersVersion}'
+```
+
+## Configuring the Starter
+
+We'll create a simple Spring Configuration class that pulls in properties for configuring the Kafka Java Client for Oracle Database Transactional Event Queues. You can read more about these configuration properties in the [Developing With Kafka APIs](../kafka/developing-with-kafka.md) section.
+
+```java
+@Configuration
+public class OKafkaConfiguration {
+    public static final String TOPIC_NAME = "OKAFKA_SAMPLE";
+
+    @Value("${ojdbc.path}")
+    private String ojdbcPath;
+
+    @Value("${bootstrap.servers}")
+    private String bootstrapServers;
+
+    // We use the default 23ai Free service name
+    @Value("${service.name:freepdb1}")
+    private String serviceName;
+
+    // We use plaintext for a containerized, local database.
+    // Use SSL for wallet connections, like Autonomous Database.
+    @Value("${security.protocol:PLAINTEXT}")
+    private String securityProtocol;
+
+    @Bean
+    @Qualifier("okafkaProperties")
+    public Properties kafkaProperties() {
+        return OKafkaUtil.getConnectionProperties(ojdbcPath,
+                bootstrapServers,
+                securityProtocol,
+                serviceName);
+    }
+}
+```
+
+### Configuring a Producer Bean
+
+We can now configure a sample producer bean using the org.oracle.okafka.clients.producer.KafkaProducer class:
+
+```java
+@Bean
+@Qualifier("sampleProducer")
+public Producer<String, String> sampleProducer() throws IOException {
+    // Create the OKafka Producer.
+    Properties props = kafkaProperties();
+    props.put("enable.idempotence", "true");
+    props.put("key.serializer", "org.apache.kafka.common.serialization.StringSerializer");
+    props.put("value.serializer", "org.apache.kafka.common.serialization.StringSerializer");
+    // Note the use of the org.oracle.okafka.clients.producer.KafkaProducer class, for Oracle TxEventQ.
+    return new KafkaProducer<String, String>(props);
+}
+```
+
+The Producer bean can be autowired into Spring components to write messages to Oracle Database Transactional Event Queue topics.. For a complete example of writing data to topics, see [Producing messages to Kafka Topics](../kafka/developing-with-kafka.md#producing-messages).
+
+### Configuring a Consumer Bean
+
+Next, we'll configure a sample consumer bean using the org.oracle.okafka.clients.consumer.KafkaConsumer class:
+
+```java
+@Bean
+@Qualifier("sampleConsumer")
+public Consumer<String, String> sampleConsumer() {
+    // Create the OKafka Consumer.
+    Properties props = kafkaProperties();
+    props.put("group.id" , "MY_CONSUMER_GROUP");
+    props.put("enable.auto.commit","false");
+    props.put("max.poll.records", 2000);
+    props.put("key.deserializer", "org.apache.kafka.common.serialization.StringDeserializer");
+    props.put("value.deserializer", "org.apache.kafka.common.serialization.StringDeserializer");
+    props.put("auto.offset.reset", "earliest");
+    // Note the use of the org.oracle.okafka.clients.consumer.KafkaConsumer class, for Oracle TxEventQ.
+    return new KafkaConsumer<>(props);
+}
+```
+
+The Consumer bean can be autowired into Spring components to poll messages from Oracle Database Transactional Event Queue topics. For a complete consumer example, see [Consuming messages from Kafka topics](../kafka/developing-with-kafka.md#consuming-messages).
+
+## Sample Application Code
+
+The following samples provide application code using the Spring starter.
+
+- [Oracle Spring Boot Sample for JSON Events and the Kafka Java Client for Oracle Database Transactional Event Queues](https://github.com/oracle/spring-cloud-oracle/tree/main/database/starters/oracle-spring-boot-starter-samples/oracle-spring-boot-sample-json-events)
+- [Oracle Spring Boot Sample for the Kafka Java Client for Oracle Database Transactional Event Queues](https://github.com/oracle/spring-cloud-oracle/tree/main/database/starters/oracle-spring-boot-starter-samples/oracle-spring-boot-sample-okafka)