(kafka) branch trunk updated: KAFKA-19284 Add documentation to clarify the behavior of null values for all partitionsToOffsetAndMetadata methods. (#19728)

[chia7712]

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

chia7712 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 4eac6adf91a KAFKA-19284 Add documentation to clarify the behavior of 
null values for all partitionsToOffsetAndMetadata methods. (#19728)
4eac6adf91a is described below

commit 4eac6adf91a1516f8862dc5b40ca1dfe46135695
Author: Logan Zhu <loganzh...@outlook.com>
AuthorDate: Sun Jun 1 02:17:47 2025 +0800

    KAFKA-19284 Add documentation to clarify the behavior of null values for 
all partitionsToOffsetAndMetadata methods. (#19728)
    
    Adds missing documentation to the `partitionsToOffsetAndMetadata`
    methods in both `ListStreamsGroupOffsetsResult` and
    `ListShareGroupOffsetsResult` classes to clarify the behavior when a
    group does not have a committed offset for a specific partition.
    
    As document in ListConsumerGroupOffsetsResult: > If the group doesn’t
    have a committed offset for a specific partition, the corresponding
    value in the returned map will be null.
    
    This important detail was previously missing in the JavaDoc of the
    stream and share group variants.
    
    Reviewers: Nick Guo <lansg0...@gmail.com>, Chia-Ping Tsai
     <chia7...@gmail.com>
---
 .../org/apache/kafka/clients/admin/ListShareGroupOffsetsResult.java | 6 ++----
 .../apache/kafka/clients/admin/ListStreamsGroupOffsetsResult.java   | 3 ++-
 2 files changed, 4 insertions(+), 5 deletions(-)

diff --git 
a/clients/src/main/java/org/apache/kafka/clients/admin/ListShareGroupOffsetsResult.java
 
b/clients/src/main/java/org/apache/kafka/clients/admin/ListShareGroupOffsetsResult.java
index e1dcd932309..6fecddc69ef 100644
--- 
a/clients/src/main/java/org/apache/kafka/clients/admin/ListShareGroupOffsetsResult.java
+++ 
b/clients/src/main/java/org/apache/kafka/clients/admin/ListShareGroupOffsetsResult.java
@@ -66,10 +66,8 @@ public class ListShareGroupOffsetsResult {
     }
 
     /**
-     * Return a future which yields a map of topic partitions to offsets for 
the specified group.
-     *
-     * @param groupId The group ID.
-     * @return Future which yields a map of topic partitions to offsets for 
the specified group.
+     * Return a future which yields a map of topic partitions to offsets for 
the specified group. If the group doesn't
+     * have a committed offset for a specific partition, the corresponding 
value in the returned map will be null.
      */
     public KafkaFuture<Map<TopicPartition, OffsetAndMetadata>> 
partitionsToOffsetAndMetadata(String groupId) {
         if (!futures.containsKey(groupId)) {
diff --git 
a/clients/src/main/java/org/apache/kafka/clients/admin/ListStreamsGroupOffsetsResult.java
 
b/clients/src/main/java/org/apache/kafka/clients/admin/ListStreamsGroupOffsetsResult.java
index 3f2ea17e92e..3abf578f71a 100644
--- 
a/clients/src/main/java/org/apache/kafka/clients/admin/ListStreamsGroupOffsetsResult.java
+++ 
b/clients/src/main/java/org/apache/kafka/clients/admin/ListStreamsGroupOffsetsResult.java
@@ -50,7 +50,8 @@ public class ListStreamsGroupOffsetsResult {
     }
 
     /**
-     * Return a future which yields a map of topic partitions to offsets for 
the specified group.
+     * Return a future which yields a map of topic partitions to offsets for 
the specified group. If the group doesn't
+     * have a committed offset for a specific partition, the corresponding 
value in the returned map will be null.
      */
     public KafkaFuture<Map<TopicPartition, OffsetAndMetadata>> 
partitionsToOffsetAndMetadata(String groupId) {
         return delegate.partitionsToOffsetAndMetadata(groupId);