Wenxi/fix identity doc (#57)

* fix identify doc

* add reset

* add unit tests

* attempt to fix flaky tests in JavaAnalyticsTest.kt

* attempt to fix flaky tests in JavaAnalyticsTest.kt

* add findAll and optimize code

* add unit tests for find all

* fix flaky tests

* fix flaky tests

* fix flaky tests

* replace instance check with more idiomatic way

Author: wenxi-zeng

core/src/main/java/com/segment/analytics/kotlin/core/Analytics.kt

@@ -43,8 +43,9 @@ class Analytics internal constructor(
     val storage: Storage
     companion object {
         var debugLogsEnabled: Boolean = false
-            set(value: Boolean) {
+            set(value) {
                 SegmentLog.loggingEnabled = value
+                field = value
             }
     }
 
@@ -151,9 +152,12 @@ class Analytics internal constructor(
      * etc.
      *
      * <p>Traits and userId will be automatically cached and available on future sessions for the
-     * same user. To update a trait on the server, call identify with the same user id (or null).
+     * same user. To update a trait on the server, call identify with the same user id.
      * You can also use {@link #identify(Traits)} for this purpose.
      *
+     * In the case when user logs out, make sure to call {@link #reset()} to clear user's identity
+     * info.
+     *
      * @param userId Unique identifier which you recognize a user by in your own database
      * @param traits [Traits] about the user.
      * @see <a href="https://segment.com/docs/spec/identify/">Identify Documentation</a>
@@ -173,9 +177,12 @@ class Analytics internal constructor(
      * etc.
      *
      * <p>Traits and userId will be automatically cached and available on future sessions for the
-     * same user. To update a trait on the server, call identify with the same user id (or null).
+     * same user. To update a trait on the server, call identify with the same user id.
      * You can also use {@link #identify(Traits)} for this purpose.
      *
+     * In the case when user logs out, make sure to call {@link #reset()} to clear user's identity
+     * info.
+     *
      * @param userId Unique identifier which you recognize a user by in your own database
      * @param traits [Traits] about the user. Needs to be [serializable](https://github.com/Kotlin/kotlinx.serialization/blob/master/docs/serializers.md)
      * @param serializationStrategy strategy to serialize [traits]
@@ -195,9 +202,12 @@ class Analytics internal constructor(
      * etc.
      *
      * <p>Traits and userId will be automatically cached and available on future sessions for the
-     * same user. To update a trait on the server, call identify with the same user id (or null).
+     * same user. To update a trait on the server, call identify with the same user id.
      * You can also use {@link #identify(Traits)} for this purpose.
      *
+     * In the case when user logs out, make sure to call {@link #reset()} to clear user's identity
+     * info.
+     *
      * @param userId Unique identifier which you recognize a user by in your own database
      * @param traits [Traits] about the user. Needs to be [serializable](https://github.com/Kotlin/kotlinx.serialization/blob/master/docs/serializers.md)
      * @see <a href="https://segment.com/docs/spec/identify/">Identify Documentation</a>
@@ -381,11 +391,21 @@ class Analytics internal constructor(
     }
 
     /**
-     * Retrieve a registered plugin by reference
-     * @param plugin [Plugin]
+     * Retrieve the first match of registered plugin. It finds
+     *      1. the first instance of the given class/interface
+     *      2. or the first instance of subclass of the given class/interface
+     * @param plugin [KClass]
      */
     fun <T: Plugin> find(plugin: KClass<T>): T? = this.timeline.find(plugin)
 
+    /**
+     * Retrieve the first match of registered plugin. It finds
+     *      1. all instances of the given class/interface
+     *      2. and all instances of subclass of the given class/interface
+     * @param plugin [KClass]
+     */
+    fun <T: Plugin> findAll(plugin: KClass<T>): List<T> = this.timeline.findAll(plugin)
+
     /**
      * Remove a plugin from the analytics timeline using its name
      * @param plugin [Plugin] to be remove
@@ -414,6 +434,19 @@ class Analytics internal constructor(
         }
     }
 
+    /**
+     * Reset the user identity info and all the event plugins. Should be invoked when
+     * user logs out
+     */
+    fun reset() {
+        analyticsScope.launch(analyticsDispatcher) {
+            store.dispatch(UserInfo.ResetAction(), UserInfo::class)
+            timeline.applyClosure {
+                (it as? EventPlugin)?.reset()
+            }
+        }
+    }
+
     /**
      * Retrieve the userId registered by a previous `identify` call in a blocking way.
      * Note: this method invokes `runBlocking` internal, it's not recommended to be used

core/src/main/java/com/segment/analytics/kotlin/core/compat/JavaAnalytics.kt

@@ -79,6 +79,9 @@ class JavaAnalytics private constructor() {
      * same user. To update a trait on the server, call identify with the same user id (or null).
      * You can also use {@link #identify(Traits)} for this purpose.
      *
+     * In the case when user logs out, make sure to call {@link #reset()} to clear user's identity
+     * info.
+     *
      * @param userId Unique identifier which you recognize a user by in your own database
      * @param traits [Traits] about the user in JsonObject form. can be built by
      *          {@link Builder com.segment.analytics.kotlin.core.compat.Builder}
@@ -96,6 +99,9 @@ class JavaAnalytics private constructor() {
      * same user. To update a trait on the server, call identify with the same user id (or null).
      * You can also use {@link #identify(Traits)} for this purpose.
      *
+     * In the case when user logs out, make sure to call {@link #reset()} to clear user's identity
+     * info.
+     *
      * @param userId Unique identifier which you recognize a user by in your own database
      * @param serializable an object that implements {@link JsonSerializable com.segment.analytics.kotlin.core.compat.JsonSerializable}
      * @see <a href="https://segment.com/docs/spec/identify/">Identify Documentation</a>
@@ -212,6 +218,12 @@ class JavaAnalytics private constructor() {
 
     fun flush() = analytics.flush()
 
+    /**
+     * Reset the user identity info and all the event plugins. Should be invoked when
+     * user logs out
+     */
+    fun reset() = analytics.reset()
+
     /**
      * Retrieve the userId registered by a previous `identify` call
      */

core/src/main/java/com/segment/analytics/kotlin/core/platform/Mediator.kt

@@ -65,10 +65,14 @@ internal class Mediator(internal val plugins: MutableList<Plugin>) {
 
     fun <T: Plugin> find(pluginClass: KClass<T>): T? = synchronized(plugins) {
         plugins.forEach {
-            if (it::class == pluginClass) {
+            if (pluginClass.isInstance(it)) {
                 return it as T
             }
         }
         return null
     }
+
+    fun <T: Plugin> findAll(pluginClass: KClass<T>): List<T> = synchronized(plugins) {
+        return plugins.filter { pluginClass.isInstance(it) } as List<T>
+    }
 }

core/src/main/java/com/segment/analytics/kotlin/core/platform/Timeline.kt

@@ -90,4 +90,13 @@ internal class Timeline {
         }
         return null
     }
+
+    fun <T: Plugin> findAll(pluginClass: KClass<T>): List<T> {
+        val result = mutableListOf<T>()
+        plugins.forEach { (_, list) ->
+            val found = list.findAll(pluginClass)
+            result.addAll(found)
+        }
+        return result
+    }
 }

core/src/main/java/com/segment/analytics/kotlin/core/platform/plugins/logger/LogTarget.kt

@@ -126,16 +126,10 @@ fun Analytics.log(message: String, kind: LogFilterKind? = null, function: String
         return
     }
 
-    applyClosureToPlugins { plugin: Plugin ->
-        if (plugin is SegmentLog) {
-            var filterKind = plugin.filterKind
-            if (kind != null) {
-                filterKind = kind
-            }
-
-            val log = LogFactory.buildLog(LoggingType.Filter.LOG, "", message, filterKind, function, line)
-            plugin.log(log, LoggingType.Filter.LOG)
-        }
+    val plugins = findAll(SegmentLog::class)
+    plugins.forEach {
+        val log = LogFactory.buildLog(LoggingType.Filter.LOG, "", message, kind ?: it.filterKind, function, line)
+        it.log(log, LoggingType.Filter.LOG)
     }
 }
 
@@ -156,11 +150,10 @@ fun Analytics.metric(type: String, name: String, value: Double, tags: List<Strin
         return
     }
 
-    applyClosureToPlugins { plugin: Plugin ->
-        if (plugin is SegmentLog) {
-            val log = LogFactory.buildLog(LoggingType.Filter.METRIC, type, name, value = value, tags = tags)
-            plugin.log(log, LoggingType.Filter.METRIC)
-        }
+    val log = LogFactory.buildLog(LoggingType.Filter.METRIC, type, name, value = value, tags = tags)
+    val plugins = findAll(SegmentLog::class)
+    plugins.forEach {
+        it.log(log, LoggingType.Filter.METRIC)
     }
 }
 
@@ -190,17 +183,16 @@ fun Analytics.history(event: BaseEvent, sender: Any, function: String = "", line
         updatedLine = methodInfo.second
     }
 
-    applyClosureToPlugins { plugin: Plugin ->
-        if (plugin is SegmentLog) {
-            val log = LogFactory.buildLog(LoggingType.Filter.HISTORY,
-                title = event.toString(),
-                message = "",
-                function = updatedFunction,
-                line = updatedLine,
-                event = event,
-                sender = sender)
-            plugin.log(log, LoggingType.Filter.HISTORY)
-        }
+    val log = LogFactory.buildLog(LoggingType.Filter.HISTORY,
+        title = event.toString(),
+        message = "",
+        function = updatedFunction,
+        line = updatedLine,
+        event = event,
+        sender = sender)
+    val plugins = findAll(SegmentLog::class)
+    plugins.forEach {
+        it.log(log, LoggingType.Filter.HISTORY)
     }
 }
 
@@ -214,10 +206,9 @@ fun Analytics.history(event: BaseEvent, sender: Any, function: String = "", line
  * public API on Analytics.
  */
 fun Analytics.add(target: LogTarget, type: LoggingType) {
-    applyClosureToPlugins { plugin: Plugin ->
-        if (plugin is SegmentLog) {
-            plugin.add(target, type)
-        }
+    val plugins = findAll(SegmentLog::class)
+    plugins.forEach {
+        it.add(target, type)
     }
 }
 
@@ -228,20 +219,18 @@ fun Analytics.add(target: LogTarget, type: LoggingType) {
  * @property targetType A `LogTarget` class type that should be removed from the system.
  */
 fun <T: LogTarget> Analytics.remove(targetType: KClass<T>) {
-    applyClosureToPlugins { plugin: Plugin ->
-        if (plugin is SegmentLog) {
-            plugin.remove(targetType)
-        }
+    val plugins = findAll(SegmentLog::class)
+    plugins.forEach {
+        it.remove(targetType)
     }
 }
 
 /**
  * Expunge all cached logs that have been captured.
  */
 fun Analytics.logFlush() {
-    this.timeline.applyClosure { plugin: Plugin ->
-        if (plugin is SegmentLog) {
-            plugin.flush()
-        }
+    val plugins = findAll(SegmentLog::class)
+    plugins.forEach {
+        it.flush()
     }
 }

core/src/main/java/com/segment/analytics/kotlin/core/platform/plugins/logger/SegmentLog.kt

@@ -158,35 +158,36 @@ fun Analytics.Companion.segmentLog(message: String, kind: LogFilterKind? = LogFi
 
     val methodInfo = Analytics.callingMethodDetails(function, line)
 
-    SegmentLog.sharedAnalytics?.applyClosureToPlugins { plugin: Plugin ->
-        if (plugin is SegmentLog) {
-            var filterKind = plugin.filterKind
-            if (kind != null) {
-                filterKind = kind
-            }
-
-            val log = LogFactory.buildLog(LoggingType.Filter.LOG, "", message, filterKind, methodInfo.first, methodInfo.second)
-            plugin.log(log, LoggingType.Filter.LOG)
-        }
+    val plugins = SegmentLog.sharedAnalytics?.findAll(SegmentLog::class)
+
+    plugins?.forEach {
+        val log = LogFactory.buildLog(
+            LoggingType.Filter.LOG,
+            "",
+            message,
+            kind ?: it.filterKind,
+            methodInfo.first,
+            methodInfo.second
+        )
+        it.log(log, LoggingType.Filter.LOG)
     }
 }
 
 fun Analytics.Companion.segmentMetric(type: String, name: String, value: Double, tags: List<String>?) {
-    SegmentLog.sharedAnalytics?.applyClosureToPlugins { plugin: Plugin ->
-        if (plugin is SegmentLog) {
-            val log = LogFactory.buildLog(LoggingType.Filter.METRIC,
-                type,
-                name,
-                LogFilterKind.DEBUG,
-                null,
-                null,
-                null,
-                null,
-                value,
-                tags)
-            plugin.log(log, LoggingType.Filter.METRIC)
-            // TODO: Capture function and line
-        }
+    val log = LogFactory.buildLog(LoggingType.Filter.METRIC,
+        type,
+        name,
+        LogFilterKind.DEBUG,
+        null,
+        null,
+        null,
+        null,
+        value,
+        tags)
+
+    val plugins = SegmentLog.sharedAnalytics?.findAll(SegmentLog::class)
+    plugins?.forEach {
+        it.log(log, LoggingType.Filter.METRIC)
     }
 }
 

core/src/main/java/com/segment/analytics/kotlin/core/utilities/PropertiesFile.kt

@@ -22,6 +22,10 @@ class PropertiesFile(private val directory: File, writeKey: String) : KVS {
         if (propertiesFile.exists()) {
             underlyingProperties.load(FileInputStream(propertiesFile))
         }
+        else {
+            propertiesFile.parentFile.mkdirs()
+            propertiesFile.createNewFile()
+        }
     }
 
     fun save() {