puback to publish acknowledgement. aws-c-mqtt -> v0.15.2

Author: sbSteveK

crt/aws-c-mqtt

@@ -203,17 +203,20 @@ public Mqtt5ClientOperationStatistics getOperationStatistics() {
     }
 
     /**
-     * Sends a PUBACK packet for a QoS 1 PUBLISH that was previously acquired for manual control.
+     * Sends a publish acknowledgement for a QoS 1 PUBLISH that was previously acquired
+     * for manual control.
      *
-     * <p>To use manual PUBACK control, call {@link PublishReturn#acquirePubackControl()} within
-     * the {@link Mqtt5ClientOptions.PublishEvents#onMessageReceived} callback of a QoS 1 PUBLISH to 
-     * obtain a {@link Mqtt5PubackControlHandle}. Then call this method to send the PUBACK.</p>
+     * <p>To use manual publish acknowledgement control, call
+     * {@link PublishReturn#acquirePublishAcknowledgementControl()} within the
+     * {@link Mqtt5ClientOptions.PublishEvents#onMessageReceived} callback of a QoS 1 PUBLISH to obtain a
+     * {@link Mqtt5PublishAcknowledgementControlHandle}. Then call this method to send the PUBACK.</p>
      *
-     * @param pubackControlHandle An opaque handle obtained from {@link PublishReturn#acquirePubackControl()}.
-     * @throws CrtRuntimeException If the native client returns an error when invoking the PUBACK.
+     * @param publishAcknowledgementControlHandle An opaque handle obtained from
+     *        {@link PublishReturn#acquirePublishAcknowledgementControl()}.
+     * @throws CrtRuntimeException If the native client returns an error when invoking the publish acknowledgement.
      */
