introduce NavigationRouterV2 interface (#6190)

Author: dzinad

libnavigation-base/src/main/java/com/mapbox/navigation/base/internal/CurrentIndices.kt

@@ -0,0 +1,57 @@
+package com.mapbox.navigation.base.internal
+
+import com.mapbox.api.directions.v5.models.DirectionsRoute
+
+/**
+ * Class holding information about a snapshot of current indices.
+ * All the indices are consistent (taken from the same RouteProgress instance).
+ *
+ * @param legIndex index of a leg the user is currently on.
+ * @param routeGeometryIndex route-wise index representing the geometry point
+ * right in front of the user (see [DirectionsRoute.geometry]), null if unavailable.
+ * @param legGeometryIndex leg-wise index representing the geometry point
+ * right in front of the user (see [DirectionsRoute.geometry]), null if unavailable.
+ */
+class CurrentIndices internal constructor(
+    val legIndex: Int,
+    val routeGeometryIndex: Int,
+    val legGeometryIndex: Int?,
+) {
+
+    /**
+     * Indicates whether some other object is "equal to" this one.
+     */
+    override fun equals(other: Any?): Boolean {
+        if (this === other) return true
+        if (javaClass != other?.javaClass) return false
+
+        other as CurrentIndices
+
+        if (legIndex != other.legIndex) return false
+        if (routeGeometryIndex != other.routeGeometryIndex) return false
+        if (legGeometryIndex != other.legGeometryIndex) return false
+
+        return true
+    }
+
+    /**
+     * Returns a hash code value for the object.
+     */
+    override fun hashCode(): Int {
+        var result = legIndex
+        result = 31 * result + routeGeometryIndex
+        result = 31 * result + (legGeometryIndex ?: 0)
+        return result
+    }
+
+    /**
+     * Returns a string representation of the object.
+     */
+    override fun toString(): String {
+        return "CurrentIndices(" +
+            "legIndex=$legIndex, " +
+            "routeGeometryIndex=$routeGeometryIndex, " +
+            "legGeometryIndex=$legGeometryIndex" +
+            ")"
+    }
+}

libnavigation-base/src/main/java/com/mapbox/navigation/base/internal/CurrentIndicesFactory.kt

@@ -0,0 +1,12 @@
+package com.mapbox.navigation.base.internal
+
+object CurrentIndicesFactory {
+
+    fun createIndices(
+        legIndex: Int,
+        routeGeometryIndex: Int,
+        legGeometryIndex: Int?,
+    ): CurrentIndices = CurrentIndices(
+        legIndex, routeGeometryIndex, legGeometryIndex
+    )
+}

libnavigation-base/src/main/java/com/mapbox/navigation/base/internal/CurrentIndicesSnapshot.kt

@@ -0,0 +1,41 @@
+package com.mapbox.navigation.base.internal
+
+import com.mapbox.api.directions.v5.models.DirectionsRoute
+import com.mapbox.navigation.base.route.NavigationRoute
+import com.mapbox.navigation.base.route.NavigationRouter
+import com.mapbox.navigation.base.route.NavigationRouterRefreshCallback
+
+/**
+ * Extends [NavigationRouter] to also provide ability for refreshing routes partially
+ * using indices stored in [CurrentIndices].
+ */
+interface NavigationRouterV2 : NavigationRouter {
+
+    @Deprecated(
+        "Use getRouteRefresh(" +
+            "NavigationRoute, " +
+            "CurrentIndices, " +
+            "NavigationRouterRefreshCallback" +
+            ")"
+    )
+    override fun getRouteRefresh(
+        route: NavigationRoute,
+        legIndex: Int,
+        callback: NavigationRouterRefreshCallback
+    ): Long
+
+    /**
+     * Refresh the traffic annotations for a given underlying [DirectionsRoute]
+     *
+     * @param route [NavigationRoute] the route to refresh
+     * @param indicesSnapshot Object containing information about consistent current indices
+     * @param callback Callback that gets notified with the results of the request
+     *
+     * @return request ID, can be used to cancel the request with [cancelRouteRefreshRequest]
+     */
+    fun getRouteRefresh(
+        route: NavigationRoute,
+        indicesSnapshot: CurrentIndices,
+        callback: NavigationRouterRefreshCallback
+    ): Long
+}

libnavigation-base/src/main/java/com/mapbox/navigation/base/internal/NavigationRouterV2.kt

@@ -0,0 +1,51 @@
+package com.mapbox.navigation.core
+
+import androidx.annotation.MainThread
+import com.mapbox.navigation.base.internal.CurrentIndices
+import com.mapbox.navigation.base.internal.CurrentIndicesFactory
+import com.mapbox.navigation.base.trip.model.RouteProgress
+import com.mapbox.navigation.core.trip.session.RouteProgressObserver
+import kotlinx.coroutines.CancellableContinuation
+import kotlinx.coroutines.suspendCancellableCoroutine
+import kotlin.coroutines.resume
+
+/**
+ * Gets updates from [RouteProgress], converts them into [CurrentIndices]
+ * and provides said info.
+ */
+@MainThread
+internal class CurrentIndicesProvider : RouteProgressObserver {
+
+    private val defaultIndicesSnapshot = CurrentIndicesFactory.createIndices(0, 0, null)
+    private var indicesSnapshot: CurrentIndices? = null
+    private var continuation: CancellableContinuation<CurrentIndices>? = null
+
+    /**
+     * Returns either last saved value (if has one) or waits for the next update.
+     */
+    suspend fun getFilledIndicesOrWait(): CurrentIndices {
+        return (indicesSnapshot ?: suspendCancellableCoroutine { continuation = it })
+    }
+
+    /**
+     * Resets saved info to null.
+     */
+    fun clear() {
+        indicesSnapshot = null
+    }
+
+    /**
+     * Updates indices.
+     */
+    override fun onRouteProgressChanged(routeProgress: RouteProgress) {
+        indicesSnapshot = CurrentIndicesFactory.createIndices(
+            legIndex = routeProgress.currentLegProgress?.legIndex
+                ?: defaultIndicesSnapshot.legIndex,
+            routeGeometryIndex = routeProgress.currentRouteGeometryIndex,
+            legGeometryIndex = routeProgress.currentLegProgress?.geometryIndex,
+        ).also {
+            continuation?.resume(it)
+            continuation = null
+        }
+    }
+}

libnavigation-base/src/test/java/com/mapbox/navigation/base/route/CurrentIndicesSnapshotTest.kt

@@ -22,6 +22,7 @@ import com.mapbox.common.module.provider.MapboxModuleProvider
 import com.mapbox.navigation.base.ExperimentalPreviewMapboxNavigationAPI
 import com.mapbox.navigation.base.extensions.applyDefaultNavigationOptions
 import com.mapbox.navigation.base.extensions.applyLanguageAndVoiceUnitOptions
+import com.mapbox.navigation.base.internal.NavigationRouterV2
 import com.mapbox.navigation.base.internal.trip.notification.TripNotificationInterceptorOwner
 import com.mapbox.navigation.base.options.HistoryRecorderOptions
 import com.mapbox.navigation.base.options.NavigationOptions
@@ -47,6 +48,7 @@ import com.mapbox.navigation.core.arrival.ArrivalController
 import com.mapbox.navigation.core.arrival.ArrivalObserver
 import com.mapbox.navigation.core.arrival.ArrivalProgressObserver
 import com.mapbox.navigation.core.arrival.AutoArrivalController
+import com.mapbox.navigation.core.directions.LegacyNavigationRouterAdapter
 import com.mapbox.navigation.core.directions.LegacyRouterAdapter
 import com.mapbox.navigation.core.directions.session.DirectionsSession
 import com.mapbox.navigation.core.directions.session.RoutesExtra
@@ -286,26 +288,25 @@ class MapboxNavigation @VisibleForTesting internal constructor(
         )
     }
 
