Skip to content

KAFKA-20341: Clarify return semantics of assignment(), subscription(), and metrics() in consumer Javadoc #21849

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
chia7712 merged 3 commits into from
Mar 24, 2026
Merged

KAFKA-20341: Clarify return semantics of assignment(), subscription(), and metrics() in consumer Javadoc #21849

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
cbea116
KAFKA-20341
DL1231 Mar 20, 2026
0ab09f9
Merge branch 'trunk' into KAFKA-20341
DL1231 Mar 23, 2026
71ea443
fix comment
DL1231 Mar 23, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions clients/src/main/java/org/apache/kafka/clients/admin/KafkaAdminClient.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3865,6 +3865,14 @@ public DeleteShareGroupsResult deleteShareGroups(Collection<String> groupIds, De
.collect(Collectors.toMap(entry -> entry.getKey().idValue, Map.Entry::getValue)));
}

/**
* Get the metrics kept by the admin client.
*
* <p>The returned map is an unmodifiable live view of the metrics. Changes to the underlying
* metrics will be reflected in the returned map.
*
* @return An unmodifiable live view of the map of metrics currently maintained by the admin client
*/
@Override
public Map<MetricName, ? extends Metric> metrics() {
return Collections.unmodifiableMap(this.metrics.metrics());
Expand Down
19 changes: 16 additions & 3 deletions clients/src/main/java/org/apache/kafka/clients/consumer/KafkaConsumer.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -643,7 +643,11 @@ public KafkaConsumer(Map<String, Object> configs,
* were assigned. If topic subscription was used, then this will give the set of topic partitions currently assigned
* to the consumer (which may be none if the assignment hasn't happened yet, or the partitions are in the
* process of getting reassigned).
* @return The set of partitions currently assigned to this consumer
*
* <p>The returned set is a snapshot of the current assignment at the time of the call. It will not be updated
* if the assignment changes afterward.
*
* @return An immutable snapshot of the set of partitions currently assigned to this consumer
*/
public Set<TopicPartition> assignment() {
return delegate.assignment();
Expand All @@ -652,7 +656,11 @@ public Set<TopicPartition> assignment() {
/**
* Get the current subscription. Will return the same topics used in the most recent call to
* {@link #subscribe(Collection, ConsumerRebalanceListener)}, or an empty set if no such call has been made.
* @return The set of topics currently subscribed to
*
* <p>The returned set is a snapshot of the current subscription at the time of the call. It will not be updated
* if the subscription changes afterward.
*
* @return An immutable snapshot of the set of topics currently subscribed to
*/
public Set<String> subscription() {
return delegate.subscription();
Expand Down Expand Up @@ -1398,8 +1406,13 @@ public Uuid clientInstanceId(Duration timeout) {
return delegate.clientInstanceId(timeout);
}

/**
/**
* Get the metrics kept by the consumer
Copy link
Copy Markdown
Contributor

@nileshkumar3 nileshkumar3 Mar 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit:indentation issue

Copy link
Copy Markdown
Collaborator Author

@DL1231 DL1231 Mar 23, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The indentation issue pre-exists this PR, but happy to fix it while we're here.

*
* <p>The returned map is an unmodifiable live view of the metrics. Changes to the underlying
* metrics will be reflected in the returned map.
*
* @return An unmodifiable live view of the map of metrics currently maintained by the consumer
Copy link
Copy Markdown
Member

@chia7712 chia7712 Mar 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For the sake of consistency, could we apply these excellent javadocs to Admin and Producer too?

Copy link
Copy Markdown
Collaborator Author

@DL1231 DL1231 Mar 23, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done.

*/
@Override
public Map<MetricName, ? extends Metric> metrics() {
Expand Down
10 changes: 9 additions & 1 deletion clients/src/main/java/org/apache/kafka/clients/consumer/KafkaShareConsumer.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -490,7 +490,10 @@ public KafkaShareConsumer(Map<String, Object> configs,
* Get the current subscription. Will return the same topics used in the most recent call to
* {@link #subscribe(Collection)}, or an empty set if no such call has been made.
*
* @return The set of topics currently subscribed to
* <p>The returned set is a snapshot of the current subscription at the time of the call. It will not be updated
* if the subscription changes afterward.
*
* @return An immutable snapshot of the set of topics currently subscribed to
*/
@Override
public Set<String> subscription() {
Expand Down Expand Up @@ -732,6 +735,11 @@ public Optional<Integer> acquisitionLockTimeoutMs() {

/**
* Get the metrics kept by the consumer
*
* <p>The returned map is an unmodifiable live view of the metrics. Changes to the underlying
* metrics will be reflected in the returned map.
*
* @return An unmodifiable live view of the map of metrics currently maintained by the consumer
Comment thread
DL1231 marked this conversation as resolved.
*/
@Override
public Map<MetricName, ? extends Metric> metrics() {
Expand Down
5 changes: 5 additions & 0 deletions clients/src/main/java/org/apache/kafka/clients/producer/KafkaProducer.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1375,6 +1375,11 @@ public List<PartitionInfo> partitionsFor(String topic) {

/**
* Get the full set of internal metrics maintained by the producer.
*
* <p>The returned map is an unmodifiable live view of the metrics. Changes to the underlying
* metrics will be reflected in the returned map.
*
* @return An unmodifiable live view of the map of metrics currently maintained by the producer
*/
@Override
public Map<MetricName, ? extends Metric> metrics() {
Expand Down
Loading