update MQTT5 User Guide and FAQ with Manual Publish Acknowledgement info

Author: sbSteveK

documents/FAQ.md

@@ -13,6 +13,7 @@
 * [Where can I find MQTT 311 Samples?](#where-can-i-find-mqtt-311-samples)
 * [How can I improve the library size?](#how-can-i-improve-the-library-size)
 * [Certificate and Private Key Usage Across Different Versions of the SDK on macOS](#certificate-and-private-key-usage-across-different-versions-of-the-sdk-on-macos)
+* [Manual Publish Acknowledgement and QoS 1 Redelivery](#manual-publish-acknowledgement-and-qos-1-redelivery)
 * [I still have more questions about this sdk?](#i-still-have-more-questions-about-this-sdk)
 
 ### Where should I start?
@@ -176,6 +177,18 @@ For maximum control, build both CRT and SDK locally:
 ### Certificate and Private Key Usage Across Different Versions of the SDK on macOS
 A certificate and private key pair cannot be shared on a macOS device between aws-iot-device-sdk-java-v2 v1.29.0 and other versions. In the update to v1.29.0 we migrated macOS from using Apple's deprecated Security Framework to SecItem API. In doing so, certificate and private keys are imported in a non-backwards compatible manner into the Apple Keychain.
 
+### Manual Publish Acknowledgement and QoS 1 Redelivery
+
+When using [manual publish acknowledgement](./MQTT5_Userguide.md#manual-publish-acknowledgement), there are two important behaviors to be aware of regarding QoS 1 message redelivery:
+
+**Broker redelivery of unacknowledged publishes**
+
+The AWS IoT broker will periodically resend unacknowledged QoS 1 PUBLISH packets. These redeliveries should be treated as duplicates even if the DUP flag in the PUBLISH packet is not set. If the manual publish acknowledgement is not acquired again for a redelivered packet, the acknowledgement will be sent automatically.
+
+**Session resumption after disconnect/reconnect**
+
+Upon a disconnect and reconnect of the MQTT5 client, if a session is resumed, any previously acquired acknowledgement handle is void. The broker will resend the unacknowledged PUBLISH packet, and the acknowledgement must be reacquired from that resent packet. If the resent packet is not handled for manual acknowledgement, the acknowledgement will be sent automatically.
+
 ### I still have more questions about this sdk?
 
 * [Here](https://docs.aws.amazon.com/iot/latest/developerguide/what-is-aws-iot.html) are the AWS IoT Core docs for more details about IoT Core

documents/MQTT5_Userguide.md

@@ -24,6 +24,8 @@
         + [Publish](#publish)
         + [Subscribe and Unsubscribe](#subscribe-and-unsubscribe)
     + [MQTT5 Best Practices](#mqtt5-best-practices)
+* [Advanced Operations and Settings](#advanced-operations-and-settings)
+    + [Manual Publish Acknowledgement](#manual-publish-acknowledgement)
 
 # Introduction
 
@@ -564,3 +566,54 @@ Below are some best practices for the MQTT5 client that are recommended to follo
 * Make sure to always call `close()` when finished a MQTT5 client to avoid native resource leaks!
 * For [publish](https://awslabs.github.io/aws-crt-java/software/amazon/awssdk/crt/mqtt5/Mqtt5Client.html#publish(software.amazon.awssdk.crt.mqtt5.packets.PublishPacket)), [subscribe](https://awslabs.github.io/aws-crt-java/software/amazon/awssdk/crt/mqtt5/Mqtt5Client.html#subscribe(software.amazon.awssdk.crt.mqtt5.packets.SubscribePacket)), and [unsubscribe](https://awslabs.github.io/aws-crt-java/software/amazon/awssdk/crt/mqtt5/Mqtt5Client.html#unsubscribe(software.amazon.awssdk.crt.mqtt5.packets.UnsubscribePacket)), make sure to check the reason codes in the ACK ([PubAckPacket](https://awslabs.github.io/aws-crt-java/software/amazon/awssdk/crt/mqtt5/packets/PubAckPacket.html), [SubAckPacket](https://awslabs.github.io/aws-crt-java/software/amazon/awssdk/crt/mqtt5/packets/SubAckPacket.html), and [UnsubAckPacket](https://awslabs.github.io/aws-crt-java/software/amazon/awssdk/crt/mqtt5/packets/UnsubAckPacket.html) respectively) to see if the operation actually succeeded.
 * You MUST NOT perform blocking operations on any callback, or you will cause a deadlock. For example: in the `onMessageReceived` callback, do not send a publish, and then wait for the future to complete within the callback. The Client cannot do work until your callback returns, so the thread will be stuck.
+
+## Advanced Operations and Settings
+
+### Manual Publish Acknowledgement
+
+By default, the MQTT5 client automatically sends a PUBACK for every QoS 1 PUBLISH it receives, immediately after the `onMessageReceived` callback returns. Manual publish acknowledgement gives you control over when that PUBACK is sent, allowing you to defer acknowledgement until after your application has fully processed the message — for example, after persisting it to a database or forwarding it to another service.
+
+To take manual control of the PUBACK, call `publishReturn.acquirePublishAcknowledgementControl()` **within** the `onMessageReceived` callback. This returns a `Mqtt5PublishAcknowledgementControlHandle` that you can store and use later to send the PUBACK by calling `client.invokePublishAcknowledgement()`.
+
+**Important constraints:**
+* `acquirePublishAcknowledgementControl()` must be called within the `onMessageReceived` callback. Calling it outside the callback or after it returns will return `null`.
+* `acquirePublishAcknowledgementControl()` may only be called once per received PUBLISH. Subsequent calls will return `null`.
+* This is only relevant for QoS 1 messages. Calling it on a QoS 0 message will return `null`.
+* If `acquirePublishAcknowledgementControl()` is not called, the client will automatically send the PUBACK when the callback returns.
+
+The following example shows how to acquire the acknowledgement handle within the callback and invoke it later:
+
+~~~ java
+// A shared location to store the acknowledgement handle for later use
+final AtomicReference<Mqtt5PublishAcknowledgementControlHandle> pendingAck = new AtomicReference<>();
+
+class MyPublishEvents implements Mqtt5ClientOptions.PublishEvents {
+    @Override
+    public void onMessageReceived(Mqtt5Client client, PublishReturn publishReturn) {
+        System.out.println("Message received on topic: " +
+            publishReturn.getPublishPacket().getTopic());
+
+        if (publishReturn.getPublishPacket().getQOS() == QOS.AT_LEAST_ONCE) {
+            // Acquire manual control of the PUBACK for this QoS 1 message.
+            // This must be called within the callback. Calling it outside the callback
+            // or after it returns will return null.
+            Mqtt5PublishAcknowledgementControlHandle handle =
+                publishReturn.acquirePublishAcknowledgementControl();
+
+            if (handle != null) {
+                // The PUBACK will NOT be sent automatically because we acquired the handle.
+                // Store it for later use after processing is complete.
+                pendingAck.set(handle);
+            }
+        }
+    }
+}
+
+// ... build client, connect, and subscribe ...
+
+// After processing is complete, send the PUBACK by invoking the acknowledgement.
+Mqtt5PublishAcknowledgementControlHandle handle = pendingAck.getAndSet(null);
+if (handle != null) {
+    client.invokePublishAcknowledgement(handle);
+}
+~~~