This is an automated email from the ASF dual-hosted git repository.
schofielaj 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 70e7cddb9d9 KAFKA-20137: Add javadoc to public APIs in
org.apache.kafka.clients.producer (#21445)
70e7cddb9d9 is described below
commit 70e7cddb9d9cd5df9290f2c7a0c7bf9708d753eb
Author: zoo-code <[email protected]>
AuthorDate: Wed Feb 18 20:30:11 2026 +0900
KAFKA-20137: Add javadoc to public APIs in
org.apache.kafka.clients.producer (#21445)
## Summary
This PR adds missing Javadocs to public APIs within the
`org.apache.kafka.clients.producer` package to improve documentation
coverage and consistency with project standards.
## Changes
Added missing Javadocs to public classes, methods, and fields in 4 files
- BufferExhaustedException
- PreparedTxnState
- MockProducer
- ProducerConfig
## Test Plan
- No functional changes, documentation only
- Verified that Javadoc formatting follows existing Kafka conventions
Reviewers: Andrew Schofield <[email protected]>
---
.../clients/producer/BufferExhaustedException.java | 5 ++
.../kafka/clients/producer/MockProducer.java | 79 +++++++++++++++++++++-
.../kafka/clients/producer/PreparedTxnState.java | 10 +++
.../apache/kafka/clients/producer/Producer.java | 4 +-
.../kafka/clients/producer/ProducerConfig.java | 25 +++++++
5 files changed, 120 insertions(+), 3 deletions(-)
diff --git
a/clients/src/main/java/org/apache/kafka/clients/producer/BufferExhaustedException.java
b/clients/src/main/java/org/apache/kafka/clients/producer/BufferExhaustedException.java
index 292bb4eef1c..06b0ce1767c 100644
---
a/clients/src/main/java/org/apache/kafka/clients/producer/BufferExhaustedException.java
+++
b/clients/src/main/java/org/apache/kafka/clients/producer/BufferExhaustedException.java
@@ -30,6 +30,11 @@ public class BufferExhaustedException extends
TimeoutException {
private static final long serialVersionUID = 1L;
+ /**
+ * Constructs a new BufferExhaustedException with the specified detail
message.
+ *
+ * @param message The error message
+ */
public BufferExhaustedException(String message) {
super(message);
}
diff --git
a/clients/src/main/java/org/apache/kafka/clients/producer/MockProducer.java
b/clients/src/main/java/org/apache/kafka/clients/producer/MockProducer.java
index 7061ac1b384..eb89f88f7d9 100644
--- a/clients/src/main/java/org/apache/kafka/clients/producer/MockProducer.java
+++ b/clients/src/main/java/org/apache/kafka/clients/producer/MockProducer.java
@@ -76,14 +76,23 @@ public class MockProducer<K, V> implements Producer<K, V> {
private long commitCount = 0L;
private final List<KafkaMetric> addedMetrics = new ArrayList<>();
+ /** Exception to throw when {@link #initTransactions(boolean)} is called */
public RuntimeException initTransactionException = null;
+ /** Exception to throw when {@link #beginTransaction()} is called */
public RuntimeException beginTransactionException = null;
+ /** Exception to throw when {@link #sendOffsetsToTransaction(Map,
ConsumerGroupMetadata)} is called */
public RuntimeException sendOffsetsToTransactionException = null;
+ /** Exception to throw when {@link #commitTransaction()} is called */
public RuntimeException commitTransactionException = null;
+ /** Exception to throw when {@link #abortTransaction()} is called */
public RuntimeException abortTransactionException = null;
+ /** Exception to throw when {@link #send(ProducerRecord)} or {@link
#send(ProducerRecord, Callback)} is called */
public RuntimeException sendException = null;
+ /** Exception to throw when {@link #flush()} is called */
public RuntimeException flushException = null;
+ /** Exception to throw when {@link #partitionsFor(String)} is called */
public RuntimeException partitionsForException = null;
+ /** Exception to throw when {@link #close()} or {@link #close(Duration)}
is called */
public RuntimeException closeException = null;
private boolean telemetryDisabled = false;
private Uuid clientInstanceId;
@@ -396,17 +405,27 @@ public class MockProducer<K, V> implements Producer<K, V>
{
return this.cluster.partitionsForTopic(topic);
}
+ /**
+ * Disables telemetry for this mock producer for testing purposes.
+ */
public void disableTelemetry() {
telemetryDisabled = true;
}
/**
- * @param injectTimeoutExceptionCounter use -1 for infinite
+ * Injects timeout exceptions into {@link #clientInstanceId(Duration)}
calls for testing purposes.
+ *
+ * @param injectTimeoutExceptionCounter Number of times to inject timeout
exceptions, or -1 for infinite
*/
public void injectTimeoutException(final int
injectTimeoutExceptionCounter) {
this.injectTimeoutExceptionCounter = injectTimeoutExceptionCounter;
}
+ /**
+ * Sets the client instance ID for this mock producer.
+ *
+ * @param instanceId The client instance ID to set
+ */
public void setClientInstanceId(final Uuid instanceId) {
clientInstanceId = instanceId;
}
@@ -455,10 +474,18 @@ public class MockProducer<K, V> implements Producer<K, V>
{
this.closed = true;
}
+ /**
+ * Checks whether this mock producer has been closed.
+ *
+ * @return {@code true} if the producer has been closed, {@code false}
otherwise
+ */
public boolean closed() {
return this.closed;
}
+ /**
+ * Fences this mock producer, causing it to throw {@link
ProducerFencedException} on subsequent transactional operations.
+ */
public synchronized void fenceProducer() {
verifyNotClosed();
verifyNotFenced();
@@ -466,30 +493,65 @@ public class MockProducer<K, V> implements Producer<K, V>
{
this.producerFenced = true;
}
+ /**
+ * Checks whether transactions have been initialized for this mock
producer.
+ *
+ * @return {@code true} if transactions have been initialized, {@code
false} otherwise
+ */
public boolean transactionInitialized() {
return this.transactionInitialized;
}
+ /**
+ * Checks whether a transaction is currently in progress.
+ *
+ * @return {@code true} if a transaction is in progress, {@code false}
otherwise
+ */
public boolean transactionInFlight() {
return this.transactionInFlight;
}
+ /**
+ * Checks whether the current transaction has been committed.
+ *
+ * @return {@code true} if the transaction was committed, {@code false}
otherwise
+ */
public boolean transactionCommitted() {
return this.transactionCommitted;
}
+ /**
+ * Checks whether the current transaction has been aborted.
+ *
+ * @return {@code true} if the transaction was aborted, {@code false}
otherwise
+ */
public boolean transactionAborted() {
return this.transactionAborted;
}
+ /**
+ * Checks whether all sent records have been completed (no pending
completions).
+ *
+ * @return {@code true} if there are no pending completions, {@code false}
otherwise
+ */
public boolean flushed() {
return this.completions.isEmpty();
}
+ /**
+ * Checks whether offsets have been sent to the current transaction.
+ *
+ * @return {@code true} if offsets were sent in the current transaction,
{@code false} otherwise
+ */
public boolean sentOffsets() {
return this.sentOffsets;
}
+ /**
+ * Gets the total number of transactions committed by this mock producer.
+ *
+ * @return The commit count
+ */
public long commitCount() {
return this.commitCount;
}
@@ -501,6 +563,11 @@ public class MockProducer<K, V> implements Producer<K, V> {
return new ArrayList<>(this.sent);
}
+ /**
+ * Gets the list of records sent in the current transaction that have not
yet been committed.
+ *
+ * @return A list of uncommitted producer records
+ */
public synchronized List<ProducerRecord<K, V>> uncommittedRecords() {
return new ArrayList<>(this.uncommittedSends);
}
@@ -513,6 +580,11 @@ public class MockProducer<K, V> implements Producer<K, V> {
return new ArrayList<>(this.consumerGroupOffsets);
}
+ /**
+ * Gets the consumer group offsets sent in the current transaction that
have not yet been committed.
+ *
+ * @return A map of consumer group IDs to their uncommitted offsets
+ */
public synchronized Map<String, Map<TopicPartition, OffsetAndMetadata>>
uncommittedOffsets() {
return this.uncommittedConsumerGroupOffsets;
}
@@ -614,6 +686,11 @@ public class MockProducer<K, V> implements Producer<K, V> {
}
}
+ /**
+ * Gets the list of metrics that have been registered for subscription.
+ *
+ * @return An unmodifiable list of added metrics
+ */
public List<KafkaMetric> addedMetrics() {
return Collections.unmodifiableList(addedMetrics);
}
diff --git
a/clients/src/main/java/org/apache/kafka/clients/producer/PreparedTxnState.java
b/clients/src/main/java/org/apache/kafka/clients/producer/PreparedTxnState.java
index 88a18df8a15..4e9ccf92ff7 100644
---
a/clients/src/main/java/org/apache/kafka/clients/producer/PreparedTxnState.java
+++
b/clients/src/main/java/org/apache/kafka/clients/producer/PreparedTxnState.java
@@ -77,10 +77,20 @@ public class PreparedTxnState {
this.epoch = epoch;
}
+ /**
+ * Gets the producer ID associated with this prepared transaction state.
+ *
+ * @return The producer ID
+ */
public long producerId() {
return producerId;
}
+ /**
+ * Gets the producer epoch associated with this prepared transaction state.
+ *
+ * @return The producer epoch
+ */
public short epoch() {
return epoch;
}
diff --git
a/clients/src/main/java/org/apache/kafka/clients/producer/Producer.java
b/clients/src/main/java/org/apache/kafka/clients/producer/Producer.java
index e6e94691e34..e4e02865189 100644
--- a/clients/src/main/java/org/apache/kafka/clients/producer/Producer.java
+++ b/clients/src/main/java/org/apache/kafka/clients/producer/Producer.java
@@ -83,12 +83,12 @@ public interface Producer<K, V> extends Closeable {
void completeTransaction(PreparedTxnState preparedTxnState) throws
ProducerFencedException;
/**
- * @see KafkaProducer#registerMetricForSubscription(KafkaMetric)
+ * See {@link KafkaProducer#registerMetricForSubscription(KafkaMetric)}
*/
void registerMetricForSubscription(KafkaMetric metric);
/**
- * @see KafkaProducer#unregisterMetricFromSubscription(KafkaMetric)
+ * See {@link KafkaProducer#unregisterMetricFromSubscription(KafkaMetric)}
*/
void unregisterMetricFromSubscription(KafkaMetric metric);
diff --git
a/clients/src/main/java/org/apache/kafka/clients/producer/ProducerConfig.java
b/clients/src/main/java/org/apache/kafka/clients/producer/ProducerConfig.java
index 5e47a9fb88d..f9a99c5ef08 100644
---
a/clients/src/main/java/org/apache/kafka/clients/producer/ProducerConfig.java
+++
b/clients/src/main/java/org/apache/kafka/clients/producer/ProducerConfig.java
@@ -674,22 +674,47 @@ public class ProducerConfig extends AbstractConfig {
return newConfigs;
}
+ /**
+ * Constructs a new ProducerConfig with the given properties.
+ *
+ * @param props The producer configuration properties
+ */
public ProducerConfig(Properties props) {
super(CONFIG, props);
}
+ /**
+ * Constructs a new ProducerConfig with the given configuration map.
+ *
+ * @param props The producer configuration map
+ */
public ProducerConfig(Map<String, Object> props) {
super(CONFIG, props);
}
+ /**
+ * Gets the set of all producer configuration names.
+ *
+ * @return The set of configuration names
+ */
public static Set<String> configNames() {
return CONFIG.names();
}
+ /**
+ * Gets a copy of the producer configuration definition.
+ *
+ * @return A new ConfigDef instance containing the producer configuration
definition
+ */
public static ConfigDef configDef() {
return new ConfigDef(CONFIG);
}
+ /**
+ * Generates HTML documentation for producer configurations.
+ *
+ * @param args Command line arguments (unused)
+ */
public static void main(String[] args) {
System.out.println(CONFIG.toHtml(4, config -> "producerconfigs_" +
config));
}
