[ECO-5479] Defined and implemented ObjectLifecycleChange interface

- Updated LiveMap and LiveCounter to extend ObjectLifecycleChange interface
- Implemented ObjectLifecycleCoordinator by extending ObjectLifecycleChange
- Updated testObjectDelete with relevant assertions for ObjectLifecycleEvent.DELETED

Author: sacOO7

lib/src/main/java/io/ably/lib/objects/type/ObjectLifecycleChange.java

@@ -0,0 +1,69 @@
+package io.ably.lib.objects.type;
+
+import io.ably.lib.objects.ObjectsSubscription;
+import org.jetbrains.annotations.NonBlocking;
+import org.jetbrains.annotations.NotNull;
+
+/**
+ * Interface for managing subscriptions to Object lifecycle events.
+ * <p>
+ * This interface provides methods to subscribe to and manage notifications about significant lifecycle
+ * changes that occur to Object, such as deletion. More events can be added in the future.
+ * Multiple listeners can be registered independently, and each can be managed separately.
+ * <p>
+ * Lifecycle events are different from data update events - they represent changes
+ * to the object's existence state rather than changes to the object's data content.
+ *
+ * @see ObjectLifecycleEvent for the available lifecycle events
+ */
+public interface ObjectLifecycleChange {
+    /**
+     * Subscribes to a specific Object lifecycle event.
+     *
+     * <p>This method registers the provided listener to be notified when the specified
+     * lifecycle event occurs. The returned subscription can be used to
+     * unsubscribe later when the notifications are no longer needed.
+     *
+     * @param event the lifecycle event to subscribe to
+     * @param listener the listener that will be called when the event occurs
+     * @return a subscription object that can be used to unsubscribe from the event
+     */
+    @NonBlocking
+    ObjectsSubscription on(@NotNull ObjectLifecycleEvent event, @NotNull ObjectLifecycleChange.Listener listener);
+
+    /**
+     * Unsubscribes the specified listener from all lifecycle events.
+     *
+     * <p>After calling this method, the provided listener will no longer receive
+     * any lifecycle event notifications.
+     *
+     * @param listener the listener to unregister from all events
+     */
+    @NonBlocking
+    void off(@NotNull ObjectLifecycleChange.Listener listener);
+
+    /**
+     * Unsubscribes all listeners from all lifecycle events.
+     *
+     * <p>After calling this method, no listeners will receive any lifecycle
+     * event notifications until new listeners are registered.
+     */
+    @NonBlocking
+    void offAll();
+
+    /**
+     * Interface for receiving notifications about Object lifecycle changes.
+     * <p>
+     * Implement this interface and register it with an ObjectLifecycleChange provider
+     * to be notified when lifecycle events occur, such as object creation or deletion.
+     */
+    @FunctionalInterface
+    interface Listener {
+        /**
+         * Called when a lifecycle event occurs.
+         *
+         * @param lifecycleEvent The lifecycle event that occurred
+         */
+        void onLifecycleEvent(@NotNull ObjectLifecycleEvent lifecycleEvent);
+    }
+}

lib/src/main/java/io/ably/lib/objects/type/ObjectLifecycleEvent.java

@@ -0,0 +1,17 @@
+package io.ably.lib.objects.type;
+
+/**
+ * Represents lifecycle events a Object in the Ably system.
+ * <p>
+ * This enum notifies listeners about significant lifecycle changes
+ * that occur to an Object during its lifetime. Clients can register a
+ * {@link ObjectLifecycleChange.Listener} to receive these events.
+ */
+public enum ObjectLifecycleEvent {
+    /**
+     * Indicates that an Object has been deleted (tombstoned).
+     * Emitted once when the object is tombstoned server-side (i.e., deleted and no longer addressable).
+     * Not re-emitted during client-side garbage collection of tombstones.
+     */
+    DELETED
+}

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

@@ -1,6 +1,7 @@
 package io.ably.lib.objects.type.counter;
 
 import io.ably.lib.objects.ObjectsCallback;
+import io.ably.lib.objects.type.ObjectLifecycleChange;
 import org.jetbrains.annotations.Blocking;
 import org.jetbrains.annotations.NonBlocking;
 import org.jetbrains.annotations.NotNull;
@@ -11,7 +12,7 @@
  * It allows incrementing, decrementing, and retrieving the current value of the counter,
  * both synchronously and asynchronously.
  */
