Update consumer and producer docs

Author: loicgreffier

kafka-consumer-quickstarts/kafka-consumer-avro-generic/README.md

@@ -1,16 +1,14 @@
 # Consumer Avro Generic
 
-This module demonstrates the following:
-
-- The use of the Kafka Clients consumer API.
-- The use of Apache Avro and generic records.
-- Unit testing using a Mock consumer.
-
 This module consumes records of type `<String, GenericRecord>` from a topic named `USER_TOPIC`.
+It demonstrates the following:
+- Use of the Kafka Clients consumer API
+- Use of Apache Avro and generic records
+- Unit testing with a mock consumer
 
 ## Prerequisites
 
-To compile and run this demo, you will need the following:
+To compile and run this demo, you’ll need:
 
 - Java 21
 - Maven
@@ -21,7 +19,7 @@ To compile and run this demo, you will need the following:
 To run the application manually:
 
 - Start a [Confluent Platform](https://docs.confluent.io/platform/current/quickstart/ce-docker-quickstart.html#step-1-download-and-start-cp) in a Docker environment.
-- Produce records of type `<String, GenericRecord>` to a topic named `USER_TOPIC`. You can use the [producer Avro Generic](../../kafka-producer-quickstarts/kafka-producer-avro-generic) to do this.
+- Produce records of type `<String, GenericRecord>` to the `USER_TOPIC`. You can use the [producer Avro Generic](../../kafka-producer-quickstarts/kafka-producer-avro-generic) for this.
 - Start the consumer.
 
 To run the application in Docker, use the following command:
@@ -30,10 +28,10 @@ To run the application in Docker, use the following command:
 docker-compose up -d
 ```
 
-This command will start the following services in Docker:
+This command starts the following services in Docker:
 
 - 1 Kafka broker (KRaft mode)
-- 1 Schema registry
+- 1 Schema Registry
 - 1 Control Center
-- 1 producer Avro Generic
-- 1 consumer Avro Generic
+- 1 Producer Avro Generic
+- 1 Consumer Avro Generic

kafka-consumer-quickstarts/kafka-consumer-avro-generic/src/main/java/io/github/loicgreffier/consumer/avro/generic/app/ConsumerRunner.java

@@ -50,9 +50,10 @@ public ConsumerRunner(Consumer<String, GenericRecord> consumer) {
     }
 
     /**
-     * Asynchronously starts the Kafka consumer when the application is ready. The asynchronous annotation is used to
-     * run the consumer in a separate thread and not block the main thread. The Kafka consumer processes generic Avro
-     * records from the USER_TOPIC topic, so it does not require to know the schema of the records.
+     * Asynchronously starts the Kafka consumer once the application is ready. The {@code @Async} annotation ensures
+     * that the consumer runs in a separate thread, preventing the main thread from being blocked. The Kafka consumer
+     * processes generic Avro records from the USER_TOPIC topic, so it does not require to know the schema of the
+     * records.
      */
     @Async
     @EventListener(ApplicationReadyEvent.class)

kafka-consumer-quickstarts/kafka-consumer-avro-specific/README.md

@@ -1,16 +1,14 @@
 # Consumer Avro Specific
 
-This module demonstrates the following:
-
-- The use of the Kafka Clients consumer API.
-- The use of Apache Avro and specific records.
-- Unit testing using a Mock consumer.
-
 This module consumes records of type `<String, KafkaUser>` from a topic named `USER_TOPIC`.
+It demonstrates the following:
+- Use of the Kafka Clients consumer API
+- Use of Apache Avro and specific records
+- Unit testing with a mock consumer
 
 ## Prerequisites
 
-To compile and run this demo, you will need the following:
+To compile and run this demo, you’ll need:
 
 - Java 21
 - Maven
@@ -21,7 +19,7 @@ To compile and run this demo, you will need the following:
 To run the application manually:
 
 - Start a [Confluent Platform](https://docs.confluent.io/platform/current/quickstart/ce-docker-quickstart.html#step-1-download-and-start-cp) in a Docker environment.
-- Produce records of type `<String, KafkaUser>` to a topic named `USER_TOPIC`. You can use the [producer Avro Specific](../../kafka-producer-quickstarts/kafka-producer-avro-specific) to do this.
+- Produce records of type `<String, KafkaUser>` to the `USER_TOPIC`. You can use the [producer Avro Specific](../../kafka-producer-quickstarts/kafka-producer-avro-specific) for this.
 - Start the consumer.
 
 To run the application in Docker, use the following command:
@@ -30,10 +28,10 @@ To run the application in Docker, use the following command:
 docker-compose up -d
 ```
 
-This command will start the following services in Docker:
+This command starts the following services in Docker:
 
 - 1 Kafka broker (KRaft mode)
-- 1 Schema registry
+- 1 Schema Registry
 - 1 Control Center
-- 1 producer Avro Specific
-- 1 consumer Avro Specific
+- 1 Producer Avro Specific
+- 1 Consumer Avro Specific

kafka-consumer-quickstarts/kafka-consumer-avro-specific/src/main/java/io/github/loicgreffier/consumer/avro/specific/app/ConsumerRunner.java

@@ -50,9 +50,9 @@ public ConsumerRunner(Consumer<String, KafkaUser> consumer) {
     }
 
     /**
-     * Asynchronously starts the Kafka consumer when the application is ready. The asynchronous annotation is used to
-     * run the consumer in a separate thread and not block the main thread. The Kafka consumer processes specific Avro
-     * records from the USER_TOPIC topic.
+     * Asynchronously starts the Kafka consumer once the application is ready. The {@code @Async} annotation ensures
+     * that the consumer runs in a separate thread, preventing the main thread from being blocked. The Kafka consumer
+     * processes specific Avro records from the USER_TOPIC topic.
      */
     @Async
     @EventListener(ApplicationReadyEvent.class)

kafka-consumer-quickstarts/kafka-consumer-circuit-breaker/README.md

@@ -1,22 +1,15 @@
 # Consumer Circuit Breaker
 
-This module demonstrates the following:
-
-- The use of the Kafka Clients consumer API.
-- The use of Apache Avro
-- Unit testing using a Mock consumer.
-
-This module performs the following tasks:
-
-- Consume records of type `<String, KafkaUser>` from a topic named `USER_TOPIC`.
-- Handle deserialization exceptions and seek the poison pill.
-- If a poison pill is found in the middle of a batch of good records, the `poll()` method will return the good records
-  in the first loop and then throw the deserialization exception in the second loop.
-- To ensure no good records are lost, the module seeks to the next offset.
+This module consumes records of type `<String, KafkaUser>` from a topic named `USER_TOPIC`, handling deserialization exceptions.
+It demonstrates the following:
+- Use of the Kafka Clients consumer API
+- How to handle poison pills in a Kafka consumer
+- Use of Apache Avro
+- Unit testing with a mock consumer
 
 ## Prerequisites
 
-To compile and run this demo, you will need the following:
+To compile and run this demo, you’ll need:
 
 - Java 21
 - Maven
@@ -27,10 +20,10 @@ To compile and run this demo, you will need the following:
 To run the application manually:
 
 - Start a [Confluent Platform](https://docs.confluent.io/platform/current/quickstart/ce-docker-quickstart.html#step-1-download-and-start-cp) in a Docker environment.
-- Produce records of type `<String, KafkaUser>` to a topic named `USER_TOPIC`. You can use the [producer Avro Specific](../../kafka-producer-quickstarts/kafka-producer-avro-specific) to do this.
-- Make sure a deserialization exception will occur by either:
-    - Deleting the Avro schema from the schema registry.
-    - Producing a String message in the middle of Avro messages.
+- Produce records of type `<String, KafkaUser>` to the `USER_TOPIC`. You can use the [producer Avro Specific](../../kafka-producer-quickstarts/kafka-producer-avro-specific) for this.
+- Ensure a deserialization exception will occur by either:
+    - Deleting the Avro schema from the schema registry
+    - Producing a String message in the middle of Avro messages
 - Start the consumer.
 
 To run the application in Docker, use the following command:
@@ -39,10 +32,10 @@ To run the application in Docker, use the following command:
 docker-compose up -d
 ```
 
-This command will start the following services in Docker:
+This command starts the following services in Docker:
 
 - 1 Kafka broker (KRaft mode)
-- 1 Schema registry
+- 1 Schema Registry
 - 1 Control Center
-- 1 producer Avro Specific
-- 1 Circuit Breaker consumer
+- 1 Producer Avro Specific
+- 1 Circuit Breaker Consumer

kafka-consumer-quickstarts/kafka-consumer-circuit-breaker/src/main/java/io/github/loicgreffier/consumer/circuit/breaker/app/ConsumerRunner.java

@@ -51,10 +51,12 @@ public ConsumerRunner(Consumer<String, KafkaUser> consumer) {
     }
 
     /**
-     * Asynchronously starts the Kafka consumer when the application is ready. The asynchronous annotation is used to
-     * run the consumer in a separate thread and not block the main thread. The Kafka consumer processes messages from
-     * the USER_TOPIC topic and handles deserialization errors. When a deserialization error occurs, the consumer seeks
-     * to the next offset in order to skip the record that caused the error.
+     * Asynchronously starts the Kafka consumer once the application is ready. The {@code @Async} annotation ensures
+     * that the consumer runs in a separate thread, preventing the main thread from being blocked. The Kafka consumer
+     * processes messages from the USER_TOPIC topic and handles deserialization errors. When a deserialization error
+     * occurs, the consumer skips the problematic record by seeking to the next offset. Note that if a deserialization
+     * error occurs in the middle of a batch, the poll operation * will still return the valid records, throw the
+     * deserialization exception, and continue with the rest of the batch.
      */
     @Async
     @EventListener(ApplicationReadyEvent.class)

kafka-consumer-quickstarts/kafka-consumer-headers/README.md

@@ -1,16 +1,14 @@
 # Consumer Headers
 
-This module demonstrates the following:
-
-- The use of the Kafka Clients consumer API.
-- The use of headers in Kafka records.
-- Unit testing using a Mock consumer.
-
 This module consumes records of type `<String, String>` with headers from a topic named `STRING_TOPIC`.
+It demonstrates the following:
+- Use of the Kafka Clients consumer API
+- Use of headers in Kafka records
+- Unit testing with a mock consumer
 
 ## Prerequisites
 
-To compile and run this demo, you will need the following:
+To compile and run this demo, you’ll need:
 
 - Java 21
 - Maven
@@ -21,7 +19,7 @@ To compile and run this demo, you will need the following:
 To run the application manually:
 
 - Start a [Confluent Platform](https://docs.confluent.io/platform/current/quickstart/ce-docker-quickstart.html#step-1-download-and-start-cp) in a Docker environment.
-- Produce records of type `<String, String>` with headers named `id` and `message` to a topic named `STRING_TOPIC`. You can use the [producer headers](../../kafka-producer-quickstarts/kafka-producer-headers) to do this.
+- Produce records of type `<String, String>` with a header named `message` to the `STRING_TOPIC`. You can use the [producer Headers](../../kafka-producer-quickstarts/kafka-producer-headers) for this.
 - Start the consumer.
 
 To run the application in Docker, use the following command:
@@ -30,9 +28,9 @@ To run the application in Docker, use the following command:
 docker-compose up -d
 ```
 
-This command will start the following services in Docker:
+This command starts the following services in Docker:
 
 - 1 Kafka broker (KRaft mode)
 - 1 Control Center
-- 1 producer Headers
-- 1 consumer Headers
+- 1 Producer Headers
+- 1 Consumer Headers

kafka-consumer-quickstarts/kafka-consumer-headers/src/main/java/io/github/loicgreffier/consumer/headers/app/ConsumerRunner.java

@@ -51,9 +51,9 @@ public ConsumerRunner(Consumer<String, String> consumer) {
     }
 
     /**
-     * Asynchronously starts the Kafka consumer when the application is ready. The asynchronous annotation is used to
-     * run the consumer in a separate thread and not block the main thread. The Kafka consumer processes string records
-     * with headers from the STRING_TOPIC topic.
+     * Asynchronously starts the Kafka consumer once the application is ready. The {@code @Async} annotation ensures
+     * that the consumer runs in a separate thread, preventing the main thread from being blocked. The Kafka consumer
+     * processes string records with headers from the STRING_TOPIC topic.
      */
     @Async
     @EventListener(ApplicationReadyEvent.class)

kafka-consumer-quickstarts/kafka-consumer-retry-external-system/README.md

@@ -1,20 +1,13 @@
 # Consumer Retry External System
 
-This module demonstrates the following:
-
-- The use of the Kafka Clients consumer API.
-- Unit testing using a Mock consumer.
-
-This module performs the following tasks:
-
-- Consumes records of type `<String, String>` from a topic named `STRING_TOPIC`.
-- Sends the records to a fake external system.
-- Implements a strong retry mechanism to handle failures in the external system. If the call to the external system
-  fails, the module retries the operation using the retry mechanism.
+This module consumes records of type `<String, String>` from a topic named `STRING_TOPIC`, handling failures in an external system and implementing a retry mechanism.
+It demonstrates the following:
+- Use of the Kafka Clients consumer API
+- Unit testing with a mock consumer
 
 ## Prerequisites
 
-To compile and run this demo, you will need the following:
+To compile and run this demo, you’ll need:
 
 - Java 21
 - Maven
@@ -25,7 +18,7 @@ To compile and run this demo, you will need the following:
 To run the application manually:
 
 - Start a [Confluent Platform](https://docs.confluent.io/platform/current/quickstart/ce-docker-quickstart.html#step-1-download-and-start-cp) in a Docker environment.
-- Produce records of type `<String, String>` to a topic named `STRING_TOPIC`. You can use the [producer simple](../../kafka-producer-quickstarts/kafka-producer-simple) to do this.
+- Produce records of type `<String, String>` to the `STRING_TOPIC`. You can use the [producer Simple](../../kafka-producer-quickstarts/kafka-producer-simple) for this.
 - Start the consumer.
 
 To run the application in Docker, use the following command:
@@ -34,9 +27,9 @@ To run the application in Docker, use the following command:
 docker-compose up -d
 ```
 
-This command will start the following services in Docker:
+This command starts the following services in Docker:
 
 - 1 Kafka broker (KRaft mode)
 - 1 Control Center
-- 1 producer Simple
-- 1 consumer Retry External System
+- 1 Producer Simple
+- 1 Consumer Retry External System

kafka-consumer-quickstarts/kafka-consumer-retry-external-system/src/main/java/io/github/loicgreffier/consumer/retry/app/ConsumerRunner.java

@@ -65,14 +65,14 @@ public ConsumerRunner(
     }
 
     /**
-     * Asynchronously starts the Kafka consumer when the application is ready. The asynchronous annotation is used to
-     * run the consumer in a separate thread and not block the main thread. The Kafka consumer processes messages from
-     * the STRING_TOPIC topic. If an error occurs during the external system call, the consumer pauses the
-     * topic-partitions. and rewinds to the failed record offset as a call to poll() has automatically advanced the
-     * consumer offsets. The consumer being paused, it will not commit the offsets and the next call to poll() will not
-     * return any records. Consequently, the consumer will honor the pause duration given by the poll() timeout. Once
-     * the pause duration is elapsed, the consumer will resume the topic-partitions and consume the records from the
-     * failed record offset.
+     * Asynchronously starts the Kafka consumer once the application is ready. The {@code @Async} annotation ensures
+     * that the consumer runs in a separate thread, preventing the main thread from being blocked. The Kafka consumer
+     * processes messages from the STRING_TOPIC topic. If an error occurs during the external system call, the consumer
+     * pauses the topic-partitions. and rewinds to the failed record offset as a call to poll() has automatically
+     * advanced the consumer offsets. The consumer being paused, it will not commit the offsets and the next call to
+     * poll() will not return any records. Consequently, the consumer will honor the pause duration given by the poll()
+     * timeout. Once the pause duration is elapsed, the consumer will resume the topic-partitions and consume the
+     * records from the failed record offset.
      */
     @Async
     @EventListener(ApplicationReadyEvent.class)