-    public void invokePuback(Mqtt5PubackControlHandle pubackControlHandle) throws CrtRuntimeException {
-        mqtt5ClientInternalInvokePuback(getNativeHandle(), pubackControlHandle.getControlId());
+    public void invokePublishAcknowledgement(Mqtt5PublishAcknowledgementControlHandle publishAcknowledgementControlHandle) throws CrtRuntimeException {
+        mqtt5ClientInternalInvokePublishAcknowledgement(getNativeHandle(), publishAcknowledgementControlHandle.getControlId());
     }
 
     /**
@@ -291,5 +294,5 @@ private static native long mqtt5ClientNew(
     private static native void mqtt5ClientInternalUnsubscribe(long client, UnsubscribePacket unsubscribe_options, CompletableFuture<UnsubAckPacket> unsubscribe_suback);
     private static native void mqtt5ClientInternalWebsocketHandshakeComplete(long connection, byte[] marshalledRequest, Throwable throwable, long nativeUserData) throws CrtRuntimeException;
     private static native Mqtt5ClientOperationStatistics mqtt5ClientInternalGetOperationStatistics(long client);
-    private static native void mqtt5ClientInternalInvokePuback(long client, long controlId);
+    private static native void mqtt5ClientInternalInvokePublishAcknowledgement(long client, long controlId);
 }

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

@@ -0,0 +1,35 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0.
+ */
+package software.amazon.awssdk.crt.mqtt5;
+
+/**
+ * An opaque handle representing manual control over a publish acknowledgement for a received
+ * PUBLISH packet.
+ *
+ * <p>This class cannot be instantiated directly. Instances are only created by the CRT library.</p>
+ */
+public class Mqtt5PublishAcknowledgementControlHandle {
+
+    private final long controlId;
+
+    /**
+     * Creates a new Mqtt5PublishAcknowledgementControlHandle. Only called from native/JNI code.
+     *
+     * @param controlId The native publish acknowledgement control ID returned by
+     *                  aws_mqtt5_client_acquire_publish_acknowledgement.
+     */
+    Mqtt5PublishAcknowledgementControlHandle(long controlId) {
+        this.controlId = controlId;
+    }
+
+    /**
+     * Returns the native publish acknowledgement control ID. Used internally by JNI.
+     *
+     * @return The native publish acknowledgement control ID.
+     */
+    long getControlId() {
+        return controlId;
+    }
+}

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

@@ -15,7 +15,7 @@ public class PublishReturn {
     private PublishPacket publishPacket;
 
     /**
-     * Single-element long array holding the native manual PUBACK control context pointer.
+     * Single-element long array holding the native manual publish acknowledgement control context pointer.
      * Element [0] is the pointer value, valid only during the
      * {@link Mqtt5ClientOptions.PublishEvents#onMessageReceived} callback.
      * QoS 0 results in this being set to 0.
@@ -33,10 +33,10 @@ public PublishPacket getPublishPacket() {
     }
 
     /**
-     * Acquires manual control over the PUBACK for this QoS 1 PUBLISH message, preventing the
-     * client from automatically sending a PUBACK. The returned handle can be passed to
-     * {@link Mqtt5Client#invokePuback(Mqtt5PubackControlHandle)} at a later time to send the
-     * PUBACK to the broker.
+     * Acquires manual control over the publish acknowledgement (PUBACK) for this PUBLISH message,
+     * preventing the client from automatically sending a acknowledgement. The returned handle can be passed to
+     * {@link Mqtt5Client#invokePublishAcknowledgement(Mqtt5PublishAcknowledgementControlHandle)} at a later
+     * time to send the PUBACK to the broker.
      *
      * <p><b>Important:</b> This method must be called within the
      * {@link Mqtt5ClientOptions.PublishEvents#onMessageReceived} callback. Calling it after the
@@ -48,18 +48,19 @@ public PublishPacket getPublishPacket() {
      * <p>If this method is not called, the client will automatically send a PUBACK for QoS 1
      * messages when the callback returns.</p>
      *
-     * @return A {@link Mqtt5PubackControlHandle} that can be used to manually send the PUBACK.
-     * @throws IllegalStateException if called outside the onMessageReceived callback or called more than once.
+     * @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,
+     *                               or called on a QoS 0 message.
      */
-    public synchronized Mqtt5PubackControlHandle acquirePubackControl() {
+    public synchronized Mqtt5PublishAcknowledgementControlHandle acquirePublishAcknowledgementControl() {
         if (nativeContextPtrHolder == null || nativeContextPtrHolder[0] == 0) {
             throw new IllegalStateException(
-                "acquirePubackControl() must be called within the onMessageReceived callback and may only be called once.");
+                "acquirePublishAcknowledgementControl() must be called within the onMessageReceived callback and may only be called once.");
         }
-        long controlId = mqtt5AcquirePubackControl(nativeContextPtrHolder[0]);
+        long controlId = mqtt5AcquirePublishAcknowledgementControl(nativeContextPtrHolder[0]);
         /* We set the array element to 0 so it can't be double-called */
         nativeContextPtrHolder[0] = 0;
-        return new Mqtt5PubackControlHandle(controlId);
+        return new Mqtt5PublishAcknowledgementControlHandle(controlId);
     }
 
     /**
@@ -68,17 +69,18 @@ public synchronized Mqtt5PubackControlHandle acquirePubackControl() {
      * after the onMessageReceived callback returns to prevent use-after-free.
      *
      * @param newPublishPacket The PublishPacket data received from the server.
-     * @param nativeContextPtrHolder Single-element long[] holding the native PUBACK control context pointer.
+     * @param nativeContextPtrHolder Single-element long[] holding the native publish acknowledgement control
+     *                               context pointer.
      */
     private PublishReturn(PublishPacket newPublishPacket, long[] nativeContextPtrHolder) {
         this.publishPacket = newPublishPacket;
         this.nativeContextPtrHolder = nativeContextPtrHolder;
     }
 
     /**
-     * Calls the native aws_mqtt5_client_acquire_puback function.
-     * @param nativeContextPtr Pointer to the native manual PUBACK control context.
-     * @return The native puback control ID.
+     * Calls the native aws_mqtt5_client_acquire_publish_acknowledgement function.
+     * @param nativeContextPtr Pointer to the native manual publish acknowledgement control context.
+     * @return The native publish acknowledgement control ID.
      */
-    private static native long mqtt5AcquirePubackControl(long nativeContextPtr);
-}
+    private static native long mqtt5AcquirePublishAcknowledgementControl(long nativeContextPtr);
+}

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

@@ -38,8 +38,8 @@ struct aws_mqtt5_client_publish_return_data {
     jobject jni_publish_future;
 };
 
