GH-3181: MQTT: Support MANUAL Acks

Resolves #3181

* Doc polishing

* Rework acknowledgment into the existing `AcknowledgmentCallback`.

* Fix javadocs and doc linFix javadocs and doc linkk

* Doc polishing; explain uses of `ACKNOWLEDGMENT_CALLBACK` header.

Author: garyrussell

spring-integration-core/src/main/java/org/springframework/integration/IntegrationMessageHeaderAccessor.java

@@ -65,6 +65,11 @@ public class IntegrationMessageHeaderAccessor extends MessageHeaderAccessor {
 
 	public static final String DELIVERY_ATTEMPT = "deliveryAttempt";
 
+	/**
+	 * A callback to acknowledge message delivery. The type of the header value depends on
+	 * the context in which the header is used. See the reference manual for more
+	 * information.
+	 */
 	public static final String ACKNOWLEDGMENT_CALLBACK = "acknowledgmentCallback";
 
 	/**

spring-integration-core/src/main/java/org/springframework/integration/StaticMessageHeaderAccessor.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2017-2019 the original author or authors.
+ * Copyright 2017-2020 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -21,6 +21,7 @@
 import java.util.concurrent.atomic.AtomicInteger;
 
 import org.springframework.integration.acks.AcknowledgmentCallback;
+import org.springframework.integration.acks.SimpleAcknowledgment;
 import org.springframework.lang.Nullable;
 import org.springframework.messaging.Message;
 import org.springframework.messaging.MessageHeaders;
@@ -107,6 +108,12 @@ public static AcknowledgmentCallback getAcknowledgmentCallback(Message<?> messag
 				AcknowledgmentCallback.class);
 	}
 
+	@Nullable
+	public static SimpleAcknowledgment getAcknowledgment(Message<?> message) {
+		return message.getHeaders().get(IntegrationMessageHeaderAccessor.ACKNOWLEDGMENT_CALLBACK,
+				SimpleAcknowledgment.class);
+	}
+
 	@SuppressWarnings("unchecked")
 	@Nullable
 	public static <T> T getSourceData(Message<?> message) {

spring-integration-core/src/main/java/org/springframework/integration/acks/AcknowledgmentCallback.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2018-2019 the original author or authors.
+ * Copyright 2018-2020 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -25,14 +25,19 @@
  *
  */
 @FunctionalInterface
-public interface AcknowledgmentCallback {
+public interface AcknowledgmentCallback extends SimpleAcknowledgment {
 
 	/**
 	 * Acknowledge the message.
 	 * @param status the status.
 	 */
 	void acknowledge(Status status);
 
+	@Override
+	default void acknowledge() {
+		acknowledge(Status.ACCEPT);
+	}
+
 	/**
 	 * Implementations must implement this to indicate when the ack has been
 	 * processed by the user so that the framework can auto-ack if needed.

spring-integration-core/src/main/java/org/springframework/integration/acks/SimpleAcknowledgment.java

@@ -0,0 +1,34 @@
+/*
+ * Copyright 2020 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.integration.acks;
+
+/**
+ * Opaque object for manually acknowledging.
+ *
+ * @author Gary Russell
+ * @since 5.3
+ *
+ */
+@FunctionalInterface
+public interface SimpleAcknowledgment {
+
+	/**
+	 * Acknowledge the message delivery.
+	 */
+	void acknowledge();
+
+}

spring-integration-mqtt/src/main/java/org/springframework/integration/mqtt/config/xml/MqttMessageDrivenChannelAdapterParser.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2019 the original author or authors.
+ * Copyright 2002-2020 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -48,6 +48,7 @@ protected AbstractBeanDefinition doParse(Element element, ParserContext parserCo
 		IntegrationNamespaceUtils.setReferenceIfAttributeDefined(builder, element, "error-channel");
 		IntegrationNamespaceUtils.setValueIfAttributeDefined(builder, element, "qos");
 		IntegrationNamespaceUtils.setValueIfAttributeDefined(builder, element, "recovery-interval");
+		IntegrationNamespaceUtils.setValueIfAttributeDefined(builder, element, "manual-acks");
 
 		return builder.getBeanDefinition();
 	}

spring-integration-mqtt/src/main/java/org/springframework/integration/mqtt/inbound/MqttPahoMessageDrivenChannelAdapter.java

@@ -30,11 +30,14 @@
 
 import org.springframework.context.ApplicationEventPublisher;
 import org.springframework.context.ApplicationEventPublisherAware;
+import org.springframework.integration.IntegrationMessageHeaderAccessor;
+import org.springframework.integration.acks.SimpleAcknowledgment;
 import org.springframework.integration.mqtt.core.ConsumerStopAction;
 import org.springframework.integration.mqtt.core.DefaultMqttPahoClientFactory;
 import org.springframework.integration.mqtt.core.MqttPahoClientFactory;
 import org.springframework.integration.mqtt.event.MqttConnectionFailedEvent;
 import org.springframework.integration.mqtt.event.MqttSubscribedEvent;
+import org.springframework.integration.support.AbstractIntegrationMessageBuilder;
 import org.springframework.messaging.Message;
 import org.springframework.messaging.MessagingException;
 import org.springframework.util.Assert;
@@ -71,6 +74,8 @@ public class MqttPahoMessageDrivenChannelAdapter extends AbstractMqttMessageDriv
 
 	private long disconnectCompletionTimeout = DISCONNECT_COMPLETION_TIMEOUT;
 
+	private boolean manualAcks;
+
 	private volatile IMqttClient client;
 
 	private volatile ScheduledFuture<?> reconnectFuture;
@@ -152,6 +157,15 @@ public synchronized void setRecoveryInterval(int recoveryInterval) {
 		this.recoveryInterval = recoveryInterval;
 	}
 
+	/**
+	 * Set the acknowledgment mode to manual.
+	 * @param manualAcks true for manual acks.
+	 * @since 5.3
+	 */
+	public void setManualAcks(boolean manualAcks) {
+		this.manualAcks = manualAcks;
+	}
+
 	/**
 	 * @since 4.2.2
 	 */
@@ -263,6 +277,7 @@ private synchronized void connectAndSubscribe() throws MqttException {
 		String[] topics = getTopic();
 		try {
 			this.client.connect(connectionOptions);
+			this.client.setManualAcks(this.manualAcks);
 			int[] requestedQos = getQos();
 			int[] grantedQos = Arrays.copyOf(requestedQos, requestedQos.length);
 			this.client.subscribe(topics, grantedQos);
@@ -365,7 +380,12 @@ public synchronized void connectionLost(Throwable cause) {
 
 	@Override
 	public void messageArrived(String topic, MqttMessage mqttMessage) {
-		Message<?> message = this.getConverter().toMessage(topic, mqttMessage);
+		AbstractIntegrationMessageBuilder<?> builder = getConverter().toMessageBuilder(topic, mqttMessage);
+		if (this.manualAcks) {
+			builder.setHeader(IntegrationMessageHeaderAccessor.ACKNOWLEDGMENT_CALLBACK,
+					new AcknowledgmentImpl(mqttMessage.getId(), mqttMessage.getQos(), this.client));
+		}
+		Message<?> message = builder.build();
 		try {
 			sendMessage(message);
 		}
@@ -379,4 +399,46 @@ public void messageArrived(String topic, MqttMessage mqttMessage) {
 	public void deliveryComplete(IMqttDeliveryToken token) {
 	}
 
+	/**
+	 * Used to complete message arrival when {@link AckMode#MANUAL}.
+	 *
+	 * @since 5.3
+	 */
+	private static class AcknowledgmentImpl implements SimpleAcknowledgment {
+
+		private final int id;
+
+		private final int qos;
+
+		private final IMqttClient ackClient;
+
+		/**
+		 * Construct an instance with the provided properties.
+		 * @param id the message id.
+		 * @param qos the message QOS.
+		 * @param client the client.
+		 */
+		AcknowledgmentImpl(int id, int qos, IMqttClient client) {
+			this.id = id;
+			this.qos = qos;
+			this.ackClient = client;
+		}
+
+		@Override
+		public void acknowledge() {
+			if (this.ackClient != null) {
+				try {
+					this.ackClient.messageArrivedComplete(this.id, this.qos);
+				}
+				catch (MqttException e) {
+					throw new IllegalStateException(e);
+				}
+			}
+			else {
+				throw new IllegalStateException("Client has changed");
+			}
+		}
+
+	}
+
 }

spring-integration-mqtt/src/main/java/org/springframework/integration/mqtt/support/DefaultPahoMessageConverter.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2019 the original author or authors.
+ * Copyright 2002-2020 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -206,6 +206,11 @@ public Message<?> toMessage(Object mqttMessage, MessageHeaders headers) {
 
 	@Override
 	public Message<?> toMessage(String topic, MqttMessage mqttMessage) {
+		return toMessageBuilder(topic, mqttMessage).build();
+	}
+
+	@Override
+	public AbstractIntegrationMessageBuilder<?> toMessageBuilder(String topic, MqttMessage mqttMessage) {
 		try {
 			AbstractIntegrationMessageBuilder<?> messageBuilder;
 			if (this.bytesMessageMapper != null) {
@@ -219,13 +224,14 @@ public Message<?> toMessage(String topic, MqttMessage mqttMessage) {
 								.withPayload(mqttBytesToPayload(mqttMessage));
 			}
 			messageBuilder
+					.setHeader(MqttHeaders.ID, mqttMessage.getId())
 					.setHeader(MqttHeaders.RECEIVED_QOS, mqttMessage.getQos())
 					.setHeader(MqttHeaders.DUPLICATE, mqttMessage.isDuplicate())
 					.setHeader(MqttHeaders.RECEIVED_RETAINED, mqttMessage.isRetained());
 			if (topic != null) {
 				messageBuilder.setHeader(MqttHeaders.RECEIVED_TOPIC, topic);
 			}
-			return messageBuilder.build();
+			return messageBuilder;
 		}
 		catch (Exception e) {
 			throw new MessageConversionException("failed to convert object to Message", e);

spring-integration-mqtt/src/main/java/org/springframework/integration/mqtt/support/MqttHeaderAccessor.java

@@ -0,0 +1,84 @@
+/*
+ * Copyright 2020 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.integration.mqtt.support;
+
+import org.springframework.lang.Nullable;
+import org.springframework.messaging.Message;
+
+/**
+ * Helper for typed access to incoming MQTT message headers.
+ *
+ * @author Gary Russell
+ * @since 5.3
+ *
+ */
+public final class MqttHeaderAccessor {
+
+	private MqttHeaderAccessor() {
+	}
+
+	/**
+	 * Return the received topic header.
+	 * @param message the message.
+	 * @return the header.
+	 */
+	@Nullable
+	public static String receivedTopic(Message<?> message) {
+		return message.getHeaders().get(MqttHeaders.RECEIVED_TOPIC, String.class);
+	}
+
+	/**
+	 * Return the MQTT message id.
+	 * @param message the message.
+	 * @return the header.
+	 */
+	@Nullable
+	public static Integer id(Message<?> message) {
+		return message.getHeaders().get(MqttHeaders.ID, Integer.class);
+	}
+
+	/**
+	 * Return the received QOS header.
+	 * @param message the message.
+	 * @return the header.
+	 */
+	@Nullable
+	public static Integer receivedQos(Message<?> message) {
+		return message.getHeaders().get(MqttHeaders.RECEIVED_QOS, Integer.class);
+	}
+
+	/**
+	 * Return the received retained header.
+	 * @param message the message.
+	 * @return the header.
+	 */
+	@Nullable
+	public static Boolean receivedRetained(Message<?> message) {
+		return message.getHeaders().get(MqttHeaders.RECEIVED_RETAINED, Boolean.class);
+	}
+
+	/**
+	 * Return the duplicate header.
+	 * @param message the message.
+	 * @return the header.
+	 */
+	@Nullable
+	public static Boolean duplicate(Message<?> message) {
+		return message.getHeaders().get(MqttHeaders.DUPLICATE, Boolean.class);
+	}
+
+}

spring-integration-mqtt/src/main/java/org/springframework/integration/mqtt/support/MqttHeaders.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2019 the original author or authors.
+ * Copyright 2002-2020 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -30,6 +30,8 @@ public final class MqttHeaders {
 
 	public static final String QOS = PREFIX + "qos";
 
+	public static final String ID = PREFIX + "id";
+
 	public static final String RECEIVED_QOS = PREFIX + "receivedQos";
 
 	public static final String DUPLICATE = PREFIX + "duplicate";