GH-3181: MQTT: Support MANUAL Acks

Resolves https://github.com/spring-projects/spring-integration/issues/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.

src/reference/asciidoc/message.adoc

@@ -171,8 +171,8 @@ ACKNOWLEDGMENT_CALLBACK
 | o.s.i.support.
 Acknowledgment
 Callback
-| If a message source supports it, a call back to accept, reject, or requeue a message.
-See <<./polling-consumer.adoc#deferred-acks-message-source,Deferred Acknowledgment Pollable Message Source>>.
+| If an inbound endpoint supports it, a call back to accept, reject, or requeue a message.
+See <<./polling-consumer.adoc#deferred-acks-message-source,Deferred Acknowledgment Pollable Message Source>> and <<./mqtt.adoc#mqtt-ack-mode,MQTT Manual Acks>>.
 |===
 
 Convenient typed getters for some of these headers are provided on the `IntegrationMessageHeaderAccessor` class, as the following example shows:

src/reference/asciidoc/mqtt.adoc

@@ -74,6 +74,7 @@ The following listing shows the available attributes:
     send-timeout="123"  <7>
     error-channel="errors"  <8>
     recovery-interval="10000"  <9>
+    manual-acks="false" <10>
     channel="out" />
 ----
 
@@ -97,6 +98,7 @@ The payload is a `MessagingException` that contains the failed message and cause
 <9> The recovery interval.
 It controls the interval at which the adapter attempts to reconnect after a failure.
 It defaults to `10000ms` (ten seconds).
+<10> The acknowledgment mode; set to true for manual acknowledgment.
 ====
 
 NOTE: Starting with version 4.1, you can omit the URL.
@@ -145,6 +147,23 @@ A new application context reverts to the configured settings.
 
 Changing the topics while the adapter is stopped (or disconnected from the broker) takes effect the next time a connection is established.
 
+[[mqtt-ack-mode]]
+==== Manual Acks
+
+Starting with version 5.3, you can set the `manualAcks` property to true.
+Often used to asynchronously acknowledge delivery.
+When set to `true`, header (`IntegrationMessageHeaderAccessor.ACKNOWLEDGMENT_CALLBACK`) is added to the message with the value being a `SimpleAcknowledgment`.
+You must invoke the `acknowledge()` method to complete the delivery.
+See the Javadocs for `IMqppClient` `setManualAcks()` and `messageArrivedComplete()` for more information.
+For convenience a header accessor is provided:
+
+====
+[source, java]
+----
+StaticMessageHeaderAccessor.acknowledgment(someMessage).acknowledge();
+----
+====
+
 ==== Configuring with Java Configuration
 
 The following Spring Boot application shows an example of how to configure the inbound adapter with Java configuration:
@@ -278,7 +297,7 @@ The default is `headers['mqtt_topic']`.
 <11> When `true`, the caller does not block.
 Rather, it waits for delivery confirmation when a message is sent.
 The default is `false` (the send blocks until delivery is confirmed).
-<12> When `async` and `async-events` are both `true`, an `MqttMessageSentEvent` is emitted (See <<events>>).
+<12> When `async` and `async-events` are both `true`, an `MqttMessageSentEvent` is emitted (See <<mqtt-events>>).
 It contains the message, the topic, the `messageId` generated by the client library, the `clientId`, and the `clientInstance` (incremented each time the client is connected).
 When the delivery is confirmed by the client library, an `MqttMessageDeliveredEvent` is emitted.
 It contains the the `messageId`, the `clientId`, and the `clientInstance`, enabling delivery to be correlated with the send.
@@ -373,7 +392,7 @@ public class MqttJavaApplication {
 ----
 ====
 
-[[events]]
+[[mqtt-events]]
 === Events
 
 Certain application events are published by the adapters.
@@ -381,5 +400,6 @@ Certain application events are published by the adapters.
 * `MqttConnectionFailedEvent` - published by both adapters if we fail to connect or a connection is subsequently lost.
 * `MqttMessageSentEvent` - published by the outbound adapter when a message has been sent, if running in asynchronous mode.
 * `MqttMessageDeliveredEvent` - published by the outbound adapter when the client indicates that a message has been delivered, if running in asynchronous mode.
+* `MqttSubscribedEvent` - published by the inbound adapter after subscribing to the topics.
 
 These events can be received by an `ApplicationListener<MqttIntegrationEvent>` or with an `@EventListener` method.

src/reference/asciidoc/polling-consumer.adoc

@@ -60,7 +60,7 @@ Starting with version 5.0.1, certain modules provide `MessageSource` implementat
 This is currently limited to the `AmqpMessageSource` and the `KafkaMessageSource` provided by the `spring-integration-kafka` https://github.com/spring-projects/spring-integration-kafka[extension project].
 
 With these message sources, the `IntegrationMessageHeaderAccessor.ACKNOWLEDGMENT_CALLBACK` header (see <<./message.adoc#message-header-accessor,`MessageHeaderAccessor` API>>) is added to the message.
-The value of the header is an instance of `AcknowledgmentCallback`, as the following example shows:
+When used with pollable message sources, the value of the header is an instance of `AcknowledgmentCallback`, as the following example shows:
 
 [source, java]
 ----

src/reference/asciidoc/whats-new.adoc

@@ -116,3 +116,13 @@ See <<./rsocket.adoc#rsocket-inbound,RSocket Inbound Gateway>> for more informat
 
 A `LeaderInitiatorFactoryBean` (as well as its XML `<int-zk:leader-listener>`) exposes a `candidate` option for more control over a `Candidate` configuration.
 See <<./zookeeper.adoc#zk-leadership,Leadership event handling>> for more information.
+
+[[x5.3-mqtt]]
+=== MQTT Changes
+
+The inbound channel adapter can now be configured to provide user control over when a message is acknowledged as being delivered.
+See <<./mqtt.adoc#mqtt-ack-mode,Manual Acks>> for more information.
+
+The outbound adapter now publishes a `MqttConnectionFailedEvent` when a connection can't be created, or is lost.
+Previously, only the inbound adapter did so.
+See <<./mqtt.adoc#mqtt-events,MQTT Events>>.