[ECO-5506] Declared separate interface ObjectsCallback for async ops

- Updated ObjectsAsyncScope to handle ObjectsCallback
- Added launchWithVoidCallback method to handle void callbacks
- Added unit tests covering all scenarios for ObjectsAsyncScope

Author: sacOO7

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

@@ -1,6 +1,5 @@
 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;
@@ -33,7 +32,7 @@ public interface LiveCounter {
      * @param callback the callback to be invoked upon completion of the operation.
      */
     @NonBlocking
-    void incrementAsync(@NotNull Callback<Void> callback);
+    void incrementAsync(@NotNull ObjectsCallback<Void> callback);
 
     /**
      * Decrements the value of the counter by 1.
@@ -49,7 +48,7 @@ public interface LiveCounter {
      * @param callback the callback to be invoked upon completion of the operation.
      */
     @NonBlocking
-    void decrementAsync(@NotNull Callback<Void> callback);
+    void decrementAsync(@NotNull ObjectsCallback<Void> callback);
 
     /**
      * Retrieves the current value of the counter.

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

@@ -1,6 +1,5 @@
 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;
@@ -109,7 +108,7 @@ public interface LiveMap {
      * @param callback the callback to handle the result or any errors.
      */
     @NonBlocking
-    void setAsync(@NotNull String keyName, @NotNull Object value, @NotNull Callback<Void> callback);
+    void setAsync(@NotNull String keyName, @NotNull Object value, @NotNull ObjectsCallback<Void> callback);
 
     /**
      * Asynchronously removes the specified key and its associated value from the map.
@@ -122,5 +121,5 @@ public interface LiveMap {
      * @param callback the callback to handle the result or any errors.
      */
     @NonBlocking
-    void removeAsync(@NotNull String keyName, @NotNull Callback<Void> callback);
+    void removeAsync(@NotNull String keyName, @NotNull ObjectsCallback<Void> callback);
 }

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

@@ -1,7 +1,6 @@
 package io.ably.lib.objects;
 
 import io.ably.lib.objects.state.ObjectsStateChange;
-import io.ably.lib.types.Callback;
 import org.jetbrains.annotations.Blocking;
 import org.jetbrains.annotations.NonBlocking;
 import org.jetbrains.annotations.NotNull;
@@ -96,7 +95,7 @@ public interface LiveObjects extends ObjectsStateChange {
      * @param callback the callback to handle the result or error.
      */
     @NonBlocking
-    void getRootAsync(@NotNull Callback<@NotNull LiveMap> callback);
+    void getRootAsync(@NotNull ObjectsCallback<@NotNull LiveMap> callback);
 
     /**
      * Asynchronously creates a new LiveMap based on an existing LiveMap.
@@ -109,7 +108,7 @@ public interface LiveObjects extends ObjectsStateChange {
      * @param callback the callback to handle the result or error.
      */
     @NonBlocking
-    void createMapAsync(@NotNull LiveMap liveMap, @NotNull Callback<@NotNull LiveMap> callback);
+    void createMapAsync(@NotNull LiveMap liveMap, @NotNull ObjectsCallback<@NotNull LiveMap> callback);
 
     /**
      * Asynchronously creates a new LiveMap based on a LiveCounter.
@@ -122,7 +121,7 @@ public interface LiveObjects extends ObjectsStateChange {
      * @param callback the callback to handle the result or error.
      */
     @NonBlocking
-    void createMapAsync(@NotNull LiveCounter liveCounter, @NotNull Callback<@NotNull LiveMap> callback);
+    void createMapAsync(@NotNull LiveCounter liveCounter, @NotNull ObjectsCallback<@NotNull LiveMap> callback);
 
     /**
      * Asynchronously creates a new LiveMap based on a standard Java Map.
@@ -135,7 +134,7 @@ public interface LiveObjects extends ObjectsStateChange {
      * @param callback the callback to handle the result or error.
      */
     @NonBlocking
-    void createMapAsync(@NotNull Map<String, Object> map, @NotNull Callback<@NotNull LiveMap> callback);
+    void createMapAsync(@NotNull Map<String, Object> map, @NotNull ObjectsCallback<@NotNull LiveMap> callback);
 
     /**
      * Asynchronously creates a new LiveCounter with an initial value.
@@ -148,5 +147,5 @@ public interface LiveObjects extends ObjectsStateChange {
      * @param callback the callback to handle the result or error.
      */
     @NonBlocking
-    void createCounterAsync(@NotNull Long initialValue, @NotNull Callback<@NotNull LiveCounter> callback);
+    void createCounterAsync(@NotNull Long initialValue, @NotNull ObjectsCallback<@NotNull LiveCounter> callback);
 }

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

