kafka git commit: KAFKA-3280: KafkaConsumer Javadoc contains misleading description of heartbeat behavior and correct use

[gw...@apache.org]

Repository: kafka
Updated Branches:
  refs/heads/trunk 62945280a -> d51dd5fc7


KAFKA-3280: KafkaConsumer Javadoc contains misleading description of heartbeat behavior and correct use

This is my original work and I license the work to the project under the project's open source license.

Author: Richard Whaling <rw...@spantree.net>

Reviewers: Jason Gustafson, Gwen Shapira

Closes #968 from rwhaling/docs/kafkaconsumer-heartbeat-doc-improvement


Project: http://git-wip-us.apache.org/repos/asf/kafka/repo
Commit: http://git-wip-us.apache.org/repos/asf/kafka/commit/d51dd5fc
Tree: http://git-wip-us.apache.org/repos/asf/kafka/tree/d51dd5fc
Diff: http://git-wip-us.apache.org/repos/asf/kafka/diff/d51dd5fc

Branch: refs/heads/trunk
Commit: d51dd5fc7475ad29bea8616f77e1183a8fa9e000
Parents: 6294528
Author: Richard Whaling <rw...@spantree.net>
Authored: Thu Feb 25 18:24:51 2016 -0800
Committer: Gwen Shapira <cs...@gmail.com>
Committed: Thu Feb 25 18:24:51 2016 -0800

----------------------------------------------------------------------
 .../org/apache/kafka/clients/consumer/KafkaConsumer.java | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/kafka/blob/d51dd5fc/clients/src/main/java/org/apache/kafka/clients/consumer/KafkaConsumer.java
----------------------------------------------------------------------
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 e1b07d9..c88f607 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
@@ -166,11 +166,12 @@ import java.util.regex.Pattern;
  * In this example the client is subscribing to the topics <i>foo</i> and <i>bar</i> as part of a group of consumers
  * called <i>test</i> as described above.
  * <p>
- * The broker will automatically detect failed processes in the <i>test</i> group by using a heartbeat mechanism. The
- * consumer will automatically ping the cluster periodically, which lets the cluster know that it is alive. As long as
- * the consumer is able to do this it is considered alive and retains the right to consume from the partitions assigned
- * to it. If it stops heartbeating for a period of time longer than <code>session.timeout.ms</code> then it will be
- * considered dead and its partitions will be assigned to another process.
+ * The broker will automatically detect failed processes in the <i>test</i> group by using a heartbeat mechanism. The 
+ * consumer will automatically ping the cluster periodically, which lets the cluster know that it is alive. Note that 
+ * the consumer is single-threaded, so periodic heartbeats can only be sent when {@link #poll(long)} is called. As long as 
+ * the consumer is able to do this it is considered alive and retains the right to consume from the partitions assigned 
+ * to it. If it stops heartbeating by failing to call {@link #poll(long)} for a period of time longer than <code>session.timeout.ms</code> 
+ * then it will be considered dead and its partitions will be assigned to another process.
  * <p>
  * The deserializer settings specify how to turn bytes into objects. For example, by specifying string deserializers, we
  * are saying that our record's key and value will just be simple strings.