Rename the interfaces, methods, and objects to be somewhat Activity a…

…gnostic

embrace-android-features/src/main/kotlin/io/embrace/android/embracesdk/internal/capture/activity/UiLoadEventEmitter.kt → embrace-android-features/src/main/kotlin/io/embrace/android/embracesdk/internal/capture/activity/ActivityLoadEventEmitter.kt

@@ -11,16 +11,17 @@ import io.embrace.android.embracesdk.internal.utils.VersionChecker
 import io.opentelemetry.sdk.common.Clock
 
 /**
- * Maps [ActivityLifecycleCallbacks] events to [UiLoadEvents] depending on the current state of the app and capabilities of the OS.
+ * Maps [ActivityLifecycleCallbacks] events to [UiLoadEventListener] depending on version of the OS and whether or
+ * not the given [Activity]'s load should be traced.
  *
  * The purpose of this is to leverage Activity lifecycle events to provide data for the underlying workflow to bring a new Activity on
  * screen. Due to the varying capabilities of the APIs available on the different versions of Android, the precise triggering events for
  * the start and intermediate steps may differ.
  *
- * See [UiLoadTraceEmitter] for details.
+ * See [UiLoadTraceEmitter] for details about how these events are turned into traces.
  */
-class UiLoadEventEmitter(
-    private val uiLoadEvents: UiLoadEvents,
+class ActivityLoadEventEmitter(
+    private val uiLoadEventListener: UiLoadEventListener,
     private val clock: Clock,
     private val versionChecker: VersionChecker,
 ) : ActivityLifecycleListener {
@@ -96,59 +97,59 @@ class UiLoadEventEmitter(
     }
 
     private fun abandonTrace(activity: Activity) {
-        uiLoadEvents.abandon(
+        uiLoadEventListener.abandon(
             instanceId = traceInstanceId(activity),
             activityName = activity.localClassName,
             timestampMs = nowMs()
         )
     }
 
     private fun reset(activity: Activity) {
-        uiLoadEvents.reset(
-            instanceId = traceInstanceId(activity),
+        uiLoadEventListener.reset(
+            lastInstanceId = traceInstanceId(activity),
         )
     }
 
     private fun create(activity: Activity) {
-        uiLoadEvents.create(
+        uiLoadEventListener.create(
             instanceId = traceInstanceId(activity),
             activityName = activity.localClassName,
             timestampMs = nowMs()
         )
     }
 
     private fun createEnd(activity: Activity) {
-        uiLoadEvents.createEnd(
+        uiLoadEventListener.createEnd(
             instanceId = traceInstanceId(activity),
             timestampMs = nowMs()
         )
     }
 
     private fun start(activity: Activity) {
-        uiLoadEvents.start(
+        uiLoadEventListener.start(
             instanceId = traceInstanceId(activity),
             activityName = activity.localClassName,
             timestampMs = nowMs()
         )
     }
 
     private fun startEnd(activity: Activity) {
-        uiLoadEvents.startEnd(
+        uiLoadEventListener.startEnd(
             instanceId = traceInstanceId(activity),
             timestampMs = nowMs()
         )
     }
 
     private fun resume(activity: Activity) {
-        uiLoadEvents.resume(
+        uiLoadEventListener.resume(
             instanceId = traceInstanceId(activity),
             activityName = activity.localClassName,
             timestampMs = nowMs()
         )
     }
 
     private fun resumeEnd(activity: Activity) {
-        uiLoadEvents.resumeEnd(
+        uiLoadEventListener.resumeEnd(
             instanceId = traceInstanceId(activity),
             timestampMs = nowMs()
         )

embrace-android-features/src/main/kotlin/io/embrace/android/embracesdk/internal/capture/activity/LifecycleStage.kt

@@ -0,0 +1,13 @@
+package io.embrace.android.embracesdk.internal.capture.activity
+
+/**
+ * The defined stages in the UI Load lifecycle for which child spans will be logged, if applicable.
+ */
+enum class LifecycleStage(private val typeName: String) {
+    CREATE("create"),
+    START("start"),
+    RESUME("resume"),
+    RENDER("render");
+
+    fun spanName(componentName: String): String = "$componentName-$typeName"
+}

embrace-android-features/src/main/kotlin/io/embrace/android/embracesdk/internal/capture/activity/UiLoadEventListener.kt

@@ -0,0 +1,76 @@
+package io.embrace.android.embracesdk.internal.capture.activity
+
+/**
+ * Listener to handle relevant events during the lifecycle of UI loading. Implementations should gather the data and log
+ * the appropriate loading traces and spans.
+ */
+interface UiLoadEventListener {
+
+    /**
+     * When the given UI instance is starting to be created.
+     *
+     * For an Activity, it means it has entered the CREATED state of its lifecycle.
+     */
+    fun create(instanceId: Int, activityName: String, timestampMs: Long)
+
+    /**
+     * When the given UI instance has been fully created and is ready to be displayed on screen.
+     *
+     * For an Activity, it means it is about to exit CREATED state of its lifecycle.
+     */
+    fun createEnd(instanceId: Int, timestampMs: Long)
+
+    /**
+     * When the given UI instance is starting to be displayed on screen
+     *
+     * For an Activity, it means it is about to enter the STARTED state of its lifecycle.
+     */
+    fun start(instanceId: Int, activityName: String, timestampMs: Long)
+
+    /**
+     * When the given UI instance is displayed on screen and its views are ready to be rendered
+     *
+     * For an Activity, it means it is about to exit the STARTED state of its lifecycle.
+     */
+    fun startEnd(instanceId: Int, timestampMs: Long)
+
+    /**
+     * When the given UI instance is getting ready to be rendered
+     *
+     * For an Activity, it means it is about to enter the RESUMED state of its lifecycle.
+     */
+    fun resume(instanceId: Int, activityName: String, timestampMs: Long)
+
+    /**
+     * When the given UI instance is ready to start rendering.
+     *
+     * For an Activity, it means it is about to exit the RESUMED state of its lifecycle.
+     */
+    fun resumeEnd(instanceId: Int, timestampMs: Long)
+
+    /**
+     * When the given UI instance is starting to render
+     *
+     * For an Activity, it means when its root View is begin to render
+     */
+    fun render(instanceId: Int, activityName: String, timestampMs: Long)
+
+    /**
+     * When the given UI instance is has rendered its first frame
+     *
+     * For an Activity, it means when the first frame associated with its Window has delivered its first frame.
+     */
+    fun renderEnd(instanceId: Int, timestampMs: Long)
+
+    /**
+     * When we no longer wish to observe the loading of the given UI instance. This may be called during its load
+     * or after it has loaded. Calls to this for a given instance should be idempotent.
+     */
+    fun abandon(instanceId: Int, activityName: String, timestampMs: Long)
+
+    /**
+     * When the app is no longer in a state where it is trying to open up UI. All traces should be abandoned and
+     * Any events received after this should assume the app is emerging or have emerged from a background state.
+     */
+    fun reset(lastInstanceId: Int)
+}