@@ -0,0 +1,31 @@
+package io.ably.lib.objects;
+
+import io.ably.lib.types.AblyException;
+
+/**
+ * Callback interface for handling results of asynchronous LiveObjects operations.
+ * Used for operations like creating LiveMaps/LiveCounters, modifying entries, and retrieving objects.
+ * Callbacks are executed on background threads managed by the LiveObjects system.
+ *
+ * @param <T> the type of the result returned by the asynchronous operation
+ */
+public interface ObjectsCallback<T> {
+
+    /**
+     * Called when the asynchronous operation completes successfully.
+     * For modification operations (set, remove, increment), result is typically Void.
+     * For creation/retrieval operations, result contains the created/retrieved object.
+     *
+     * @param result the result of the operation, may be null for modification operations
+     */
+    void onSuccess(T result);
+
+    /**
+     * Called when the asynchronous operation fails.
+     * The exception contains detailed error information including error codes and messages.
+     * Common errors include network issues, authentication failures, and validation errors.
+     *
+     * @param exception the exception that occurred during the operation
+     */
+    void onError(AblyException exception);
+}

live-objects/src/main/kotlin/io/ably/lib/objects/DefaultLiveObjects.kt

@@ -4,7 +4,6 @@ import io.ably.lib.objects.state.ObjectsStateChange
 import io.ably.lib.objects.state.ObjectsStateEvent
 import io.ably.lib.realtime.ChannelState
 import io.ably.lib.types.AblyException
-import io.ably.lib.types.Callback
 import io.ably.lib.types.ProtocolMessage
 import io.ably.lib.util.Log
 import kotlinx.coroutines.*
@@ -66,23 +65,23 @@ internal class DefaultLiveObjects(internal val channelName: String, internal val
     TODO("Not yet implemented")
   }
 
