Add Javadoc

matrix-sdk-android/src/main/java/im/vector/matrix/android/api/session/pushers/PushersService.kt

@@ -27,17 +27,29 @@ interface PushersService {
     fun refreshPushers()
 
     /**
-     * Add a new HTTP pusher.
+     * Add a new HTTP pusher. Only `http` kind is supported by the SDK for now.
+     * Ref: https://matrix.org/docs/spec/client_server/latest#post-matrix-client-r0-pushers-set
      *
-     * @param pushkey           the pushkey
+     * @param pushkey           This is a unique identifier for this pusher. The value you should use for
+     *                          this is the routing or destination address information for the notification,
+     *                          for example, the APNS token for APNS or the Registration ID for GCM. If your
+     *                          notification client has no such concept, use any unique identifier. Max length, 512 bytes.
+     *                          If the kind is "email", this is the email address to send notifications to.
      * @param appId             the application id
-     * @param profileTag        the profile tag
+     *                          This is a reverse-DNS style identifier for the application. It is recommended
-     * @param lang              the language
+     *                          that this end with the platform, such that different platform versions get
-     * @param appDisplayName    a human-readable application name
+     *                          different app identifiers. Max length, 64 chars.
-     * @param deviceDisplayName a human-readable device name
+     *                          If the kind is "email", this is "m.email".
-     * @param url               the URL that should be used to send notifications
+     * @param profileTag        This string determines which set of device specific rules this pusher executes.
-     * @param append            append the pusher
+     * @param lang              The preferred language for receiving notifications (e.g. "en" or "en-US").
-     * @param withEventIdOnly   true to limit the push content
+     * @param appDisplayName    A human readable string that will allow the user to identify what application owns this pusher.
+     * @param deviceDisplayName A human readable string that will allow the user to identify what device owns this pusher.
+     * @param url               The URL to use to send notifications to. MUST be an HTTPS URL with a path of /_matrix/push/v1/notify.
+     * @param append            If true, the homeserver should add another pusher with the given pushkey and App ID in addition
+     *                          to any others with different user IDs. Otherwise, the homeserver must remove any other pushers
+     *                          with the same App ID and pushkey for different users.
+     * @param withEventIdOnly   true to limit the push content to only id and not message content
+     *                          Ref: https://matrix.org/docs/spec/push_gateway/r0.1.1#homeserver-behaviour
      *
      * @return A work request uuid. Can be used to listen to the status
      * (LiveData<WorkInfo> status = workManager.getWorkInfoByIdLiveData(<UUID>))
@@ -54,11 +66,7 @@ interface PushersService {
 
     fun removeHttpPusher(pushkey: String, appId: String, callback: MatrixCallback<Unit>)
 
-    companion object {
-        const val EVENT_ID_ONLY = "event_id_only"
-    }
-
     fun getPushersLive(): LiveData<List<Pusher>>
 
-    fun pushers() : List<Pusher>
+    fun pushers(): List<Pusher>
 }

matrix-sdk-android/src/main/java/im/vector/matrix/android/internal/session/pushers/DefaultPusherService.kt

@@ -29,7 +29,7 @@ import im.vector.matrix.android.internal.di.WorkManagerProvider
 import im.vector.matrix.android.internal.task.TaskExecutor
 import im.vector.matrix.android.internal.task.configureWith
 import im.vector.matrix.android.internal.worker.WorkerParamsFactory
-import java.util.*
+import java.util.UUID
 import java.util.concurrent.TimeUnit
 import javax.inject.Inject
 
@@ -48,9 +48,15 @@ internal class DefaultPusherService @Inject constructor(
                 .executeBy(taskExecutor)
     }
 
-    override fun addHttpPusher(pushkey: String, appId: String, profileTag: String,
+    override fun addHttpPusher(pushkey: String,
-                               lang: String, appDisplayName: String, deviceDisplayName: String,
+                               appId: String,
-                               url: String, append: Boolean, withEventIdOnly: Boolean)
+                               profileTag: String,
+                               lang: String,
+                               appDisplayName: String,
+                               deviceDisplayName: String,
+                               url: String,
+                               append: Boolean,
+                               withEventIdOnly: Boolean)
             : UUID {
         val pusher = JsonPusher(
                 pushKey = pushkey,
@@ -60,7 +66,7 @@ internal class DefaultPusherService @Inject constructor(
                 deviceDisplayName = deviceDisplayName,
                 profileTag = profileTag,
                 lang = lang,
-                data = JsonPusherData(url, if (withEventIdOnly) PushersService.EVENT_ID_ONLY else null),
+                data = JsonPusherData(url, EVENT_ID_ONLY.takeIf { withEventIdOnly }),
                 append = append)
 
         val params = AddHttpPusherWorker.Params(sessionId, pusher)
@@ -94,4 +100,8 @@ internal class DefaultPusherService @Inject constructor(
     override fun pushers(): List<Pusher> {
         return monarchy.fetchAllCopiedSync { PusherEntity.where(it) }.map { it.asDomain() }
     }
+
+    companion object {
+        const val EVENT_ID_ONLY = "event_id_only"
+    }
 }