Merge pull request #1085 from ably/feature/liveobject-plugin-setup

Setup : LiveObject plugin

Author: sacOO7

android/build.gradle.kts

@@ -51,6 +51,7 @@ android {
 dependencies {
     api(libs.gson)
     implementation(libs.bundles.common)
+    compileOnly(libs.jetbrains)
     testImplementation(libs.bundles.tests)
     implementation(project(":network-client-core"))
     runtimeOnly(project(":network-client-default"))

android/src/main/java/io/ably/lib/realtime/Channel.java

@@ -3,6 +3,8 @@
 import io.ably.lib.types.AblyException;
 import io.ably.lib.types.ChannelOptions;
 import io.ably.lib.push.PushChannel;
+import io.ably.lib.objects.LiveObjectsPlugin;
+
 
 public class Channel extends ChannelBase {
     /**
@@ -12,8 +14,8 @@ public class Channel extends ChannelBase {
      */
     public final PushChannel push;
 
-    Channel(AblyRealtime ably, String name, ChannelOptions options) throws AblyException {
-        super(ably, name, options);
+    Channel(AblyRealtime ably, String name, ChannelOptions options, LiveObjectsPlugin liveObjectsPlugin) throws AblyException {
+        super(ably, name, options, liveObjectsPlugin);
         this.push = ((io.ably.lib.rest.AblyRest) ably).channels.get(name, options).push;
     }
 

gradle/libs.versions.toml

@@ -22,6 +22,7 @@ test-retry = "1.6.0"
 kotlin = "2.1.10"
 coroutine = "1.9.0"
 turbine = "1.2.0"
+jetbrains-annoations = "26.0.2"
 
 [libraries]
 gson = { group = "com.google.code.gson", name = "gson", version.ref = "gson" }
@@ -47,6 +48,7 @@ okhttp = { group = "com.squareup.okhttp3", name = "okhttp", version.ref = "okhtt
 coroutine-core = { group = "org.jetbrains.kotlinx", name = "kotlinx-coroutines-core", version.ref = "coroutine" }
 coroutine-test = { group = "org.jetbrains.kotlinx", name = "kotlinx-coroutines-test", version.ref = "coroutine" }
 turbine = { group = "app.cash.turbine", name = "turbine", version.ref = "turbine" }
+jetbrains = { group = "org.jetbrains", name = "annotations", version.ref = "jetbrains-annoations" }
 
 [bundles]
 common = ["msgpack", "vcdiff-core"]

java/build.gradle.kts

@@ -20,6 +20,7 @@ tasks.withType<Jar> {
 dependencies {
     api(libs.gson)
     implementation(libs.bundles.common)
+    compileOnly(libs.jetbrains)
     implementation(project(":network-client-core"))
     if (findProperty("okhttp") == null) {
         runtimeOnly(project(":network-client-default"))

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

@@ -1,11 +1,12 @@
 package io.ably.lib.realtime;
 
+import io.ably.lib.objects.LiveObjectsPlugin;
 import io.ably.lib.types.AblyException;
 import io.ably.lib.types.ChannelOptions;
 
 public class Channel extends ChannelBase {
-    Channel(AblyRealtime ably, String name, ChannelOptions options) throws AblyException {
-        super(ably, name, options);
+    Channel(AblyRealtime ably, String name, ChannelOptions options, LiveObjectsPlugin liveObjectsPlugin) throws AblyException {
+        super(ably, name, options, liveObjectsPlugin);
     }
 
     public interface MessageListener extends ChannelBase.MessageListener {}

lib/src/main/java/io/ably/lib/objects/LiveCounter.java

@@ -0,0 +1,62 @@
+package io.ably.lib.objects;
+
+import io.ably.lib.types.Callback;
+import org.jetbrains.annotations.Blocking;
+import org.jetbrains.annotations.NonBlocking;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Contract;
+
+/**
+ * The LiveCounter interface provides methods to interact with a live counter.
+ * It allows incrementing, decrementing, and retrieving the current value of the counter,
+ * both synchronously and asynchronously.
+ */
+public interface LiveCounter {
+
+    /**
+     * Increments the value of the counter by 1.
+     * Send a COUNTER_INC operation to the realtime system to increment a value on this LiveCounter object.
+     * This does not modify the underlying data of this LiveCounter object. Instead, the change will be applied when
+     * the published COUNTER_INC operation is echoed back to the client and applied to the object following the regular
+     * operation application procedure.
+     */
+    @Blocking
+    void increment();
+
+    /**
+     * Increments the value of the counter by 1 asynchronously.
+     * Send a COUNTER_INC operation to the realtime system to increment a value on this LiveCounter object.
+     * This does not modify the underlying data of this LiveCounter object. Instead, the change will be applied when
+     * the published COUNTER_INC operation is echoed back to the client and applied to the object following the regular
+     * operation application procedure.
+     *
+     * @param callback the callback to be invoked upon completion of the operation.
+     */
+    @NonBlocking
+    void incrementAsync(@NotNull Callback<Void> callback);
+
+    /**
+     * Decrements the value of the counter by 1.
+     * An alias for calling {@link LiveCounter#increment()} with a negative amount.
+     */
+    @Blocking
+    void decrement();
+
+    /**
+     * Decrements the value of the counter by 1 asynchronously.
+     * An alias for calling {@link LiveCounter#increment()} with a negative amount.
+     *
+     * @param callback the callback to be invoked upon completion of the operation.
+     */
+    @NonBlocking
+    void decrementAsync(@NotNull Callback<Void> callback);
+
+    /**
+     * Retrieves the current value of the counter.
+     *
+     * @return the current value of the counter as a Long.
+     */
+    @NotNull
+    @Contract(pure = true) // Indicates this method does not modify the state of the object.
+    Long value();
+}

lib/src/main/java/io/ably/lib/objects/LiveMap.java

@@ -0,0 +1,121 @@
+package io.ably.lib.objects;
+
+import io.ably.lib.types.Callback;
+import org.jetbrains.annotations.Blocking;
+import org.jetbrains.annotations.NonBlocking;
+import org.jetbrains.annotations.Contract;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+import org.jetbrains.annotations.Unmodifiable;
+
+import java.util.Map;
+
+/**
+ * The LiveMap interface provides methods to interact with a live, real-time map structure.
+ * It supports both synchronous and asynchronous operations for managing key-value pairs.
+ */
+public interface LiveMap {
+
+    /**
+     * Retrieves the value associated with the specified key.
+     * If this map object is tombstoned (deleted), `undefined` is returned.
+     * If no entry is associated with the specified key, `undefined` is returned.
+     * If map entry is tombstoned (deleted), `undefined` is returned.
+     * If the value associated with the provided key is an objectId string of another LiveObject, a reference to that LiveObject
+     * is returned, provided it exists in the local pool and is not tombstoned. Otherwise, `undefined` is returned.
+     * If the value is not an objectId, then that value is returned.
+     *
+     * @param keyName the key whose associated value is to be returned.
+     * @return the value associated with the specified key, or null if the key does not exist.
+     */
+    @Nullable
+    Object get(@NotNull String keyName);
+
+    /**
+     * Retrieves all entries (key-value pairs) in the map.
+     *
+     * @return an iterable collection of all entries in the map.
+     */
+    @NotNull
+    @Unmodifiable
+    Iterable<Map.Entry<String, Object>> entries();
+
+    /**
+     * Retrieves all keys in the map.
+     *
+     * @return an iterable collection of all keys in the map.
+     */
+    @NotNull
+    @Unmodifiable
+    Iterable<String> keys();
+
+    /**
+     * Retrieves all values in the map.
+     *
+     * @return an iterable collection of all values in the map.
+     */
+    @NotNull
+    @Unmodifiable
+    Iterable<Object> values();
+
+    /**
+     * Sets the specified key to the given value in the map.
+     * Send a MAP_SET operation to the realtime system to set a key on this LiveMap object to a specified value.
+     * This does not modify the underlying data of this LiveMap object. Instead, the change will be applied when
+     * the published MAP_SET operation is echoed back to the client and applied to the object following the regular
+     * operation application procedure.
+     *
+     * @param keyName the key to be set.
+     * @param value the value to be associated with the key.
+     */
+    @Blocking
+    void set(@NotNull String keyName, @NotNull Object value);
+
+    /**
+     * Removes the specified key and its associated value from the map.
+     * Send a MAP_REMOVE operation to the realtime system to tombstone a key on this LiveMap object.
+     * This does not modify the underlying data of this LiveMap object. Instead, the change will be applied when
+     * the published MAP_REMOVE operation is echoed back to the client and applied to the object following the regular
+     * operation application procedure.
+     *
+     * @param keyName the key to be removed.
+     */
+    @Blocking
+    void remove(@NotNull String keyName);
+
+    /**
+     * Retrieves the number of entries in the map.
+     *
+     * @return the size of the map.
+     */
+    @Contract(pure = true) // Indicates this method does not modify the state of the object.
+    @NotNull
+    Long size();
+
+    /**
+     * Asynchronously sets the specified key to the given value in the map.
+     * Send a MAP_SET operation to the realtime system to set a key on this LiveMap object to a specified value.
+     * This does not modify the underlying data of this LiveMap object. Instead, the change will be applied when
+     * the published MAP_SET operation is echoed back to the client and applied to the object following the regular
+     * operation application procedure.
+     *
+     * @param keyName the key to be set.
+     * @param value the value to be associated with the key.
+     * @param callback the callback to handle the result or any errors.
+     */
+    @NonBlocking
+    void setAsync(@NotNull String keyName, @NotNull Object value, @NotNull Callback<Void> callback);
+
+    /**
+     * Asynchronously removes the specified key and its associated value from the map.
+     * Send a MAP_REMOVE operation to the realtime system to tombstone a key on this LiveMap object.
+     * This does not modify the underlying data of this LiveMap object. Instead, the change will be applied when
+     * the published MAP_REMOVE operation is echoed back to the client and applied to the object following the regular
+     * operation application procedure.
+     *
+     * @param keyName  the key to be removed.
+     * @param callback the callback to handle the result or any errors.
+     */
+    @NonBlocking
+    void removeAsync(@NotNull String keyName, @NotNull Callback<Void> callback);
+}