[kafka] branch trunk updated: KAFKA-7412: clarify the doc for producer callback (#5798)

[ju...@apache.org]

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

junrao 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 895c83f  KAFKA-7412: clarify the doc for producer callback (#5798)
895c83f is described below

commit 895c83f88d351ac1f86e5df13af23423e162b774
Author: huxi <hu...@hotmail.com>
AuthorDate: Fri Nov 9 08:58:14 2018 +0800

    KAFKA-7412: clarify the doc for producer callback (#5798)
    
    The metadata in the callback is not null with non-null exception.
    
    Reviewers: Jun Rao <ju...@gmail.com>
---
 .../main/java/org/apache/kafka/clients/producer/Callback.java | 11 ++++++-----
 examples/src/main/java/kafka/examples/Producer.java           |  4 ++--
 2 files changed, 8 insertions(+), 7 deletions(-)

diff --git a/clients/src/main/java/org/apache/kafka/clients/producer/Callback.java b/clients/src/main/java/org/apache/kafka/clients/producer/Callback.java
index a70e4e9..f7d4bcd 100644
--- a/clients/src/main/java/org/apache/kafka/clients/producer/Callback.java
+++ b/clients/src/main/java/org/apache/kafka/clients/producer/Callback.java
@@ -24,10 +24,11 @@ public interface Callback {
 
     /**
      * A callback method the user can implement to provide asynchronous handling of request completion. This method will
-     * be called when the record sent to the server has been acknowledged. Exactly one of the arguments will be
-     * non-null.
-     * @param metadata The metadata for the record that was sent (i.e. the partition and offset). Null if an error
-     *        occurred.
+     * be called when the record sent to the server has been acknowledged. When exception is not null in the callback,
+     * metadata will contain the special -1 value for all fields except for topicPartition, which will be valid.
+     *
+     * @param metadata The metadata for the record that was sent (i.e. the partition and offset). An empty metadata
+     *                 with -1 value for all fields except for topicPartition will be returned if an error occurred.
      * @param exception The exception thrown during processing of this record. Null if no error occurred.
      *                  Possible thrown exceptions include:
      *
@@ -49,5 +50,5 @@ public interface Callback {
      *                  TimeoutException
      *                  UnknownTopicOrPartitionException
      */
-    public void onCompletion(RecordMetadata metadata, Exception exception);
+    void onCompletion(RecordMetadata metadata, Exception exception);
 }
diff --git a/examples/src/main/java/kafka/examples/Producer.java b/examples/src/main/java/kafka/examples/Producer.java
index 8721280..b6998c5 100644
--- a/examples/src/main/java/kafka/examples/Producer.java
+++ b/examples/src/main/java/kafka/examples/Producer.java
@@ -81,8 +81,8 @@ class DemoCallBack implements Callback {
 
     /**
      * A callback method the user can implement to provide asynchronous handling of request completion. This method will
-     * be called when the record sent to the server has been acknowledged. Exactly one of the arguments will be
-     * non-null.
+     * be called when the record sent to the server has been acknowledged. When exception is not null in the callback,
+     * metadata will contain the special -1 value for all fields except for topicPartition, which will be valid.
      *
      * @param metadata  The metadata for the record that was sent (i.e. the partition and offset). Null if an error
      *                  occurred.