(kafka) branch 4.1 updated: MINOR: Improve ProcessorContext JavaDocs (#20042)

[mj...@apache.org]

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

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


The following commit(s) were added to refs/heads/4.1 by this push:
     new adfcc9ed3f6 MINOR: Improve ProcessorContext JavaDocs (#20042)
adfcc9ed3f6 is described below

commit adfcc9ed3f695bf69ce55adaf8b3eb5e0845a6c5
Author: Matthias J. Sax <ma...@confluent.io>
AuthorDate: Thu Jun 26 10:06:46 2025 -0700

    MINOR: Improve ProcessorContext JavaDocs (#20042)
    
    Clarify that state stores are sharded, and shards cannot be shared
    across Processors.
    
    Reviewers: Lucas Brutschy <lb...@confluent.io>
---
 .../java/org/apache/kafka/streams/processor/ProcessorContext.java  | 7 +++++++
 .../org/apache/kafka/streams/processor/api/ProcessingContext.java  | 6 ++++++
 2 files changed, 13 insertions(+)

diff --git a/streams/src/main/java/org/apache/kafka/streams/processor/ProcessorContext.java b/streams/src/main/java/org/apache/kafka/streams/processor/ProcessorContext.java
index d65244bcc86..45ab411d62e 100644
--- a/streams/src/main/java/org/apache/kafka/streams/processor/ProcessorContext.java
+++ b/streams/src/main/java/org/apache/kafka/streams/processor/ProcessorContext.java
@@ -105,6 +105,13 @@ public interface ProcessorContext {
     /**
      * Get the state store given the store name.
      *
+     * <p>The returned state store represent one shard of the overall state, which belongs to the current task.
+     * The returned shard of the state store may only be used by the current
+     * {@link org.apache.kafka.streams.kstream.Transformer}, {@link org.apache.kafka.streams.kstream.ValueTransformer},
+     * or {@link org.apache.kafka.streams.kstream.ValueTransformerWithKey} instance.
+     * Sharing a shard across different transformers (ie, from different "sibling" tasks; same sub-topology but different
+     * partition) may lead to data corruption and/or data loss.
+     *
      * @param name The store name
      * @param <S> The type or interface of the store to return
      * @return The state store instance
diff --git a/streams/src/main/java/org/apache/kafka/streams/processor/api/ProcessingContext.java b/streams/src/main/java/org/apache/kafka/streams/processor/api/ProcessingContext.java
index 78aa2c8489b..7f6874c8c19 100644
--- a/streams/src/main/java/org/apache/kafka/streams/processor/api/ProcessingContext.java
+++ b/streams/src/main/java/org/apache/kafka/streams/processor/api/ProcessingContext.java
@@ -107,6 +107,12 @@ public interface ProcessingContext {
     /**
      * Get the state store given the store name.
      *
+     * <p>The returned state store represent one shard of the overall state, which belongs to the current task.
+     * The returned shard of the state store may only be used by the current {@link Processor} or
+     * {@link FixedKeyProcessor} instance.
+     * Sharing a shard across different processors (ie, from different "sibling" tasks; same sub-topology but different
+     * partition) may lead to data corruption and/or data loss.
+     *
      * @param name The store name
      * @param <S> The type or interface of the store to return
      * @return The state store instance