(kafka) branch trunk updated: KAFKA-8666: Improve Documentation on usage of Materialized config object (#17145)

[mj...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

mjsax pushed a commit to branch trunk
in repository https://gitbox.apache.org/repos/asf/kafka.git


The following commit(s) were added to refs/heads/trunk by this push:
     new 30a988a7685 KAFKA-8666: Improve Documentation on usage of Materialized config object (#17145)
30a988a7685 is described below

commit 30a988a7685d6fa6f2343b5232e9a1dbc1a19335
Author: João Pedro Fonseca Dantas <67...@users.noreply.github.com>
AuthorDate: Wed Sep 11 18:15:34 2024 -0300

    KAFKA-8666: Improve Documentation on usage of Materialized config object (#17145)
    
    Reviewers: Matthias J. Sax <ma...@confluent.io>
---
 .../apache/kafka/streams/kstream/Materialized.java | 63 +++++++++++++++++++++-
 1 file changed, 62 insertions(+), 1 deletion(-)

diff --git a/streams/src/main/java/org/apache/kafka/streams/kstream/Materialized.java b/streams/src/main/java/org/apache/kafka/streams/kstream/Materialized.java
index da352ca6b50..b2075022fd9 100644
--- a/streams/src/main/java/org/apache/kafka/streams/kstream/Materialized.java
+++ b/streams/src/main/java/org/apache/kafka/streams/kstream/Materialized.java
@@ -53,6 +53,30 @@ import static org.apache.kafka.streams.internals.ApiUtils.validateMillisecondDur
  *   "topicName",
  *   Materialized.as("queryable-store-name"));
  * }</pre>
+ * <p>
+ * <b>Correct Usage When Providing Serde:</b>
+ * <p>
+ * To configure both the name of the store and the {@link Serde} for the key and value,
+ * you should use the following pattern:
+ * <pre>{@code
+ * Materialized.<KeyType, ValueType, StateStore>as("MyStoreName")
+ *     .withKeySerde(keySerde)
+ *     .withValueSerde(valueSerde);
+ * }</pre>
+ * This ensures that the store name is retained while configuring the key and value serde.
+ * <p>
+ * <b>Warning:</b> If you use the ({@code static}) {@link Materialized#with(Serde, Serde)} method after calling
+ * {@link Materialized#as(String)}, the instance created by {@link Materialized#as(String)} will be replaced by a new
+ * {@link Materialized} instance, and any configuration set on the first instance (e.g., store name, logging settings)
+ * will be lost.
+ * <p>
+ * For example, the following code is incorrect because it discards the configuration of the store name (calling {@code static}) methods on an object/instance is an anti-pattern):
+ * <pre>{@code
+ * // This will not work as expected:
+ * Materialized.<KeyType, ValueType, StateStore>as("MyStoreName")
+ *     .with(keySerde, valueSerde);  // The store name "MyStoreName" is lost
+ * }</pre>
+ * Instead, use the proper pattern of chaining {@code withKeySerde} and {@code withValueSerde}.
  *
  * @param <K> type of record key
  * @param <V> type of record value
@@ -147,6 +171,26 @@ public class Materialized<K, V, S extends StateStore> {
 
     /**
      * Materialize a {@link StateStore} with the given name.
+     * <p>
+     * This method sets the name of the state store to be used during materialization. You can provide additional
+     * configurations like key and value {@link Serde}s using {@link #withKeySerde(Serde)} and
+     * {@link #withValueSerde(Serde)}.
+     * <p>
+     * <b>Warning:</b> Do not use {@link #with(Serde, Serde)} after calling this method, as it creates a new
+     * {@link Materialized} instance, which discards the store name and any other configurations set earlier.
+     * <p>
+     * Correct usage:
+     * <pre>{@code
+     * Materialized.<KeyType, ValueType, StateStore>as("MyStoreName")
+     *     .withKeySerde(keySerde)
+     *     .withValueSerde(valueSerde);
+     * }</pre>
+     * <p>
+     * Incorrect usage (store name is lost):
+     * <pre>{@code
+     * Materialized.<KeyType, ValueType, StateStore>as("MyStoreName")
+     *     .with(keySerde, valueSerde);  // Store name is lost
+     * }</pre>
      *
      * @param storeName  the name of the underlying {@link KTable} state store; valid characters are ASCII
      * alphanumerics, '.', '_' and '-'.
@@ -209,7 +253,24 @@ public class Materialized<K, V, S extends StateStore> {
 
     /**
      * Materialize a {@link StateStore} with the provided key and value {@link Serde}s.
-     * An internal name will be used for the store.
+     * <p>
+     * Note: If this method is used after {@link #as(String)}, the original {@link Materialized} instance will be
+     * replaced with a new instance, and any configuration on the first instance (e.g., store name) will be lost. To
+     * configure both a store name and key/value serde, use {@link #withKeySerde(Serde)} and
+     * {@link #withValueSerde(Serde)} instead.
+     * <p>
+     * Correct usage with {@link Serde}:
+     * <pre>{@code
+     * Materialized.<KeyType, ValueType, StateStore>as("MyStoreName")
+     *     .withKeySerde(keySerde)
+     *     .withValueSerde(valueSerde);
+     * }</pre>
+     * <p>
+     * Incorrect usage (store name will be lost):
+     * <pre>{@code
+     * Materialized.<KeyType, ValueType, StateStore>as("MyStoreName")
+     *     .with(keySerde, valueSerde);  // Store name is lost
+     * }</pre>
      *
      * @param keySerde      the key {@link Serde} to use. If the {@link Serde} is null, then the default key
      *                      serde from configs will be used