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>

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);
 }

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.