-    private val currentIndicesSnapshotProvider =
-        NavigationComponentProvider.createCurrentIndicesSnapshotProvider()
+    private val currentIndicesProvider =
+        NavigationComponentProvider.createCurrentIndicesProvider()
 
     // Router provided via @Modules, might be outer
-    private val moduleRouter: NavigationRouter by lazy {
+    private val moduleRouter: NavigationRouterV2 by lazy {
         val result = MapboxModuleProvider.createModule<Router>(MapboxModuleType.NavigationRouter) {
             paramsProvider(
                 ModuleParams.NavigationRouter(
                     accessToken
                         ?: throw RuntimeException(MAPBOX_NAVIGATION_TOKEN_EXCEPTION_ROUTER),
                     nativeRouter,
-                    threadController,
-                    currentIndicesSnapshotProvider
+                    threadController
                 )
             )
         }
-        if (result is NavigationRouter) {
-            result
-        } else {
-            LegacyRouterAdapter(result)
+        when (result) {
+            is NavigationRouterV2 -> result
+            is NavigationRouter -> LegacyNavigationRouterAdapter(result)
+            else -> LegacyNavigationRouterAdapter(LegacyRouterAdapter(result))
         }
     }
 
@@ -479,7 +480,7 @@ class MapboxNavigation @VisibleForTesting internal constructor(
             threadController,
         )
 
-        tripSession.registerRouteProgressObserver(currentIndicesSnapshotProvider)
+        tripSession.registerRouteProgressObserver(currentIndicesProvider)
         tripSession.registerStateObserver(navigationSession)
         tripSession.registerStateObserver(historyRecordingStateHandler)
 
@@ -534,7 +535,7 @@ class MapboxNavigation @VisibleForTesting internal constructor(
         routeRefreshController = RouteRefreshControllerProvider.createRouteRefreshController(
             navigationOptions.routeRefreshOptions,
             directionsSession,
-            currentIndicesSnapshotProvider,
+            currentIndicesProvider,
         )
 
         defaultRerouteController = MapboxRerouteController(
@@ -1613,7 +1614,7 @@ class MapboxNavigation @VisibleForTesting internal constructor(
 
     private fun createInternalRoutesObserver() = RoutesObserver { result ->
         latestLegIndex = null
-        currentIndicesSnapshotProvider.clear()
+        currentIndicesProvider.clear()
         if (result.navigationRoutes.isNotEmpty()) {
             routeScope.launch {
                 val refreshed = routeRefreshController.refresh(

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

@@ -1,9 +1,9 @@
 package com.mapbox.navigation.core
 
 import android.content.Context
+import com.mapbox.navigation.base.internal.NavigationRouterV2
 import com.mapbox.navigation.base.options.DeviceProfile
 import com.mapbox.navigation.base.options.NavigationOptions
-import com.mapbox.navigation.base.route.NavigationRouter
 import com.mapbox.navigation.base.trip.notification.TripNotification
 import com.mapbox.navigation.core.accounts.BillingController
 import com.mapbox.navigation.core.arrival.ArrivalProgressObserver
@@ -26,7 +26,7 @@ import com.mapbox.navigator.TilesConfig
 
 internal object NavigationComponentProvider {
     fun createDirectionsSession(
-        router: NavigationRouter,
+        router: NavigationRouterV2,
     ): DirectionsSession = MapboxDirectionsSession(router)
 
     fun createNativeNavigator(
@@ -94,6 +94,6 @@ internal object NavigationComponentProvider {
         initialState: NavigationSessionState
     ): HistoryRecordingStateHandler = HistoryRecordingStateHandler(initialState)
 
-    fun createCurrentIndicesSnapshotProvider(): CurrentIndicesSnapshotProvider =
-        CurrentIndicesSnapshotProvider()
+    fun createCurrentIndicesProvider(): CurrentIndicesProvider =
+        CurrentIndicesProvider()
 }