update docs, make jni/native functions private

Author: sbSteveK

src/main/java/software/amazon/awssdk/crt/mqtt5/PublishReturn.java

@@ -40,13 +40,10 @@ public PublishPacket getPublishPacket() {
     }
 
     /**
-     * Acquires manual control over the publish acknowledgement (PUBACK) for this PUBLISH message,
+     * Acquires manual control over the publish acknowledgement for this PUBLISH message,
      * preventing the client from automatically sending an acknowledgement. The returned handle can be
      * passed to {@link Mqtt5Client#invokePublishAcknowledgement(Mqtt5PublishAcknowledgementControlHandle)}
-     * at a later time to send the PUBACK to the broker.
-     *
-     * <p>The PUBACK control is eagerly acquired by the native layer as soon as the publish is received,
-     * before this callback is invoked. Calling this method retrieves the pre-acquired control handle.</p>
+     * at a later time to send the publish acknowledgement to the broker.
      *
      * <p><b>Important:</b> This method must be called within the
      * {@link Mqtt5ClientOptions.PublishEvents#onMessageReceived} callback. Calling it after the
@@ -55,8 +52,8 @@ public PublishPacket getPublishPacket() {
      * <p>This method may only be called once per received PUBLISH. Subsequent calls will throw
      * an {@link IllegalStateException}.</p>
      *
-     * <p>If this method is not called, the client will automatically send a PUBACK for QoS 1
-     * messages when the callback returns.</p>
+     * <p>If this method is not called, the client will automatically send a publish acknowledgment
+     * for QoS 1 messages when the callback returns.</p>
      *
      * @return A {@link Mqtt5PublishAcknowledgementControlHandle} that can be used to manually send the acknowledgement.
      * @throws IllegalStateException if called outside the onMessageReceived callback, called more than once,
@@ -85,7 +82,7 @@ public synchronized Mqtt5PublishAcknowledgementControlHandle acquirePublishAckno
      *
      * @return {@code true} if the user acquired manual control of the PUBACK, {@code false} otherwise.
      */
-    boolean wasControlAcquired() {
+    private boolean wasControlAcquired() {
         return controlAcquired;
     }
 
@@ -97,7 +94,7 @@ boolean wasControlAcquired() {
      * <p>Zeroes out {@code controlId} so that any saved reference to this {@code PublishReturn}
      * cannot call {@code acquirePublishAcknowledgementControl()} after the callback has returned.</p>
      */
-    synchronized void invalidateAfterCallback() {
+    private synchronized void invalidateAfterCallback() {
         controlId = 0;
     }
 

src/native/mqtt5_client.c

@@ -617,13 +617,19 @@ static void s_aws_mqtt5_client_java_publish_received(
     }
 
     /*
-     * After the callback returns, check whether the user called acquirePublishAcknowledgementControl()
-     * by calling wasControlAcquired() on the PublishReturn object.
-     *
-     * If wasControlAcquired() returns false (or an exception occurred), the user did NOT take
-     * manual control of the PUBACK, so we auto-invoke it to avoid losing it.
+     * After the callback returns:
+     * 1. Call invalidateAfterCallback() to zero out controlId in the PublishReturn, preventing
+     *    any post-callback call to acquirePublishAcknowledgementControl() from succeeding.
+     * 2. Call wasControlAcquired() to check whether the user took manual control during the
+     *    callback. If they did NOT, auto-invoke the PUBACK to avoid losing it.
      */
     if (control_id != 0 && publish_packet_return_data != NULL) {
+        /* Invalidate the PublishReturn to prevent post-callback use */
+        (*env)->CallVoidMethod(
+            env, publish_packet_return_data, mqtt5_publish_return_properties.return_invalidate_after_callback_id);
+        aws_jni_check_and_clear_exception(env); /* To hide JNI warning */
+
+        /* Check whether the user called acquirePublishAcknowledgementControl() during the callback */
         jboolean user_acquired_control = (*env)->CallBooleanMethod(
             env, publish_packet_return_data, mqtt5_publish_return_properties.return_was_control_acquired_id);
         aws_jni_check_and_clear_exception(env); /* To hide JNI warning */