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 05185c1ef8a KAFKA-20341 Clarify return semantics of assignment(),
subscription(), and metrics() in consumer Javadoc (#21849)
05185c1ef8a is described below
commit 05185c1ef8a897cc2956601d441dfbab56011352
Author: Lan Ding <[email protected]>
AuthorDate: Tue Mar 24 08:10:57 2026 +0800
KAFKA-20341 Clarify return semantics of assignment(), subscription(), and
metrics() in consumer Javadoc (#21849)
Improves Javadoc to clarify the return semantics of three methods:
- `assignment()` and `subscription()`: return an **immutable
snapshot** at the time of the call. - `metrics()`: returns an
**unmodifiable live view**. The Javadoc now documents this clearly;
the implementation is unchanged from the original behavior.
Reviewers: Nilesh Kumar <[email protected]>, Chia-Ping Tsai
<[email protected]>
---
.../apache/kafka/clients/admin/KafkaAdminClient.java | 8 ++++++++
.../apache/kafka/clients/consumer/KafkaConsumer.java | 19 ++++++++++++++++---
.../kafka/clients/consumer/KafkaShareConsumer.java | 10 +++++++++-
.../apache/kafka/clients/producer/KafkaProducer.java | 5 +++++
4 files changed, 38 insertions(+), 4 deletions(-)
diff --git
a/clients/src/main/java/org/apache/kafka/clients/admin/KafkaAdminClient.java
b/clients/src/main/java/org/apache/kafka/clients/admin/KafkaAdminClient.java
index 85f1e87459f..e1ab4c6929d 100644
--- a/clients/src/main/java/org/apache/kafka/clients/admin/KafkaAdminClient.java
+++ b/clients/src/main/java/org/apache/kafka/clients/admin/KafkaAdminClient.java
@@ -3865,6 +3865,14 @@ public class KafkaAdminClient extends AdminClient {
.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());
diff --git
a/clients/src/main/java/org/apache/kafka/clients/consumer/KafkaConsumer.java
b/clients/src/main/java/org/apache/kafka/clients/consumer/KafkaConsumer.java
index ad179f88e55..201c467cd28 100644
--- a/clients/src/main/java/org/apache/kafka/clients/consumer/KafkaConsumer.java
+++ b/clients/src/main/java/org/apache/kafka/clients/consumer/KafkaConsumer.java
@@ -643,7 +643,11 @@ public class KafkaConsumer<K, V> implements Consumer<K, V>
{
* 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();
@@ -652,7 +656,11 @@ public class KafkaConsumer<K, V> implements Consumer<K, V>
{
/**
* 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();
@@ -1398,8 +1406,13 @@ public class KafkaConsumer<K, V> implements Consumer<K,
V> {
return delegate.clientInstanceId(timeout);
}
- /**
+ /**
* 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
*/
@Override
public Map<MetricName, ? extends Metric> metrics() {
diff --git
a/clients/src/main/java/org/apache/kafka/clients/consumer/KafkaShareConsumer.java
b/clients/src/main/java/org/apache/kafka/clients/consumer/KafkaShareConsumer.java
index 75e2b27cdd9..c26a9e97f16 100644
---
a/clients/src/main/java/org/apache/kafka/clients/consumer/KafkaShareConsumer.java
+++
b/clients/src/main/java/org/apache/kafka/clients/consumer/KafkaShareConsumer.java
@@ -490,7 +490,10 @@ public class KafkaShareConsumer<K, V> implements
ShareConsumer<K, V> {
* 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() {
@@ -732,6 +735,11 @@ public class KafkaShareConsumer<K, V> implements
ShareConsumer<K, V> {
/**
* 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
*/
@Override
public Map<MetricName, ? extends Metric> metrics() {
diff --git
a/clients/src/main/java/org/apache/kafka/clients/producer/KafkaProducer.java
b/clients/src/main/java/org/apache/kafka/clients/producer/KafkaProducer.java
index 31a9f6b945c..2702ad52921 100644
--- a/clients/src/main/java/org/apache/kafka/clients/producer/KafkaProducer.java
+++ b/clients/src/main/java/org/apache/kafka/clients/producer/KafkaProducer.java
@@ -1375,6 +1375,11 @@ public class KafkaProducer<K, V> implements Producer<K,
V> {
/**
* 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() {