-public interface LiveCounter extends LiveCounterChange {
+public interface LiveCounter extends LiveCounterChange, ObjectLifecycleChange {
 
     /**
      * Increments the value of the counter by the specified amount.

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

@@ -1,6 +1,7 @@
 package io.ably.lib.objects.type.map;
 
 import io.ably.lib.objects.ObjectsCallback;
+import io.ably.lib.objects.type.ObjectLifecycleChange;
 import org.jetbrains.annotations.Blocking;
 import org.jetbrains.annotations.NonBlocking;
 import org.jetbrains.annotations.Contract;
@@ -14,7 +15,7 @@
  * 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 extends LiveMapChange {
+public interface LiveMap extends LiveMapChange, ObjectLifecycleChange {
 
     /**
      * Retrieves the value associated with the specified key.

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

@@ -99,7 +99,8 @@ private class ObjectsStateEmitter : EventEmitter<ObjectsStateEvent, ObjectsState
   private val tag = "ObjectsStateEmitter"
   override fun apply(listener: ObjectsStateChange.Listener?, event: ObjectsStateEvent?, vararg args: Any?) {
     try {
-      listener?.onStateChanged(event!!)
+      event?.let { listener?.onStateChanged(it) }
+        ?: Log.w(tag, "Null event passed to ObjectsStateChange Listener callback")
     } catch (t: Throwable) {
       Log.e(tag, "Error occurred while executing listener callback for event: $event", t)
     }

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

@@ -4,7 +4,6 @@ import io.ably.lib.types.AblyException
 import io.ably.lib.types.ErrorInfo
 import io.ably.lib.util.Log
 import kotlinx.coroutines.*
-import org.jetbrains.annotations.NotNull
 import java.nio.charset.StandardCharsets
 import java.util.concurrent.CancellationException
 
@@ -66,7 +65,6 @@ internal class ObjectsAsyncScope(channelName: String) {
   private val scope =
     CoroutineScope(Dispatchers.Default + CoroutineName(tag) + SupervisorJob())
 
-  @NotNull
   internal fun <T> launchWithCallback(callback: ObjectsCallback<T>, block: suspend () -> T) {
     scope.launch {
       try {

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

@@ -27,7 +27,7 @@ internal val ObjectUpdate.noOp get() = this.update == null
 internal abstract class BaseRealtimeObject(
   internal val objectId: String, // // RTLO3a
   internal val objectType: ObjectType,
-) {
+) : ObjectLifecycleCoordinator() {
 
   protected open val tag = "BaseRealtimeObject"
 
@@ -92,7 +92,7 @@ internal abstract class BaseRealtimeObject(
 
     if (isTombstoned) {
       // this object is tombstoned so the operation cannot be applied
-      return;
+      return
     }
     applyObjectOperation(objectOperation, objectMessage) // RTLC7d
   }
@@ -115,7 +115,7 @@ internal abstract class BaseRealtimeObject(
 
   internal fun validateObjectId(objectId: String?) {
     if (this.objectId != objectId) {
-      throw objectError("Invalid object: incoming objectId=${objectId}; $objectType objectId=$objectId")
+      throw objectError("Invalid object: incoming objectId=$objectId; $objectType objectId=${this.objectId}")
     }
   }
 
@@ -129,7 +129,8 @@ internal abstract class BaseRealtimeObject(
     isTombstoned = true
     tombstonedAt = serialTimestamp?: System.currentTimeMillis()
     val update = clearData()
-    // TODO: Emit BaseRealtimeObject lifecycle events
+    // Emit object lifecycle event for deletion
+    objectLifecycleChanged(ObjectLifecycle.Deleted)
     return update
   }
 
@@ -142,13 +143,13 @@ internal abstract class BaseRealtimeObject(
   }
 
   /**
-   * Validates that the provided object state is compatible with this live object.
+   * Validates that the provided object state is compatible with this object.
    * Checks object ID, type-specific validations, and any included create operations.
    */
   abstract fun validate(state: ObjectState)
 
   /**
-   * Applies an object state received during synchronization to this live object.
+   * Applies an object state received during synchronization to this object.
    * This method should update the internal data structure with the complete state
    * received from the server.
    *
@@ -159,7 +160,7 @@ internal abstract class BaseRealtimeObject(
   abstract fun applyObjectState(objectState: ObjectState, message: ObjectMessage): ObjectUpdate
 
   /**
-   * Applies an operation to this live object.
+   * Applies an operation to this object.
    * This method handles the specific operation actions (e.g., update, remove)
    * by modifying the underlying data structure accordingly.
    *
@@ -185,7 +186,7 @@ internal abstract class BaseRealtimeObject(
   abstract fun clearData(): ObjectUpdate
 
   /**
-   * Notifies subscribers about changes made to this live object. Propagates updates through the
+   * Notifies subscribers about changes made to this object. Propagates updates through the
    * appropriate manager after converting the generic update map to type-specific update objects.
    * Spec: RTLO4b4c
    */

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

@@ -0,0 +1,84 @@
+package io.ably.lib.objects.type
+
+import io.ably.lib.objects.ObjectsSubscription
+import io.ably.lib.util.EventEmitter
+import io.ably.lib.util.Log
+
+/**
+ * Internal enum representing object lifecycle states
+ */
+internal enum class ObjectLifecycle {
+  Created,
+  Active,
+  Deleted
+}
+
+/**
+ * Maps internal ObjectLifecycle values to their corresponding public ObjectLifecycleEvent values.
+ * Used to determine which events should be emitted when lifecycle changes occur.
+ * CREATED and ACTIVE map to null (no public event), while DELETED maps to the public DELETED event.
+ */
+private val objectLifecycleToEventMap = mapOf(
+  ObjectLifecycle.Created to null,
+  ObjectLifecycle.Active to null,
+  ObjectLifecycle.Deleted to ObjectLifecycleEvent.DELETED
+)
+
+/**
+ * An interface for managing and communicating changes in the lifecycle state of objects.
+ *
+ * Implementations should ensure thread-safe event emission and proper lifecycle
+ * event notifications.
+ */
+internal interface HandlesObjectLifecycleChange {
+  /**
+   * Handles changes in the lifecycle of objects by notifying all registered listeners.
+   * Implementations should ensure thread-safe event emission to both internal and public listeners.
+   * Makes sure every event is processed in the order they were received.
+   * @param newLifecycle The new lifecycle state of the object.
+   */
+  fun objectLifecycleChanged(newLifecycle: ObjectLifecycle)
+
+  /**
+   * Disposes all registered lifecycle change listeners and cancels any pending operations.
+   * Should be called when the associated object is no longer needed.
+   */
+  fun disposeObjectLifecycleListeners()
+}
+
+internal abstract class ObjectLifecycleCoordinator : ObjectLifecycleChange, HandlesObjectLifecycleChange {
+  private val tag = "ObjectLifecycleCoordinator"
+  // EventEmitter for users of the library
+  private val objectLifecycleEmitter = ObjectLifecycleEmitter()
+
+  override fun on(event: ObjectLifecycleEvent, listener: ObjectLifecycleChange.Listener): ObjectsSubscription {
+    objectLifecycleEmitter.on(event, listener)
+    return ObjectsSubscription {
+      objectLifecycleEmitter.off(event, listener)
+    }
+  }
+
+  override fun off(listener: ObjectLifecycleChange.Listener) = objectLifecycleEmitter.off(listener)
+
+  override fun offAll() = objectLifecycleEmitter.off()
+
+  override fun objectLifecycleChanged(newLifecycle: ObjectLifecycle) {
+    objectLifecycleToEventMap[newLifecycle]?.let { objectLifecycleEvent ->
+      objectLifecycleEmitter.emit(objectLifecycleEvent)
+    }
+  }
+
+  override fun disposeObjectLifecycleListeners() = offAll()
+}
+
+private class ObjectLifecycleEmitter : EventEmitter<ObjectLifecycleEvent, ObjectLifecycleChange.Listener>() {
+  private val tag = "ObjectLifecycleEmitter"
+  override fun apply(listener: ObjectLifecycleChange.Listener?, event: ObjectLifecycleEvent?, vararg args: Any?) {
+    try {
+      event?.let { listener?.onLifecycleEvent(it) }
+        ?: Log.w(tag, "Null event passed to ObjectLifecycleChange listener callback")
+    } catch (t: Throwable) {
+      Log.e(tag, "Error occurred while executing listener callback for event: $event", t)
+    }
+  }
+}

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

@@ -43,7 +43,7 @@ private class LiveCounterChangeEmitter : EventEmitter<LiveCounterUpdate, LiveCou
   override fun apply(listener: LiveCounterChange.Listener?, event: LiveCounterUpdate?, vararg args: Any?) {
     try {
       event?.let { listener?.onUpdated(it) }
-        ?: Log.w(tag, "Null event passed to listener callback")
+        ?: Log.w(tag, "Null event passed to LiveCounterChange listener callback")
     } catch (t: Throwable) {
       Log.e(tag, "Error occurred while executing listener callback for event: $event", t)
     }

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

@@ -43,7 +43,7 @@ private class LiveMapChangeEmitter : EventEmitter<LiveMapUpdate, LiveMapChange.L
   override fun apply(listener: LiveMapChange.Listener?, event: LiveMapUpdate?, vararg args: Any?) {
     try {
       event?.let { listener?.onUpdated(it) }
-        ?: Log.w(tag, "Null event passed to listener callback")
+        ?: Log.w(tag, "Null event passed to LiveMapChange listener callback")
     } catch (t: Throwable) {
       Log.e(tag, "Error occurred while executing listener callback for event: $event", t)
     }