chore: rename Cancellation to Subscription to avoid confusions with coroutine cancellation

Author: ttypic

chat-android/src/main/java/com/ably/chat/Cancellation.kt

@@ -25,7 +25,7 @@ interface ConnectionStatus {
      * Registers a listener that will be called whenever the connection status changes.
      * @param listener The function to call when the status changes.
      */
-    fun on(listener: Listener): Cancellation
+    fun on(listener: Listener): Subscription
 
     /**
      * An interface for listening to changes for the connection status

chat-android/src/main/java/com/ably/chat/ConnectionStatus.kt

@@ -10,7 +10,7 @@ interface EmitsDiscontinuities {
      * Register a listener to be called when a discontinuity is detected.
      * @param listener The listener to be called when a discontinuity is detected.
      */
-    fun onDiscontinuity(listener: Listener): Cancellation
+    fun onDiscontinuity(listener: Listener): Subscription
 
     /**
      * An interface for listening when discontinuity happens

chat-android/src/main/java/com/ably/chat/EmitsDiscontinuities.kt

@@ -169,7 +169,7 @@ data class SendMessageParams(
     val headers: MessageHeaders? = null,
 )
 
-interface MessagesSubscription : Cancellation {
+interface MessagesSubscription : Subscription {
     suspend fun getPreviousMessages(queryOptions: QueryOptions): PaginatedResult<Message>
 }
 
@@ -195,7 +195,7 @@ class DefaultMessages(
 
     override suspend fun send(params: SendMessageParams): Message = chatApi.sendMessage(roomId, params)
 
-    override fun onDiscontinuity(listener: EmitsDiscontinuities.Listener): Cancellation {
+    override fun onDiscontinuity(listener: EmitsDiscontinuities.Listener): Subscription {
         TODO("Not yet implemented")
     }
 }

chat-android/src/main/java/com/ably/chat/Messages.kt

@@ -23,7 +23,7 @@ interface Occupancy : EmitsDiscontinuities {
      *
      * @param listener A listener to be called when the occupancy of the room changes.
      */
-    fun subscribe(listener: Listener): Cancellation
+    fun subscribe(listener: Listener): Subscription
 
     /**
      * Get the current occupancy of the chat room.
@@ -65,15 +65,15 @@ internal class DefaultOccupancy(
     override val channel: Channel
         get() = messages.channel
 
-    override fun subscribe(listener: Occupancy.Listener): Cancellation {
+    override fun subscribe(listener: Occupancy.Listener): Subscription {
         TODO("Not yet implemented")
     }
 
     override suspend fun get(): OccupancyEvent {
         TODO("Not yet implemented")
     }
 
-    override fun onDiscontinuity(listener: EmitsDiscontinuities.Listener): Cancellation {
+    override fun onDiscontinuity(listener: EmitsDiscontinuities.Listener): Subscription {
         TODO("Not yet implemented")
     }
 }

chat-android/src/main/java/com/ably/chat/Occupancy.kt

@@ -60,7 +60,7 @@ interface Presence : EmitsDiscontinuities {
      * Subscribe the given listener to all presence events.
      * @param listener listener to subscribe
      */
-    fun subscribe(listener: Listener): Cancellation
+    fun subscribe(listener: Listener): Subscription
 
     /**
      * An interface for listening to new presence event
@@ -156,11 +156,11 @@ internal class DefaultPresence(
         TODO("Not yet implemented")
     }
 
-    override fun subscribe(listener: Presence.Listener): Cancellation {
+    override fun subscribe(listener: Presence.Listener): Subscription {
         TODO("Not yet implemented")
     }
 
-    override fun onDiscontinuity(listener: EmitsDiscontinuities.Listener): Cancellation {
+    override fun onDiscontinuity(listener: EmitsDiscontinuities.Listener): Subscription {
         TODO("Not yet implemented")
     }
 }

chat-android/src/main/java/com/ably/chat/Presence.kt

@@ -38,7 +38,7 @@ interface RoomReactions : EmitsDiscontinuities {
      * @param listener The listener function to be called when a reaction is received.
      * @returns A response object that allows you to control the subscription.
      */
-    fun subscribe(listener: Listener): Cancellation
+    fun subscribe(listener: Listener): Subscription
 
     /**
      * An interface for listening to new reaction events
@@ -111,11 +111,11 @@ internal class DefaultRoomReactions(
         TODO("Not yet implemented")
     }
 
-    override fun subscribe(listener: RoomReactions.Listener): Cancellation {
+    override fun subscribe(listener: RoomReactions.Listener): Subscription {
         TODO("Not yet implemented")
     }
 
-    override fun onDiscontinuity(listener: EmitsDiscontinuities.Listener): Cancellation {
+    override fun onDiscontinuity(listener: EmitsDiscontinuities.Listener): Subscription {
         TODO("Not yet implemented")
     }
 }

chat-android/src/main/java/com/ably/chat/RoomReactions.kt

@@ -21,7 +21,7 @@ interface RoomStatus {
      * @param listener The function to call when the status changes.
      * @returns An object that can be used to unregister the listener.
      */
-    fun on(listener: Listener): Cancellation
+    fun on(listener: Listener): Subscription
 
     /**
      * An interface for listening to changes for the room status

chat-android/src/main/java/com/ably/chat/RoomStatus.kt

@@ -0,0 +1,12 @@
+package com.ably.chat
+
+/**
+ * An unsubscription handle, returned by various functions (mostly subscriptions)
+ * where unsubscription is required.
+ */
+fun interface Subscription {
+    /**
+     * Handle unsubscription (unsubscribe listeners, clean up)
+     */
+    fun unsubscribe()
+}

chat-android/src/main/java/com/ably/chat/Subscription.kt

@@ -37,7 +37,7 @@ interface Typing : EmitsDiscontinuities {
      *
      * @param listener A listener to be called when the typing state of a user in the room changes.
      */
-    fun subscribe(listener: Listener): Cancellation
+    fun subscribe(listener: Listener): Subscription
 
     /**
      * Get the current typers, a set of clientIds.
@@ -84,7 +84,7 @@ internal class DefaultTyping(
     override val channel: Channel
         get() = realtimeClient.channels.get(typingIndicatorsChannelName, ChatChannelOptions())
 
-    override fun subscribe(listener: Typing.Listener): Cancellation {
+    override fun subscribe(listener: Typing.Listener): Subscription {
         TODO("Not yet implemented")
     }
 
@@ -100,7 +100,7 @@ internal class DefaultTyping(
         TODO("Not yet implemented")
     }
 
-    override fun onDiscontinuity(listener: EmitsDiscontinuities.Listener): Cancellation {
+    override fun onDiscontinuity(listener: EmitsDiscontinuities.Listener): Subscription {
         TODO("Not yet implemented")
     }
 }