Merge pull request #1182 from ably/AIT-99/message-appends

[AIT-99] feat: protocol v5 + message appends

Author: ttypic

.github/workflows/integration-test.yml

@@ -19,7 +19,7 @@ jobs:
         uses: actions/setup-java@v4
         with:
           java-version: '17'
-          distribution: 'temurin'
+          distribution: 'corretto'
 
       - name: Set up Gradle
         uses: gradle/actions/setup-gradle@v3

java/build.gradle.kts

@@ -79,6 +79,8 @@ tasks.register<Test>("testRestSuite") {
     }
     jvmArgs("--add-opens", "java.base/java.time=ALL-UNNAMED")
     jvmArgs("--add-opens", "java.base/java.lang=ALL-UNNAMED")
+    jvmArgs("--add-opens", "java.base/java.net=ALL-UNNAMED")
+    jvmArgs("--add-opens", "java.base/java.lang.reflect=ALL-UNNAMED")
     beforeTest(closureOf<TestDescriptor> { logger.lifecycle("-> $this") })
     outputs.upToDateWhen { false }
     testLogging {

lib/src/main/java/io/ably/lib/realtime/ChannelBase.java

@@ -43,11 +43,14 @@
 import io.ably.lib.types.ProtocolMessage.Action;
 import io.ably.lib.types.ProtocolMessage.Flag;
 import io.ably.lib.types.Summary;
+import io.ably.lib.types.UpdateDeleteResult;
 import io.ably.lib.util.CollectionUtils;
 import io.ably.lib.util.EventEmitter;
 import io.ably.lib.util.Log;
 import io.ably.lib.util.ReconnectionStrategy;
 import io.ably.lib.util.StringUtils;
+import org.jetbrains.annotations.Blocking;
+import org.jetbrains.annotations.NonBlocking;
 import org.jetbrains.annotations.Nullable;
 
 /**
@@ -1214,9 +1217,10 @@ public void getMessageAsync(String serial, Callback<Message> callback) {
      *                Only non-null fields will be applied to the existing message.
      * @param operation operation metadata such as clientId, description, or metadata in the version field
      * @throws AblyException If the update operation fails.
+     * @return A {@link UpdateDeleteResult} containing the updated message version serial.
      */
-    public void updateMessage(Message message, MessageOperation operation) throws AblyException {
-        messageEditsMixin.updateMessage(ably.http, message, operation);
+    public UpdateDeleteResult updateMessage(Message message, MessageOperation operation) throws AblyException {
+        return messageEditsMixin.updateMessage(ably.http, message, operation);
     }
 
     /**
@@ -1228,34 +1232,35 @@ public void updateMessage(Message message, MessageOperation operation) throws Ab
      * @param message A {@link Message} object containing the fields to update and the serial identifier.
      *                Only non-null fields will be applied to the existing message.
      * @throws AblyException If the update operation fails.
+     * @return A {@link UpdateDeleteResult} containing the updated message version serial.
      */
-    public void updateMessage(Message message) throws AblyException {
-        updateMessage(message, null);
+    public UpdateDeleteResult updateMessage(Message message) throws AblyException {
+        return updateMessage(message, null);
     }
 
     /**
      * Asynchronously updates an existing message.
      *
      * @param message A {@link Message} object containing the fields to update and the serial identifier.
      * @param operation operation metadata such as clientId, description, or metadata in the version field
-     * @param listener A listener to be notified of the outcome of this operation.
+     * @param callback A callback to be notified of the outcome of this operation.
      * <p>
-     * This listener is invoked on a background thread.
+     * This callback is invoked on a background thread.
      */
-    public void updateMessageAsync(Message message, MessageOperation operation, CompletionListener listener) {
-        messageEditsMixin.updateMessageAsync(ably.http, message, operation, listener);
+    public void updateMessageAsync(Message message, MessageOperation operation, Callback<UpdateDeleteResult> callback) {
+        messageEditsMixin.updateMessageAsync(ably.http, message, operation, callback);
     }
 
     /**
      * Asynchronously updates an existing message.
      *
      * @param message A {@link Message} object containing the fields to update and the serial identifier.
-     * @param listener A listener to be notified of the outcome of this operation.
+     * @param callback A callback to be notified of the outcome of this operation.
      * <p>
-     * This listener is invoked on a background thread.
+     * This callback is invoked on a background thread.
      */
-    public void updateMessageAsync(Message message, CompletionListener listener) {
-        updateMessageAsync(message, null, listener);
+    public void updateMessageAsync(Message message, Callback<UpdateDeleteResult> callback) {
+        updateMessageAsync(message, null, callback);
     }
 
     /**
@@ -1268,9 +1273,10 @@ public void updateMessageAsync(Message message, CompletionListener listener) {
      * @param message A {@link Message} message containing the serial identifier.
      * @param operation operation metadata such as clientId, description, or metadata in the version field
      * @throws AblyException If the delete operation fails.
+     * @return A {@link UpdateDeleteResult} containing the deleted message version serial.
      */
-    public void deleteMessage(Message message, MessageOperation operation) throws AblyException {
-        messageEditsMixin.deleteMessage(ably.http, message, operation);
+    public UpdateDeleteResult deleteMessage(Message message, MessageOperation operation) throws AblyException {
+        return messageEditsMixin.deleteMessage(ably.http, message, operation);
     }
 
     /**
@@ -1282,34 +1288,83 @@ public void deleteMessage(Message message, MessageOperation operation) throws Ab
      *
      * @param message A {@link Message} message containing the serial identifier.
      * @throws AblyException If the delete operation fails.
+     * @return A {@link UpdateDeleteResult} containing the deleted message version serial.
      */
-    public void deleteMessage(Message message) throws AblyException {
-        deleteMessage(message, null);
+    public UpdateDeleteResult deleteMessage(Message message) throws AblyException {
+        return deleteMessage(message, null);
     }
 
     /**
      * Asynchronously marks a message as deleted.
      *
      * @param message A {@link Message} object containing the serial identifier and operation metadata.
      * @param operation operation metadata such as clientId, description, or metadata in the version field
-     * @param listener A listener to be notified of the outcome of this operation.
+     * @param callback A callback to be notified of the outcome of this operation.
      * <p>
-     * This listener is invoked on a background thread.
+     * This callback is invoked on a background thread.
      */
-    public void deleteMessageAsync(Message message, MessageOperation operation, CompletionListener listener) {
-        messageEditsMixin.deleteMessageAsync(ably.http, message, operation, listener);
+    public void deleteMessageAsync(Message message, MessageOperation operation, Callback<UpdateDeleteResult> callback) {
+        messageEditsMixin.deleteMessageAsync(ably.http, message, operation, callback);
     }
 
     /**
      * Asynchronously marks a message as deleted.
      *
      * @param message A {@link Message} object containing the serial identifier and operation metadata.
-     * @param listener A listener to be notified of the outcome of this operation.
+     * @param callback A callback to be notified of the outcome of this operation.
      * <p>
-     * This listener is invoked on a background thread.
+     * This callback is invoked on a background thread.
+     */
+    public void deleteMessageAsync(Message message, Callback<UpdateDeleteResult> callback) {
+        deleteMessageAsync(message, null, callback);
+    }
+
+    /**
+     * Appends message text to the end of the message data.
+     *
+     * @param message  A {@link Message} object containing the serial identifier and data to append.
+     * @param operation operation details such as clientId, description, or metadata
+     * @return A {@link UpdateDeleteResult} containing the updated message version serial.
+     * @throws AblyException If the append operation fails.
+     */
+    public UpdateDeleteResult appendMessage(Message message, MessageOperation operation) throws AblyException {
+        return messageEditsMixin.appendMessage(ably.http, message, operation);
+    }
+
+    /**
+     * Appends message text to the end of the message.
+     *
+     * @param message  A {@link Message} object containing the serial identifier and data to append.
+     * @return A {@link UpdateDeleteResult} containing the updated message version serial.
+     * @throws AblyException If the append operation fails.
+     */
+    public UpdateDeleteResult appendMessage(Message message) throws AblyException {
+        return appendMessage(message, null);
+    }
+
+    /**
+     * Asynchronously appends message text to the end of the message.
+     *
+     * @param message  A {@link Message} object containing the serial identifier and data to append.
+     * @param operation operation details such as clientId, description, or metadata
+     * @param callback A callback to be notified of the outcome of this operation.
+     * <p>
+     * This callback is invoked on a background thread.
+     */
+    public void appendMessageAsync(Message message, MessageOperation operation, Callback<UpdateDeleteResult> callback) {
+        messageEditsMixin.appendMessageAsync(ably.http, message, operation, callback);
+    }
+
+    /**
+     * Asynchronously appends message text to the end of the message.
+     *
+     * @param message  A {@link Message} object containing the serial identifier and data to append.
+     * @param callback A callback to be notified of the outcome of this operation.
+     * <p>
+     * This callback is invoked on a background thread.
      */
-    public void deleteMessageAsync(Message message, CompletionListener listener) {
-        deleteMessageAsync(message, null, listener);
+    public void appendMessageAsync(Message message, Callback<UpdateDeleteResult> callback) {
+        appendMessageAsync(message, null, callback);
     }
 
     /**
@@ -1325,6 +1380,7 @@ public void deleteMessageAsync(Message message, CompletionListener listener) {
      *         representing all versions of the message.
      * @throws AblyException If the versions cannot be retrieved.
      */
+    @Blocking
     public PaginatedResult<Message> getMessageVersions(String serial, Param[] params) throws AblyException {
         return messageEditsMixin.getMessageVersions(ably.http, serial, params);
     }
@@ -1336,6 +1392,7 @@ public PaginatedResult<Message> getMessageVersions(String serial, Param[] params
      * @param params Query parameters for filtering or pagination.
      * @param callback A callback to handle the result asynchronously.
      */
+    @NonBlocking
     public void getMessageVersionsAsync(String serial, Param[] params, Callback<AsyncPaginatedResult<Message>> callback) throws AblyException {
         messageEditsMixin.getMessageVersionsAsync(ably.http, serial, params, callback);
     }