From 895c83f88d351ac1f86e5df13af23423e162b774 Mon Sep 17 00:00:00 2001
From: huxi <huxi_2b@hotmail.com>
Date: Fri, 9 Nov 2018 08:58:14 +0800
Subject: [PATCH] KAFKA-7412: clarify the doc for producer callback (#5798)

The metadata in the callback is not null with non-null exception.

Reviewers: Jun Rao <junrao@gmail.com>
---
 .../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 a70e4e9a685..f7d4bcdd468 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 87212801246..b6998c58ac7 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.