-  override fun getRootAsync(callback: Callback<LiveMap>) {
+  override fun getRootAsync(callback: ObjectsCallback<LiveMap>) {
     asyncScope.launchWithCallback(callback) { getRootAsync() }
   }
 
-  override fun createMapAsync(liveMap: LiveMap, callback: Callback<LiveMap>) {
+  override fun createMapAsync(liveMap: LiveMap, callback: ObjectsCallback<LiveMap>) {
     TODO("Not yet implemented")
   }
 
-  override fun createMapAsync(liveCounter: LiveCounter, callback: Callback<LiveMap>) {
+  override fun createMapAsync(liveCounter: LiveCounter, callback: ObjectsCallback<LiveMap>) {
     TODO("Not yet implemented")
   }
 
-  override fun createMapAsync(map: MutableMap<String, Any>, callback: Callback<LiveMap>) {
+  override fun createMapAsync(map: MutableMap<String, Any>, callback: ObjectsCallback<LiveMap>) {
     TODO("Not yet implemented")
   }
 
-  override fun createCounterAsync(initialValue: Long, callback: Callback<LiveCounter>) {
+  override fun createCounterAsync(initialValue: Long, callback: ObjectsCallback<LiveCounter>) {
     TODO("Not yet implemented")
   }
 

live-objects/src/main/kotlin/io/ably/lib/objects/Utils.kt

@@ -1,7 +1,6 @@
 package io.ably.lib.objects
 
 import io.ably.lib.types.AblyException
-import io.ably.lib.types.Callback
 import io.ably.lib.types.ErrorInfo
 import io.ably.lib.util.Log
 import kotlinx.coroutines.*
@@ -60,16 +59,40 @@ internal class ObjectsAsyncScope(channelName: String) {
   private val scope =
     CoroutineScope(Dispatchers.Default + CoroutineName(tag) + SupervisorJob())
 
-  internal fun <T> launchWithCallback(callback: Callback<T>, block: suspend () -> T) {
+  internal fun <T> launchWithCallback(callback: ObjectsCallback<T>, block: suspend () -> T) {
     scope.launch {
       try {
         val result = block()
         try { callback.onSuccess(result) } catch (t: Throwable) {
           Log.e(tag, "Error occurred while executing callback's onSuccess handler", t)
         } // catch and don't rethrow error from callback
       } catch (throwable: Throwable) {
-        val exception = throwable as? AblyException
-        callback.onError(exception?.errorInfo)
+        when (throwable) {
+          is AblyException -> { callback.onError(throwable) }
+          else -> {
+            val ex = ablyException("Error executing operation", ErrorCode.BadRequest, cause = throwable)
+            callback.onError(ex)
+          }
+        }
+      }
+    }
+  }
+
+  internal fun launchWithVoidCallback(callback: ObjectsCallback<Void>, block: suspend () -> Unit) {
+    scope.launch {
+      try {
+        block()
+        try { callback.onSuccess(null) } catch (t: Throwable) {
+          Log.e(tag, "Error occurred while executing callback's onSuccess handler", t)
+        } // catch and don't rethrow error from callback
+      } catch (throwable: Throwable) {
+        when (throwable) {
+          is AblyException -> { callback.onError(throwable) }
+          else -> {
+            val ex = ablyException("Error executing operation", ErrorCode.BadRequest, cause = throwable)
+            callback.onError(ex)
+          }
+        }
       }
     }
   }

live-objects/src/main/kotlin/io/ably/lib/objects/type/livecounter/DefaultLiveCounter.kt

@@ -5,7 +5,6 @@ import io.ably.lib.objects.ObjectOperation
 import io.ably.lib.objects.ObjectState
 import io.ably.lib.objects.type.BaseLiveObject
 import io.ably.lib.objects.type.ObjectType
-import io.ably.lib.types.Callback
 import java.util.concurrent.atomic.AtomicReference
 
 /**
@@ -38,15 +37,15 @@ internal class DefaultLiveCounter private constructor(
     TODO("Not yet implemented")
   }
 
-  override fun incrementAsync(callback: Callback<Void>) {
+  override fun incrementAsync(callback: ObjectsCallback<Void>) {
     TODO("Not yet implemented")
   }
 
   override fun decrement() {
     TODO("Not yet implemented")
   }
 
-  override fun decrementAsync(callback: Callback<Void>) {
+  override fun decrementAsync(callback: ObjectsCallback<Void>) {
     TODO("Not yet implemented")
   }
 

live-objects/src/main/kotlin/io/ably/lib/objects/type/livemap/DefaultLiveMap.kt

@@ -7,7 +7,6 @@ import io.ably.lib.objects.ObjectOperation
 import io.ably.lib.objects.ObjectState
 import io.ably.lib.objects.type.BaseLiveObject
 import io.ably.lib.objects.type.ObjectType
-import io.ably.lib.types.Callback
 import java.util.concurrent.ConcurrentHashMap
 import java.util.AbstractMap
 
@@ -94,11 +93,11 @@ internal class DefaultLiveMap private constructor(
     TODO("Not yet implemented")
   }
 
-  override fun setAsync(keyName: String, value: Any, callback: Callback<Void>) {
+  override fun setAsync(keyName: String, value: Any, callback: ObjectsCallback<Void>) {
     TODO("Not yet implemented")
   }
 
-  override fun removeAsync(keyName: String, callback: Callback<Void>) {
+  override fun removeAsync(keyName: String, callback: ObjectsCallback<Void>) {
     TODO("Not yet implemented")
   }