[ECO-5426] Refactored spec comments for LiveObject, LiveCounter and LiveMap classes

Author: sacOO7

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

@@ -304,7 +304,7 @@ internal class DefaultLiveObjects(private val channelName: String, private val a
         continue
       }
 
-      val objectState = objectMessage.objectState!!
+      val objectState: ObjectState = objectMessage.objectState
       syncObjectsDataPool[objectState.objectId] = objectState
     }
   }

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

@@ -6,8 +6,7 @@ import io.ably.lib.util.Log
  * Implementation of LiveObject for LiveCounter.
  * Similar to JavaScript LiveCounter class.
  *
- * @spec RTLC1 - LiveCounter implementation
- * @spec RTLC2 - LiveCounter extends LiveObject
+ * @spec RTLC1/RTLC2 - LiveCounter implementation extends LiveObject
  */
 internal class LiveCounter(
   objectId: String,
@@ -23,7 +22,7 @@ internal class LiveCounter(
   /**
    * @spec RTLC6 - Overrides counter data with state from sync
    */
-  override fun overrideWithObjectState(objectState: ObjectState): Any {
+  override fun overrideWithObjectState(objectState: ObjectState): Map<String, Long> {
     if (objectState.objectId != objectId) {
       throw objectError("Invalid object state: object state objectId=${objectState.objectId}; LiveCounter objectId=$objectId")
     }
@@ -93,7 +92,7 @@ internal class LiveCounter(
     notifyUpdated(update)
   }
 
-  override fun clearData(): Any {
+  override fun clearData(): Map<String, Long> {
     val previousData = data
     data = 0
     return mapOf("amount" to -previousData)
@@ -102,7 +101,7 @@ internal class LiveCounter(
   /**
    * @spec RTLC6d - Merges initial data from create operation
    */
-  private fun applyCounterCreate(operation: ObjectOperation): Any {
+  private fun applyCounterCreate(operation: ObjectOperation): Map<String, Long> {
     if (createOperationIsMerged) {
       Log.v(
         tag,
@@ -117,7 +116,7 @@ internal class LiveCounter(
   /**
    * @spec RTLC8 - Applies counter increment operation
    */
-  private fun applyCounterInc(counterOp: ObjectCounterOp): Any {
+  private fun applyCounterInc(counterOp: ObjectCounterOp): Map<String, Long> {
     val amount = counterOp.amount?.toLong() ?: 0
     data += amount
     return mapOf("amount" to amount)
@@ -126,7 +125,7 @@ internal class LiveCounter(
   /**
    * @spec RTLC6d - Merges initial data from create operation
    */
-  private fun mergeInitialDataFromCreateOperation(operation: ObjectOperation): Any {
+  private fun mergeInitialDataFromCreateOperation(operation: ObjectOperation): Map<String, Long> {
     // if a counter object is missing for the COUNTER_CREATE op, the initial value is implicitly 0 in this case.
     // note that it is intentional to SUM the incoming count from the create op.
     // if we got here, it means that current counter instance is missing the initial value in its data reference,

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

@@ -6,8 +6,7 @@ import io.ably.lib.util.Log
  * Implementation of LiveObject for LiveMap.
  * Similar to JavaScript LiveMap class.
  *
- * @spec RTLM1 - LiveMap implementation
- * @spec RTLM2 - LiveMap extends LiveObject
+ * @spec RTLM1/RTLM2 - LiveMap implementation extends LiveObject
  */
 internal class LiveMap(
   objectId: String,
@@ -20,19 +19,19 @@ internal class LiveMap(
   /**
    * @spec RTLM3 - Map data structure storing entries
    */
-  private data class MapEntry(
+  private data class LiveMapEntry(
     var tombstone: Boolean = false,
     var tombstonedAt: Long? = null,
     var timeserial: String? = null,
     var data: ObjectData? = null
   )
 
-  private val data = mutableMapOf<String, MapEntry>()
+  private val data = mutableMapOf<String, LiveMapEntry>()
 
   /**
    * @spec RTLM6 - Overrides object data with state from sync
    */
-  override fun overrideWithObjectState(objectState: ObjectState): Any {
+  override fun overrideWithObjectState(objectState: ObjectState): Map<String, String> {
     if (objectState.objectId != objectId) {
       throw objectError("Invalid object state: object state objectId=${objectState.objectId}; LiveMap objectId=$objectId")
     }
@@ -62,8 +61,8 @@ internal class LiveMap(
       createOperationIsMerged = false // RTLM6b
       data.clear()
 
-      objectState.map?.entries?.forEach { (key, entry) ->
-        data[key] = MapEntry(
+      objectState.map.entries?.forEach { (key, entry) ->
+        data[key] = LiveMapEntry(
           tombstone = entry.tombstone ?: false,
           tombstonedAt = if (entry.tombstone == true) System.currentTimeMillis() else null,
           timeserial = entry.timeserial,
@@ -119,7 +118,7 @@ internal class LiveMap(
     notifyUpdated(update)
   }
 
-  override fun clearData(): Any {
+  override fun clearData(): Map<String, String> {
     val previousData = data.toMap()
     data.clear()
     return calculateUpdateFromDataDiff(previousData, emptyMap())
@@ -128,13 +127,13 @@ internal class LiveMap(
   /**
    * @spec RTLM6d - Merges initial data from create operation
    */
-  private fun applyMapCreate(operation: ObjectOperation): Any {
+  private fun applyMapCreate(operation: ObjectOperation): Map<String, String> {
     if (createOperationIsMerged) {
       Log.v(
         tag,
         "Skipping applying MAP_CREATE op on a map instance as it was already applied before; objectId=$objectId"
       )
-      return mapOf<String, String>()
+      return mapOf()
     }
 
     if (semantics != operation.map?.semantics) {
@@ -149,7 +148,7 @@ internal class LiveMap(
   /**
    * @spec RTLM7 - Applies MAP_SET operation to LiveMap
    */
-  private fun applyMapSet(mapOp: ObjectMapOp, opSerial: String?): Any {
+  private fun applyMapSet(mapOp: ObjectMapOp, opSerial: String?): Map<String, String> {
     val existingEntry = data[mapOp.key]
 
     // RTLM7a
@@ -159,7 +158,7 @@ internal class LiveMap(
         tag,
         "Skipping update for key=\"${mapOp.key}\": op serial $opSerial <= entry serial ${existingEntry.timeserial}; objectId=$objectId"
       )
-      return mapOf<String, String>()
+      return mapOf()
     }
 
     if (existingEntry != null) {
@@ -170,7 +169,7 @@ internal class LiveMap(
       existingEntry.data = mapOp.data // RTLM7a2a
     } else {
       // RTLM7b, RTLM7b1
-      data[mapOp.key] = MapEntry(
+      data[mapOp.key] = LiveMapEntry(
         tombstone = false, // RTLM7b2
         timeserial = opSerial,
         data = mapOp.data
@@ -183,7 +182,7 @@ internal class LiveMap(
   /**
    * @spec RTLM8 - Applies MAP_REMOVE operation to LiveMap
    */
-  private fun applyMapRemove(mapOp: ObjectMapOp, opSerial: String?): Any {
+  private fun applyMapRemove(mapOp: ObjectMapOp, opSerial: String?): Map<String, String> {
     val existingEntry = data[mapOp.key]
 
     // RTLM8a
@@ -193,7 +192,7 @@ internal class LiveMap(
         tag,
         "Skipping remove for key=\"${mapOp.key}\": op serial $opSerial <= entry serial ${existingEntry.timeserial}; objectId=$objectId"
       )
-      return mapOf<String, String>()
+      return mapOf()
     }
 
     if (existingEntry != null) {
@@ -204,7 +203,7 @@ internal class LiveMap(
       existingEntry.data = null // RTLM8a2a
     } else {
       // RTLM8b, RTLM8b1
-      data[mapOp.key] = MapEntry(
+      data[mapOp.key] = LiveMapEntry(
         tombstone = true, // RTLM8b2
         tombstonedAt = System.currentTimeMillis(),
         timeserial = opSerial
@@ -215,38 +214,29 @@ internal class LiveMap(
   }
 
   /**
+   * For Lww CRDT semantics (the only supported LiveMap semantic) an operation
+   * Should only be applied if incoming serial is strictly greater than existing entry's serial.
    * @spec RTLM9 - Serial comparison logic for map operations
    */
-  private fun canApplyMapOperation(mapEntrySerial: String?, opSerial: String?): Boolean {
-    // for Lww CRDT semantics (the only supported LiveMap semantic) an operation
-    // should only be applied if its serial is strictly greater ("after") than an entry's serial.
-
-    if (mapEntrySerial.isNullOrEmpty() && opSerial.isNullOrEmpty()) {
-      // RTLM9b - if both serials are nullish or empty strings, we treat them as the "earliest possible" serials,
-      // in which case they are "equal", so the operation should not be applied
+  private fun canApplyMapOperation(existingMapEntrySerial: String?, opSerial: String?): Boolean {
+    if (existingMapEntrySerial.isNullOrEmpty() && opSerial.isNullOrEmpty()) { // RTLM9b
       return false
     }
-
-    if (mapEntrySerial.isNullOrEmpty()) {
-      // RTLM9d - any operation serial is greater than non-existing entry serial
+    if (existingMapEntrySerial.isNullOrEmpty()) { // RTLM9d - If true, means opSerial is not empty based on previous checks
       return true
     }
-
-    if (opSerial.isNullOrEmpty()) {
-      // RTLM9c - non-existing operation serial is lower than any entry serial
+    if (opSerial.isNullOrEmpty()) { // RTLM9c - Check reached here means existingMapEntrySerial is not empty
       return false
     }
-
-    // RTLM9e - if both serials exist, compare them lexicographically
-    return opSerial > mapEntrySerial
+    return opSerial > existingMapEntrySerial // RTLM9e - both are not empty
   }
 
   /**
    * @spec RTLM6d - Merges initial data from create operation
    */
-  private fun mergeInitialDataFromCreateOperation(operation: ObjectOperation): Any {
+  private fun mergeInitialDataFromCreateOperation(operation: ObjectOperation): Map<String, String> {
     if (operation.map?.entries.isNullOrEmpty()) { // no map entries in MAP_CREATE op
-      return mapOf<String, String>()
+      return mapOf()
     }
 
     val aggregatedUpdate = mutableMapOf<String, String>()
@@ -275,7 +265,7 @@ internal class LiveMap(
     return aggregatedUpdate
   }
 
-  private fun calculateUpdateFromDataDiff(prevData: Map<String, MapEntry>, newData: Map<String, MapEntry>): Map<String, String> {
+  private fun calculateUpdateFromDataDiff(prevData: Map<String, LiveMapEntry>, newData: Map<String, LiveMapEntry>): Map<String, String> {
     val update = mutableMapOf<String, String>()
 
     // Check for removed entries

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

@@ -6,8 +6,7 @@ import io.ably.lib.util.Log
  * Base implementation of LiveObject interface.
  * Provides common functionality for all live objects.
  *
- * @spec RTLM1 - Base class for LiveMap objects
- * @spec RTLC1 - Base class for LiveCounter objects
+ * @spec RTLM1/RTLC1 - Base class for LiveMap/LiveCounter objects
  */
 internal abstract class BaseLiveObject(
   protected val objectId: String,
@@ -17,14 +16,14 @@ internal abstract class BaseLiveObject(
   protected open val tag = "BaseLiveObject"
   protected var isTombstoned = false
   protected var tombstonedAt: Long? = null
+
   /**
-   * @spec RTLM6 - Map of serials keyed by site code for LiveMap
-   * @spec RTLC6 - Map of serials keyed by site code for LiveCounter
+   * @spec RTLM6/RTLC6 - Map of serials keyed by site code for LiveMap/LiveCounter
    */
   protected val siteTimeserials = mutableMapOf<String, String>()
+
   /**
-   * @spec RTLM6 - Flag to track if create operation has been merged for LiveMap
-   * @spec RTLC6 - Flag to track if create operation has been merged for LiveCounter
+   * @spec RTLM6/RTLC6 - Flag to track if create operation has been merged for LiveMap/LiveCounter
    */
   protected var createOperationIsMerged = false
 
@@ -37,24 +36,20 @@ internal abstract class BaseLiveObject(
    * Checks if an operation can be applied based on serial comparison.
    * Similar to JavaScript _canApplyOperation method.
    *
-   * @spec RTLM9 - Serial comparison logic for LiveMap operations
-   * @spec RTLC9 - Serial comparison logic for LiveCounter operations
+   * @spec RTLM9/RTLC9 - Serial comparison logic for LiveMap/LiveCounter operations
    */
-  protected fun canApplyOperation(opSiteCode: String?, opSerial: String?): Boolean {
-    if (isTombstoned) {
-      // this object is tombstoned so the operation cannot be applied
+  protected fun canApplyOperation(siteCode: String?, serial: String?): Boolean {
+    if (isTombstoned) { // this object is tombstoned so the operation cannot be applied
       return false
     }
-
-    if (opSerial.isNullOrEmpty()) {
-      throw objectError("Invalid serial: $opSerial")
+    if (serial.isNullOrEmpty()) {
+      throw objectError("Invalid serial: $serial")
     }
-    if (opSiteCode.isNullOrEmpty()) {
-      throw objectError("Invalid site code: $opSiteCode")
+    if (siteCode.isNullOrEmpty()) {
+      throw objectError("Invalid site code: $siteCode")
     }
-
-    val siteSerial = siteTimeserials[opSiteCode]
-    return siteSerial == null || opSerial > siteSerial
+    val existingSiteSerial = siteTimeserials[siteCode]
+    return existingSiteSerial == null || serial > existingSiteSerial
   }
 
   /**
@@ -68,8 +63,7 @@ internal abstract class BaseLiveObject(
    * Applies object delete operation.
    * Similar to JavaScript _applyObjectDelete method.
    *
-   * @spec RTLM10 - Object deletion for LiveMap
-   * @spec RTLC10 - Object deletion for LiveCounter
+   * @spec RTLM10/RTLC10 - Object deletion for LiveMap/LiveCounter
    */
   protected fun applyObjectDelete(): Any {
     return tombstone()
@@ -79,8 +73,7 @@ internal abstract class BaseLiveObject(
    * Marks the object as tombstoned.
    * Similar to JavaScript tombstone method.
    *
-   * @spec RTLM11 - Tombstone functionality for LiveMap
-   * @spec RTLC11 - Tombstone functionality for LiveCounter
+   * @spec RTLM11/RTLC11 - Tombstone functionality for LiveMap/LiveCounter
    */
   protected fun tombstone(): Any {
     isTombstoned = true
@@ -94,7 +87,7 @@ internal abstract class BaseLiveObject(
    * Clears the object's data.
    * Similar to JavaScript clearData method.
    */
-  protected abstract fun clearData(): Any
+  protected abstract fun clearData(): Map<String, Any>
 
   /**
    * Gets the timestamp when the object was tombstoned.
@@ -110,14 +103,12 @@ internal abstract class BaseLiveObject(
  */
 internal interface LiveObject {
   /**
-   * @spec RTLM6 - Overrides object data with state from sync
-   * @spec RTLC6 - Overrides counter data with state from sync
+   * @spec RTLM6/RTLC6 - Overrides object data with state from sync for LiveMap/LiveCounter
    */
   fun overrideWithObjectState(objectState: ObjectState): Any
 
   /**
-   * @spec RTLM7 - Applies operations to LiveMap
-   * @spec RTLC7 - Applies operations to LiveCounter
+   * @spec RTLM7/RTLC7 - Applies operations to LiveMap/LiveCounter
    */
   fun applyOperation(operation: ObjectOperation, message: ObjectMessage)
 

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

@@ -117,8 +117,8 @@ internal data class ObjectMapEntry(
   val tombstone: Boolean? = null,
 
   /**
-   * The serial value of the last operation that was applied to the map entry.
-   * It is optional in a MAP_CREATE operation and might be missing, in which case the client should use a nullish value for it
+   * The serial value of the latest operation that was applied to the map entry.
+   * It is optional in a MAP_CREATE operation and might be missing, in which case the client should use a null value for it
    * and treat it as the "earliest possible" serial for comparison purposes.
    * Spec: OME2b
    */
@@ -180,12 +180,14 @@ internal data class ObjectOperation(
 
   /**
    * The payload for the operation if it is an operation on a Map object type.
+   * i.e. MAP_SET, MAP_REMOVE.
    * Spec: OOP3c
    */
   val mapOp: ObjectMapOp? = null,
 
   /**
    * The payload for the operation if it is an operation on a Counter object type.
+   * i.e. COUNTER_INC.
    * Spec: OOP3d
    */
   val counterOp: ObjectCounterOp? = null,