Differing semantics of KafkaConsumer.pause() and pause(TopicPartition)

[tombentley]

KafkaConsumer.pause() will immediately stop the KafkaConsumer from calling the record handler until resume() is called. This includes preventing the processing of buffered messages.

In contrast, KafkaConsumer.pause(TopicPartition) and KafkaConsumer.pause(Set<TopicPartition>) just correspond to a native pause(Set<TopicPartition>), which will take effect on the next call to poll(), but buffered messages from the given TopicPartitions will continue to be processed.

This difference in behaviour should be explicitly documented in the API.

[ghost]

This also prevents sending heartbeats which triggers consumer group rebalance on kafka side when pause duration exceeds max.poll.interval.ms (or heartbeat.interval.ms for older versions of underlying kafka library). So this should be fixed, not just documented.