-/* Context for manual PUBACK control. Valid only during the publish received callback. */
-struct manual_puback_control_context {
+/* Context for manual publish acknowledgement control. Valid only during the publish received callback. */
+struct manual_publish_acknowledgement_control_context {
     struct aws_mqtt5_client *client;
     const struct aws_mqtt5_packet_publish_view *publish_packet;
 };
@@ -586,12 +586,12 @@ static void s_aws_mqtt5_client_java_publish_received(
         goto clean_up;
     }
 
-    /* Create manual PUBACK control context (valid only during this callback)
+    /* Create manual publish acknowledgement control context (valid only during this callback).
      * We clean this before clean_up since we don't want to create this early and we can be sure to
      * hit the aws_mem_release AFTER we return from the publish events callback.
      */
-    struct manual_puback_control_context *control_context =
-        aws_mem_calloc(aws_jni_get_allocator(), 1, sizeof(struct manual_puback_control_context));
+    struct manual_publish_acknowledgement_control_context *control_context =
+        aws_mem_calloc(aws_jni_get_allocator(), 1, sizeof(struct manual_publish_acknowledgement_control_context));
 
     /*
      * Create a single-element long[] array to hold the native context pointer.
@@ -603,14 +603,15 @@ static void s_aws_mqtt5_client_java_publish_received(
     control_context->publish_packet = publish;
 
     context_ptr_holder = (*env)->NewLongArray(env, 1);
-    /* If allocation failed, Java will throw IllegalStateException on acquirePubackControl(). */
+    /* If allocation failed, Java will throw IllegalStateException on acquirePublishAcknowledgementControl(). */
     if (context_ptr_holder != NULL) {
         /*
-         * Only expose the context pointer for QoS 1 publishes. For QoS 0, there is no PUBACK
-         * to send, so acquirePubackControl() should throw IllegalStateException. We pass 0 (null).
+         * Only expose the context pointer for QoS 1 publishes. For QoS 0, there is no publish
+         * acknowledgement to send, so acquirePublishAcknowledgementControl() should throw
+         * IllegalStateException. We pass 0 (null).
          */
         jlong context_ptr_value = (publish->qos == AWS_MQTT5_QOS_AT_MOST_ONCE) ? 0 : (jlong)(uintptr_t)control_context;
-        /* Assigning the pointer to the allocated manual_puback_control_context to the single-element of the array */
+        /* Assigning the pointer to the allocated manual_publish_acknowledgement_control_context to the array */
         (*env)->SetLongArrayRegion(env, context_ptr_holder, 0, 1, &context_ptr_value);
     }
 
@@ -636,7 +637,7 @@ static void s_aws_mqtt5_client_java_publish_received(
 
     /*
      * Invalidate the context pointer in the long[] array now that the callback has returned.
-     * This prevents use-after-free if acquirePubackControl() is called after the callback.
+     * This prevents use-after-free if acquirePublishAcknowledgementControl() is called after the callback.
      * SetLongArrayRegion requires no extra JNI method ID.
      */
     if (context_ptr_holder != NULL) {
@@ -2225,18 +2226,18 @@ JNIEXPORT void JNICALL Java_software_amazon_awssdk_crt_mqtt5_Mqtt5Client_mqtt5Cl
 }
 
 /*******************************************************************************
- * Manual PUBACK Control Functions
+ * Manual Publish Acknowledgement Control Functions
  ******************************************************************************/
 
 /**
- * Called from PublishReturn.mqtt5AcquirePubackControl(long nativeContextPtr).
- * Calls aws_mqtt5_client_acquire_puback to take manual control of the PUBACK
- * for the received PUBLISH packet. Returns the puback_control_id as a jlong.
+ * Called from PublishReturn.mqtt5AcquirePublishAcknowledgementControl(long nativeContextPtr).
+ * Calls aws_mqtt5_client_acquire_publish_acknowledgement to take manual control of the publish
+ * acknowledgement (PUBACK) for the received PUBLISH packet. Returns the pub_ack_control_id as a jlong.
  *
  * This must be called within the onMessageReceived callback while the
  * native context pointer is still valid.
  */
-JNIEXPORT jlong JNICALL Java_software_amazon_awssdk_crt_mqtt5_PublishReturn_mqtt5AcquirePubackControl(
+JNIEXPORT jlong JNICALL Java_software_amazon_awssdk_crt_mqtt5_PublishReturn_mqtt5AcquirePublishAcknowledgementControl(
     JNIEnv *env,
     jclass jni_class,
     jlong native_context_ptr) {
@@ -2246,53 +2247,58 @@ JNIEXPORT jlong JNICALL Java_software_amazon_awssdk_crt_mqtt5_PublishReturn_mqtt
     if (native_context_ptr == 0) {
         aws_jni_throw_runtime_exception(
             env,
-            "PublishReturn.acquirePubackControl: context is no longer valid. "
-            "acquirePubackControl() must be called within the onMessageReceived callback.");
+            "PublishReturn.acquirePublishAcknowledgementControl: context is no longer valid. "
+            "acquirePublishAcknowledgementControl() must be called within the onMessageReceived callback.");
         return 0;
     }
 
-    struct manual_puback_control_context *context =
-        (struct manual_puback_control_context *)(uintptr_t)native_context_ptr;
+    struct manual_publish_acknowledgement_control_context *context =
+        (struct manual_publish_acknowledgement_control_context *)(uintptr_t)native_context_ptr;
 
     if (!context->client || !context->publish_packet) {
         aws_jni_throw_runtime_exception(
-            env, "PublishReturn.acquirePubackControl: invalid native PUBACK control context");
+            env,
+            "PublishReturn.acquirePublishAcknowledgementControl: invalid native publish acknowledgement control "
+            "context");
         return 0;
     }
 
-    uint64_t control_id = aws_mqtt5_client_acquire_puback(context->client, context->publish_packet);
+    uint64_t control_id = aws_mqtt5_client_acquire_publish_acknowledgement(context->client, context->publish_packet);
     return (jlong)control_id;
 }
 
 /**
- * Called from Mqtt5Client.mqtt5ClientInternalInvokePuback(long client, long controlId).
- * Calls aws_mqtt5_client_invoke_puback to send the PUBACK for a previously acquired
- * manual PUBACK control handle.
+ * Called from Mqtt5Client.mqtt5ClientInternalInvokePublishAcknowledgement(long client, long controlId).
+ * Calls aws_mqtt5_client_invoke_publish_acknowledgement to send the publish acknowledgement (PUBACK)
+ * for a previously acquired manual publish acknowledgement control handle.
  */
-JNIEXPORT void JNICALL Java_software_amazon_awssdk_crt_mqtt5_Mqtt5Client_mqtt5ClientInternalInvokePuback(
-    JNIEnv *env,
-    jclass jni_class,
-    jlong jni_client,
-    jlong control_id) {
+JNIEXPORT void JNICALL
+    Java_software_amazon_awssdk_crt_mqtt5_Mqtt5Client_mqtt5ClientInternalInvokePublishAcknowledgement(
+        JNIEnv *env,
+        jclass jni_class,
+        jlong jni_client,
+        jlong control_id) {
     (void)jni_class;
     aws_cache_jni_ids(env);
 
     struct aws_mqtt5_client_java_jni *java_client = (struct aws_mqtt5_client_java_jni *)jni_client;
     if (!java_client) {
         s_aws_mqtt5_client_log_and_throw_exception(
-            env, "Mqtt5Client.invokePuback: Invalid/null client", AWS_ERROR_INVALID_ARGUMENT);
+            env, "Mqtt5Client.invokePublishAcknowledgement: Invalid/null client", AWS_ERROR_INVALID_ARGUMENT);
         return;
     }
     if (!java_client->client) {
         s_aws_mqtt5_client_log_and_throw_exception(
-            env, "Mqtt5Client.invokePuback: Invalid/null native client", AWS_ERROR_INVALID_ARGUMENT);
+            env, "Mqtt5Client.invokePublishAcknowledgement: Invalid/null native client", AWS_ERROR_INVALID_ARGUMENT);
         return;
     }
 
-    int result = aws_mqtt5_client_invoke_puback(java_client->client, (uint64_t)control_id, NULL);
+    int result = aws_mqtt5_client_invoke_publish_acknowledgement(java_client->client, (uint64_t)control_id, NULL);
     if (result != AWS_OP_SUCCESS) {
         s_aws_mqtt5_client_log_and_throw_exception(
-            env, "Mqtt5Client.invokePuback: aws_mqtt5_client_invoke_puback failed!", aws_last_error());
+            env,
+            "Mqtt5Client.invokePublishAcknowledgement: aws_mqtt5_client_invoke_publish_acknowledgement failed!",
+            aws_last_error());
     }
 }