feat: use Cancellation object instead of unsubscribe methods

It's proven to be easier to manage to implement when subscription return object that you can use to unsubscribe

.gitignore

@@ -95,6 +95,7 @@ publish.properties
 /.idea/compiler.xml
 /.idea/jarRepositories.xml
 /.idea/misc.xml
+/.idea/shelf
 
 # general
 **/.DS_Store

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

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

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

@@ -25,13 +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)
-
-    /**
-     * Unregisters a listener
-     * @param listener The function to call when the status changes.
-     */
-    fun off(listener: Listener)
+    fun on(listener: Listener): Cancellation
 
     /**
      * An interface for listening to changes for the connection status

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

@@ -10,13 +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)
-
-    /**
-     * Unregister a listener to be called when a discontinuity is detected.
-     * @param listener The listener
-     */
-    fun offDiscontinuity(listener: Listener)
+    fun onDiscontinuity(listener: Listener): Cancellation
 
     /**
      * An interface for listening when discontinuity happens

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

@@ -3,7 +3,6 @@
 package com.ably.chat
 
 import io.ably.lib.realtime.Channel
-import io.ably.lib.types.PaginatedResult
 
 /**
  * This interface is used to interact with messages in a chat room: subscribing
@@ -24,13 +23,7 @@ interface Messages : EmitsDiscontinuities {
      * @param listener callback that will be called
      * @returns A response object that allows you to control the subscription.
      */
-    fun subscribe(listener: Listener)
-
-    /**
-     * Unsubscribe listener
-     * @param listener callback that will be unsubscribed
-     */
-    fun unsubscribe(listener: Listener)
+    fun subscribe(listener: Listener): MessagesSubscription
 
     /**
      * Get messages that have been previously sent to the chat room, based on the provided options.
@@ -176,6 +169,10 @@ data class SendMessageParams(
     val headers: MessageHeaders? = null,
 )
 
+interface MessagesSubscription: Cancellation {
+    suspend fun getPreviousMessages(queryOptions: QueryOptions): PaginatedResult<Message>
+}
+
 class DefaultMessages(
     private val roomId: String,
     private val realtimeClient: RealtimeClient,
@@ -190,25 +187,15 @@ class DefaultMessages(
     override val channel: Channel
         get() = realtimeClient.channels.get(messagesChannelName, ChatChannelOptions())
 
-    override fun subscribe(listener: Messages.Listener) {
+    override fun subscribe(listener: Messages.Listener): MessagesSubscription {
         TODO("Not yet implemented")
     }
 
-    override fun unsubscribe(listener: Messages.Listener) {
-        TODO("Not yet implemented")
-    }
-
-    override suspend fun get(options: QueryOptions): PaginatedResult<Message> {
-        TODO("Not yet implemented")
-    }
+    override suspend fun get(options: QueryOptions): PaginatedResult<Message> = chatApi.getMessages(roomId, options)
 
     override suspend fun send(params: SendMessageParams): Message = chatApi.sendMessage(roomId, params)
 
-    override fun onDiscontinuity(listener: EmitsDiscontinuities.Listener) {
-        TODO("Not yet implemented")
-    }
-
-    override fun offDiscontinuity(listener: EmitsDiscontinuities.Listener) {
+    override fun onDiscontinuity(listener: EmitsDiscontinuities.Listener): Cancellation {
         TODO("Not yet implemented")
     }
 }

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

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

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

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

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

@@ -38,12 +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)
-
-    /**
-     * Unsubscribe all listeners from receiving room-level reaction events.
-     */
-    fun unsubscribe(listener: Listener)
+    fun subscribe(listener: Listener): Cancellation
 
     /**
      * An interface for listening to new reaction events
@@ -116,19 +111,11 @@ internal class DefaultRoomReactions(
         TODO("Not yet implemented")
     }
 
-    override fun subscribe(listener: RoomReactions.Listener) {
-        TODO("Not yet implemented")
-    }
-
-    override fun unsubscribe(listener: RoomReactions.Listener) {
-        TODO("Not yet implemented")
-    }
-
-    override fun onDiscontinuity(listener: EmitsDiscontinuities.Listener) {
+    override fun subscribe(listener: RoomReactions.Listener): Cancellation {
         TODO("Not yet implemented")
     }
 
-    override fun offDiscontinuity(listener: EmitsDiscontinuities.Listener) {
+    override fun onDiscontinuity(listener: EmitsDiscontinuities.Listener): Cancellation {
         TODO("Not yet implemented")
     }
 }

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

@@ -21,12 +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)
-
-    /**
-     * Removes all listeners that were added by the `onChange` method.
-     */
-    fun off(listener: Listener)
+    fun on(listener: Listener): Cancellation
 
     /**
      * An interface for listening to changes for the room status

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

@@ -37,12 +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)
-
-    /**
-     * Unsubscribe listeners from receiving typing events.
-     */
-    fun unsubscribe(listener: Listener)
+    fun subscribe(listener: Listener): Cancellation
 
     /**
      * Get the current typers, a set of clientIds.
@@ -89,11 +84,7 @@ internal class DefaultTyping(
     override val channel: Channel
         get() = realtimeClient.channels.get(typingIndicatorsChannelName, ChatChannelOptions())
 
-    override fun subscribe(listener: Typing.Listener) {
-        TODO("Not yet implemented")
-    }
-
-    override fun unsubscribe(listener: Typing.Listener) {
+    override fun subscribe(listener: Typing.Listener): Cancellation {
         TODO("Not yet implemented")
     }
 
@@ -109,11 +100,7 @@ internal class DefaultTyping(
         TODO("Not yet implemented")
     }
 
-    override fun onDiscontinuity(listener: EmitsDiscontinuities.Listener) {
-        TODO("Not yet implemented")
-    }
-
-    override fun offDiscontinuity(listener: EmitsDiscontinuities.Listener) {
+    override fun onDiscontinuity(listener: EmitsDiscontinuities.Listener): Cancellation {
         TODO("Not yet implemented")
     }
 }