GH-1353: Clarify AckMode with transactions

Resolves #1353

`AckMode` is not used with transactions - clarify the semantics in docs
and javadocs.

Also fix that offsets were not previously sent to the transaction with an
incorrectly configured MANUAL ack mode.

Author: garyrussell

spring-kafka/src/main/java/org/springframework/kafka/listener/ContainerProperties.java

@@ -287,7 +287,11 @@ public void setMessageListener(Object messageListener) {
 	 * <li>MANUAL: Listener is responsible for acking - use a
 	 * {@link org.springframework.kafka.listener.AcknowledgingMessageListener}.
 	 * </ul>
+	 * Ignored when transactions are being used. Transactional consumers commit offsets
+	 * with semantics equivalent to {@code RECORD} or {@code BATCH}, depending on
+	 * the listener type.
 	 * @param ackMode the {@link AckMode}; default BATCH.
+	 * @see #setTransactionManager(PlatformTransactionManager)
 	 */
 	public void setAckMode(AckMode ackMode) {
 		Assert.notNull(ackMode, "'ackMode' cannot be null");

spring-kafka/src/main/java/org/springframework/kafka/listener/KafkaMessageListenerContainer.java

@@ -1451,7 +1451,7 @@ private void invokeBatchOnMessage(final ConsumerRecords<K, V> records, // NOSONA
 					}
 				}
 			}
-			if (!this.isAnyManualAck && !this.autoCommit) {
+			if (producer != null || (!this.isAnyManualAck && !this.autoCommit)) {
 				for (ConsumerRecord<K, V> record : getHighestOffsetRecords(records)) {
 					this.acks.put(record);
 				}
@@ -1811,7 +1811,7 @@ public void ackCurrent(final ConsumerRecord<K, V> record,
 					this.acks.add(record);
 				}
 			}
-			else if (!this.isAnyManualAck && !this.autoCommit) {
+			else if (producer != null || (!this.isAnyManualAck && !this.autoCommit)) {
 				this.acks.add(record);
 			}
 			if (producer != null) {

src/reference/asciidoc/kafka.adoc

@@ -829,7 +829,7 @@ Previously, the Kafka default (`true`) was used if the property was not set.
 
 The consumer `poll()` method returns one or more `ConsumerRecords`.
 The `MessageListener` is called for each record.
-The following lists describes the action taken by the container for each `AckMode`:
+The following lists describes the action taken by the container for each `AckMode` (when transactions are not being used):
 
 * `RECORD`: Commit the offset when the listener returns after processing the record.
 * `BATCH`: Commit the offset when all the records returned by the `poll()` have been processed.
@@ -840,6 +840,8 @@ The following lists describes the action taken by the container for each `AckMod
 After that, the same semantics as `BATCH` are applied.
 * `MANUAL_IMMEDIATE`: Commit the offset immediately when the `Acknowledgment.acknowledge()` method is called by the listener.
 
+When using <<transactions, transactions>>, the offset(s) are sent to the transaction and the semantics are equivalent to `RECORD` or `BATCH`, depending on the listener type (record or batch).
+
 NOTE: `MANUAL`, and `MANUAL_IMMEDIATE` require the listener to be an `AcknowledgingMessageListener` or a `BatchAcknowledgingMessageListener`.
 See <<message-listeners, Message Listeners>>.