Route refresh: added experimental state observer (#6345)

* Route refresh: added experimental state observer

Author: RingerJK

CHANGELOG.md

@@ -8,6 +8,7 @@ Mapbox welcomes participation and contributions from everyone.
 - Introduced `ViewOptionsCustomization.showCameraDebugInfo` to allow end users to enable camera debug info. [#6356](https://github.com/mapbox/mapbox-navigation-android/pull/6356)
 - Added `ComponentInstaller` for the `LocationComponent` that offers simplified integration of map LocationPuck. [#6206](https://github.com/mapbox/mapbox-navigation-android/pull/6206)
 - Added `ViewStyleCustomization.locationPuck` that allows to define a custom location puck using `NavigationView`. [#6365](https://github.com/mapbox/mapbox-navigation-android/pull/6365)
+- Added _Experimental_ `RouteRefreshStatesObserver` that can be used to observe route refresh states. To subscribe and unsubscribe on updates corresponding use `MapboxNavigation#registerRouteRefreshStateObserver` and `MapboxNavigation#unregisterRouteRefreshStateObserver`. [#6345](https://github.com/mapbox/mapbox-navigation-android/pull/6345)
 #### Bug fixes and improvements
 - Marked `PredictiveCacheController`, `MapboxBuildingView`, `ViewportDataSourceUpdateObserver`, `NavigationScaleGestureHandler`, `NavigationCameraStateChangedObserver`, `NavigationCameraStateTransition`, `NavigationCameraTransition`, `TransitionEndListener`, `MapboxRecenterButton`, `MapboxRouteOverviewButton`, `MapboxJunctionView`, `MapboxSignboardView`, `MapboxRoadNameLabelView`, `MapboxRoadNameView`, `MapboxRouteArrowView`, `MapboxRouteLineView`, `MapboxCameraModeButton` methods and `View.capture` extension with `@UiThread` annotation. [#6235](https://github.com/mapbox/mapbox-navigation-android/pull/6235)
 - Marked `Binder`, `MapboxExtendableButton` methods and `MapboxNavigation#installComponents` methods with `@UiThread` annotation. [#6268](https://github.com/mapbox/mapbox-navigation-android/pull/6268)

libnavigation-core/api/current.txt

@@ -40,6 +40,7 @@ package com.mapbox.navigation.core {
     method public void registerRouteAlternativesObserver(com.mapbox.navigation.core.routealternatives.RouteAlternativesObserver routeAlternativesObserver);
     method public void registerRouteAlternativesObserver(com.mapbox.navigation.core.routealternatives.NavigationRouteAlternativesObserver routeAlternativesObserver);
     method public void registerRouteProgressObserver(com.mapbox.navigation.core.trip.session.RouteProgressObserver routeProgressObserver);
+    method @com.mapbox.navigation.base.ExperimentalPreviewMapboxNavigationAPI public void registerRouteRefreshStateObserver(com.mapbox.navigation.core.routerefresh.RouteRefreshStatesObserver routeRefreshStatesObserver);
     method public void registerRoutesObserver(com.mapbox.navigation.core.directions.session.RoutesObserver routesObserver);
     method public void registerTripSessionStateObserver(com.mapbox.navigation.core.trip.session.TripSessionStateObserver tripSessionStateObserver);
     method public void registerVoiceInstructionsObserver(com.mapbox.navigation.core.trip.session.VoiceInstructionsObserver voiceInstructionsObserver);
@@ -77,6 +78,7 @@ package com.mapbox.navigation.core {
     method public void unregisterRouteAlternativesObserver(com.mapbox.navigation.core.routealternatives.RouteAlternativesObserver routeAlternativesObserver);
     method public void unregisterRouteAlternativesObserver(com.mapbox.navigation.core.routealternatives.NavigationRouteAlternativesObserver routeAlternativesObserver);
     method public void unregisterRouteProgressObserver(com.mapbox.navigation.core.trip.session.RouteProgressObserver routeProgressObserver);
+    method @com.mapbox.navigation.base.ExperimentalPreviewMapboxNavigationAPI public void unregisterRouteRefreshStateObserver(com.mapbox.navigation.core.routerefresh.RouteRefreshStatesObserver routeRefreshStatesObserver);
     method public void unregisterRoutesObserver(com.mapbox.navigation.core.directions.session.RoutesObserver routesObserver);
     method public void unregisterTripSessionStateObserver(com.mapbox.navigation.core.trip.session.TripSessionStateObserver tripSessionStateObserver);
     method public void unregisterVoiceInstructionsObserver(com.mapbox.navigation.core.trip.session.VoiceInstructionsObserver voiceInstructionsObserver);
@@ -754,6 +756,31 @@ package com.mapbox.navigation.core.routeoptions {
 
 }
 
+package com.mapbox.navigation.core.routerefresh {
+
+  @com.mapbox.navigation.base.ExperimentalPreviewMapboxNavigationAPI public final class RouteRefreshExtra {
+    field public static final com.mapbox.navigation.core.routerefresh.RouteRefreshExtra INSTANCE;
+    field public static final String REFRESH_STATE_FINISHED_FAILED = "FINISHED_FAILED";
+    field public static final String REFRESH_STATE_FINISHED_SUCCESS = "FINISHED_SUCCESS";
+    field public static final String REFRESH_STATE_STARTED = "STARTED";
+  }
+
+  @StringDef({com.mapbox.navigation.core.routerefresh.RouteRefreshExtra.REFRESH_STATE_STARTED, com.mapbox.navigation.core.routerefresh.RouteRefreshExtra.REFRESH_STATE_FINISHED_SUCCESS, com.mapbox.navigation.core.routerefresh.RouteRefreshExtra.REFRESH_STATE_FINISHED_FAILED}) @kotlin.annotation.Retention(kotlin.annotation.AnnotationRetention.BINARY) public static @interface RouteRefreshExtra.RouteRefreshState {
+  }
+
+  @com.mapbox.navigation.base.ExperimentalPreviewMapboxNavigationAPI public final class RouteRefreshStateResult {
+    method public String? getMessage();
+    method public String getState();
+    property public final String? message;
+    property public final String state;
+  }
+
+  @com.mapbox.navigation.base.ExperimentalPreviewMapboxNavigationAPI public fun interface RouteRefreshStatesObserver {
+    method public void onNewState(com.mapbox.navigation.core.routerefresh.RouteRefreshStateResult result);
+  }
+
+}
+
 package com.mapbox.navigation.core.telemetry {
 
   public final class MapboxNavigationTelemetryKt {

libnavigation-core/src/main/java/com/mapbox/navigation/core/MapboxNavigation.kt

@@ -83,6 +83,7 @@ import com.mapbox.navigation.core.routealternatives.RouteAlternativesRequestCall
 import com.mapbox.navigation.core.routeoptions.RouteOptionsUpdater
 import com.mapbox.navigation.core.routerefresh.RouteRefreshController
 import com.mapbox.navigation.core.routerefresh.RouteRefreshControllerProvider
+import com.mapbox.navigation.core.routerefresh.RouteRefreshStatesObserver
 import com.mapbox.navigation.core.telemetry.MapboxNavigationTelemetry
 import com.mapbox.navigation.core.telemetry.events.FeedbackEvent
 import com.mapbox.navigation.core.telemetry.events.FeedbackHelper
@@ -1050,6 +1051,7 @@ class MapboxNavigation @VisibleForTesting internal constructor(
             ReachabilityService.removeReachabilityObserver(it)
             reachabilityObserverId = null
         }
+        routeRefreshController.unregisterAllRouteRefreshStateObservers()
 
         isDestroyed = true
         hasInstance = false
@@ -1612,6 +1614,28 @@ class MapboxNavigation @VisibleForTesting internal constructor(
         navigationSession.unregisterNavigationSessionStateObserver(navigationSessionStateObserver)
     }
 
+    /**
+     * Register a [RouteRefreshStatesObserver] to be notified of Route refresh state changes.
+     *
+     * @param routeRefreshStatesObserver RouteRefreshStatesObserver
+     */
+    @ExperimentalPreviewMapboxNavigationAPI
+    fun registerRouteRefreshStateObserver(
+        routeRefreshStatesObserver: RouteRefreshStatesObserver
+    ) {
+        routeRefreshController.registerRouteRefreshStateObserver(routeRefreshStatesObserver)
+    }
+
+    /**
+     * Unregisters a [RouteRefreshStatesObserver].
+     */
+    @ExperimentalPreviewMapboxNavigationAPI
+    fun unregisterRouteRefreshStateObserver(
+        routeRefreshStatesObserver: RouteRefreshStatesObserver
+    ) {
+        routeRefreshController.unregisterRouteRefreshStateObserver(routeRefreshStatesObserver)
+    }
+
     private fun startSession(withTripService: Boolean, withReplayEnabled: Boolean) {
         runIfNotDestroyed {
             tripSession.start(

libnavigation-core/src/main/java/com/mapbox/navigation/core/routerefresh/RouteRefreshController.kt

@@ -1,6 +1,8 @@
 package com.mapbox.navigation.core.routerefresh
 
+import androidx.annotation.VisibleForTesting
 import com.mapbox.api.directions.v5.models.RouteLeg
+import com.mapbox.navigation.base.ExperimentalPreviewMapboxNavigationAPI
 import com.mapbox.navigation.base.internal.CurrentIndices
 import com.mapbox.navigation.base.internal.route.updateDirectionsRouteOnly
 import com.mapbox.navigation.base.internal.time.parseISO8601DateToLocalTimeOrNull
@@ -12,6 +14,7 @@ import com.mapbox.navigation.core.CurrentIndicesProvider
 import com.mapbox.navigation.core.directions.session.RouteRefresh
 import com.mapbox.navigation.utils.internal.logE
 import com.mapbox.navigation.utils.internal.logI
+import kotlinx.coroutines.CancellationException
 import kotlinx.coroutines.CompletableDeferred
 import kotlinx.coroutines.async
 import kotlinx.coroutines.awaitAll
@@ -20,39 +23,105 @@ import kotlinx.coroutines.delay
 import kotlinx.coroutines.suspendCancellableCoroutine
 import kotlinx.coroutines.withTimeoutOrNull
 import java.util.Date
+import java.util.concurrent.CopyOnWriteArraySet
 import kotlin.coroutines.resume
 
 /**
  * This class is responsible for refreshing the current direction route's traffic.
  * This does not support alternative routes.
  */
+@OptIn(ExperimentalPreviewMapboxNavigationAPI::class)
 internal class RouteRefreshController(
     private val routeRefreshOptions: RouteRefreshOptions,
     private val routeRefresh: RouteRefresh,
     private val currentIndicesProvider: CurrentIndicesProvider,
     private val routeDiffProvider: DirectionsRouteDiffProvider = DirectionsRouteDiffProvider(),
-    private val localDateProvider: () -> Date
+    private val localDateProvider: () -> Date,
 ) {
 
+    private var state: RouteRefreshStateResult? = null
+        set(value) {
+            if (field == value) return
+            field = value
+            value?.let { nonNullValue ->
+                observers.forEach {
+                    it.onNewState(nonNullValue)
+                }
+            }
+        }
+
+    private val observers = CopyOnWriteArraySet<RouteRefreshStatesObserver>()
+
     internal companion object {
+        @VisibleForTesting
         internal const val LOG_CATEGORY = "RouteRefreshController"
-        private const val FAILED_ATTEMPTS_TO_INVALIDATE_EXPIRING_DATA = 3
+
+        @VisibleForTesting
+        internal const val FAILED_ATTEMPTS_TO_INVALIDATE_EXPIRING_DATA = 3
     }
 
     suspend fun refresh(routes: List<NavigationRoute>): RefreshedRouteInfo {
-        return if (routes.isNotEmpty()) {
-            val routesValidationResults = routes.map { validateRoute(it) }
-            if (routesValidationResults.any { it is RouteValidationResult.Valid }) {
-                tryRefreshingRoutesUntilRouteChanges(routes)
+        try {
+            return if (routes.isNotEmpty()) {
+                val routesValidationResults = routes.map { validateRoute(it) }
+                if (routesValidationResults.any { it is RouteValidationResult.Valid }) {
+                    tryRefreshingRoutesUntilRouteChanges(routes)
+                } else {
+                    val message = joinValidationErrorMessages(routesValidationResults, routes)
+                    onNewState(
+                        RouteRefreshExtra.REFRESH_STATE_FINISHED_FAILED,
+                        "No routes which could be refreshed. $message"
+                    )
+                    waitForever("No routes which could be refreshed. $message")
+                }
             } else {
-                val message = joinValidationErrorMessages(routesValidationResults, routes)
-                waitForever("No routes which could be refreshed. $message")
+                resetState()
+                waitForever("routes are empty")
             }
-        } else {
-            waitForever("routes are empty")
+        } catch (e: CancellationException) {
+            onNewStateIfCurrentIs(
+                RouteRefreshExtra.REFRESH_STATE_CANCELED,
+                current = RouteRefreshExtra.REFRESH_STATE_STARTED,
+            )
+            resetState()
+            throw e
         }
     }
 
+    fun registerRouteRefreshStateObserver(observer: RouteRefreshStatesObserver) {
+        observers.add(observer)
+        state?.let { observer.onNewState(it) }
+    }
+
+    fun unregisterRouteRefreshStateObserver(observer: RouteRefreshStatesObserver) {
+        observers.remove(observer)
+    }
+
+    fun unregisterAllRouteRefreshStateObservers() {
+        observers.clear()
+    }
+
+    private fun onNewState(
+        @RouteRefreshExtra.RouteRefreshState state: String,
+        message: String? = null
+    ) {
+        this.state = RouteRefreshStateResult(state, message)
+    }
+
+    private fun onNewStateIfCurrentIs(
+        @RouteRefreshExtra.RouteRefreshState state: String,
+        message: String? = null,
+        @RouteRefreshExtra.RouteRefreshState current: String,
+    ) {
+        if (current == this.state?.state) {
+            onNewState(state, message)
+        }
+    }
+
+    private fun resetState() {
+        this.state = null
+    }
+
     private fun joinValidationErrorMessages(
         routeValidation: List<RouteValidationResult>,
         routes: List<NavigationRoute>
@@ -78,10 +147,14 @@ internal class RouteRefreshController(
         try {
             repeat(FAILED_ATTEMPTS_TO_INVALIDATE_EXPIRING_DATA) {
                 timeUntilNextAttempt.await()
+                if (it == 0) {
+                    onNewState(RouteRefreshExtra.REFRESH_STATE_STARTED)
+                }
                 timeUntilNextAttempt = async { delay(routeRefreshOptions.intervalMillis) }
                 val indicesSnapshot = currentIndicesProvider.getFilledIndicesOrWait()
                 val refreshedRoutes = refreshRoutesOrNull(routes, indicesSnapshot)
                 if (refreshedRoutes.any { it != null }) {
+                    onNewState(RouteRefreshExtra.REFRESH_STATE_FINISHED_SUCCESS)
                     return@coroutineScope RefreshedRouteInfo(
                         refreshedRoutes.mapIndexed { index, navigationRoute ->
                             navigationRoute ?: routes[index]
@@ -93,6 +166,7 @@ internal class RouteRefreshController(
         } finally {
             timeUntilNextAttempt.cancel() // otherwise current coroutine will wait for its child
         }
+        onNewState(RouteRefreshExtra.REFRESH_STATE_FINISHED_FAILED)
         val indicesSnapshot = currentIndicesProvider.getFilledIndicesOrWait()
         RefreshedRouteInfo(
             routes.map { removeExpiringDataFromRoute(it, indicesSnapshot.legIndex) },

libnavigation-core/src/main/java/com/mapbox/navigation/core/routerefresh/RouteRefreshControllerProvider.kt

@@ -16,6 +16,6 @@ internal object RouteRefreshControllerProvider {
         directionsSession,
         currentIndicesProvider,
         DirectionsRouteDiffProvider(),
-        { Date() }
+        { Date() },
     )
 }

libnavigation-core/src/main/java/com/mapbox/navigation/core/routerefresh/RouteRefreshExtra.kt

@@ -0,0 +1,48 @@
+package com.mapbox.navigation.core.routerefresh
+
+import androidx.annotation.StringDef
+import com.mapbox.navigation.base.ExperimentalPreviewMapboxNavigationAPI
+import com.mapbox.navigation.base.route.RouteRefreshOptions
+
+/**
+ * Extra data of route refresh
+ */
+@ExperimentalPreviewMapboxNavigationAPI
+object RouteRefreshExtra {
+
+    /**
+     * The state becomes [REFRESH_STATE_STARTED] when route refresh round is started.
+     */
+    const val REFRESH_STATE_STARTED = "STARTED"
+
+    /**
+     * The state becomes [REFRESH_STATE_FINISHED_SUCCESS] when the route is successfully refreshed.
+     * The state is triggered in case if at least one route is refreshed successfully.
+     */
+    const val REFRESH_STATE_FINISHED_SUCCESS = "FINISHED_SUCCESS"
+
+    /**
+     * The state becomes [REFRESH_STATE_FINISHED_FAILED] when a route refresh failed and the route
+     * is cleaned up of expired data, see [RouteRefreshOptions] for details.
+     * The state is triggered in case if every single route refresh of a set of the routes is failed.
+     */
+    const val REFRESH_STATE_FINISHED_FAILED = "FINISHED_FAILED"
+
+    /**
+     * The state becomes [REFRESH_STATE_CANCELED] when a route refresh canceled. It occurs
+     * when a new set of routes are set, that leads to interrupt route refresh process.
+     */
+    const val REFRESH_STATE_CANCELED = "CANCELED"
+
+    /**
+     * Route refresh states. See [RouteRefreshStatesObserver].
+     */
+    @Retention(AnnotationRetention.BINARY)
+    @StringDef(
+        REFRESH_STATE_STARTED,
+        REFRESH_STATE_FINISHED_SUCCESS,
+        REFRESH_STATE_FINISHED_FAILED,
+        REFRESH_STATE_CANCELED,
+    )
+    annotation class RouteRefreshState
+}

libnavigation-core/src/main/java/com/mapbox/navigation/core/routerefresh/RouteRefreshStateResult.kt

@@ -0,0 +1,45 @@
+package com.mapbox.navigation.core.routerefresh
+
+import com.mapbox.navigation.base.ExperimentalPreviewMapboxNavigationAPI
+
+/**
+ * Wrapper of Route refresh state result. See [RouteRefreshStatesObserver]
+ * @param state route refresh state. See [RouteRefreshExtra.RouteRefreshState]
+ * @param message string represented message (optional)
+ */
+@ExperimentalPreviewMapboxNavigationAPI
+class RouteRefreshStateResult internal constructor(
+    @RouteRefreshExtra.RouteRefreshState val state: String,
+    val message: String? = null
+) {
+    /**
+     * Regenerate whenever a change is made
+     */
+    override fun equals(other: Any?): Boolean {
+        if (this === other) return true
+        if (javaClass != other?.javaClass) return false
+
+        other as RouteRefreshStateResult
+
+        if (state != other.state) return false
+        if (message != other.message) return false
+
+        return true
+    }
+
+    /**
+     * Returns a hash code value for the object.
+     */
+    override fun hashCode(): Int {
+        var result = state.hashCode()
+        result = 31 * result + message.hashCode()
+        return result
+    }
+
+    /**
+     * Returns a string representation of the object.
+     */
+    override fun toString(): String {
+        return "RouteRefreshStateResult(state='$state', message=$message)"
+    }
+}

libnavigation-core/src/main/java/com/mapbox/navigation/core/routerefresh/RouteRefreshStatesObserver.kt

@@ -0,0 +1,15 @@
+package com.mapbox.navigation.core.routerefresh
+
+import com.mapbox.navigation.base.ExperimentalPreviewMapboxNavigationAPI
+
+/**
+ * Route refresh state observer.
+ */
+@ExperimentalPreviewMapboxNavigationAPI
+fun interface RouteRefreshStatesObserver {
+
+    /**
+     * Invoked for the current and every new state.
+     */
+    fun onNewState(result: RouteRefreshStateResult)
+}