NAVAND-5543 API to switch between alternatives (#8985) (#9097)

GitOrigin-RevId: 82d210ac2089007a202f897824bd6408c63875bf

Author: VysotskiVadim

changelog/unreleased/features/8985.md

@@ -0,0 +1 @@
+* Added experimental `MapboxNavigation#switchToAlternativeRoute` that support switching between alternative routes with different amount of waypoints.

instrumentation-tests/src/androidTest/java/com/mapbox/navigation/instrumentation_tests/core/RouteAlternativesTest.kt

@@ -9,8 +9,10 @@ import com.mapbox.geojson.Point
 import com.mapbox.navigation.base.ExperimentalMapboxNavigationAPI
 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.route.routeOptions
 import com.mapbox.navigation.base.route.NavigationRoute
+import com.mapbox.navigation.base.trip.model.RouteProgressState
 import com.mapbox.navigation.core.MapboxNavigation
 import com.mapbox.navigation.core.directions.session.RoutesExtra
 import com.mapbox.navigation.core.internal.extensions.flowLocationMatcherResult
@@ -23,13 +25,15 @@ import com.mapbox.navigation.testing.ui.utils.coroutines.routeProgressUpdates
 import com.mapbox.navigation.testing.ui.utils.coroutines.routesUpdates
 import com.mapbox.navigation.testing.ui.utils.coroutines.sdkTest
 import com.mapbox.navigation.testing.ui.utils.coroutines.setNavigationRoutesAsync
+import com.mapbox.navigation.testing.ui.utils.coroutines.switchToAlternativeAsync
 import com.mapbox.navigation.testing.utils.history.MapboxHistoryTestRule
 import com.mapbox.navigation.testing.utils.http.MockDirectionsRequestHandler
 import com.mapbox.navigation.testing.utils.http.MockDynamicDirectionsRefreshHandler
 import com.mapbox.navigation.testing.utils.location.MockLocationReplayerRule
 import com.mapbox.navigation.testing.utils.location.stayOnPosition
 import com.mapbox.navigation.testing.utils.openRawResource
 import com.mapbox.navigation.testing.utils.readRawFileText
+import com.mapbox.navigation.testing.utils.routes.RoutesProvider
 import com.mapbox.navigation.testing.utils.withMapboxNavigation
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.CoroutineStart
@@ -416,6 +420,102 @@ class RouteAlternativesTest : BaseCoreNoCleanUpTest() {
         }
     }
 
+    @Test
+    fun switch_from_multi_leg_primary_to_single_leg_alternative_and_back() = sdkTest {
+        withMapboxNavigation(
+            historyRecorderRule = mapboxHistoryTestRule,
+        ) { mapboxNavigation ->
+            val mockRoute = RoutesProvider.dc_short_alternative_has_more_legs(context)
+            mockWebServerRule.requestHandlers.addAll(mockRoute.mockRequestHandlers)
+
+            val routes = mapboxNavigation.requestRoutes(
+                RouteOptions.builder()
+                    .applyDefaultNavigationOptions()
+                    .applyLanguageAndVoiceUnitOptions(context)
+                    .baseUrl(mockWebServerRule.baseUrl)
+                    .waypointsPerRoute(true)
+                    .coordinatesList(mockRoute.routeWaypoints).build(),
+            ).getSuccessfulResultOrThrowException().routes
+
+            mockLocationReplayerRule.playRoute(
+                routes[0].directionsRoute,
+                eventsToDrop = 15,
+            )
+            mapboxNavigation.startTripSession()
+            mapboxNavigation.setNavigationRoutes(routes)
+
+            mapboxNavigation.routeProgressUpdates()
+                .filter {
+                    it.currentLegProgress?.legIndex == 0 &&
+                        it.currentRouteGeometryIndex > 16
+                }
+                .first()
+
+            mapboxNavigation.switchToAlternativeRoute(routes[1])
+
+            val routeProgress = mapboxNavigation.routeProgressUpdates()
+                .first {
+                    it.currentState == RouteProgressState.TRACKING &&
+                        it.navigationRoute.id == routes[1].id
+                }
+            assertEquals(
+                1,
+                routeProgress.remainingWaypoints,
+            )
+        }
+    }
+
+    @Test
+    fun switch_to_alternative_when_no_routes_are_set() = sdkTest {
+        withMapboxNavigation(
+            historyRecorderRule = mapboxHistoryTestRule,
+        ) { mapboxNavigation ->
+            setupMockRequestHandlers()
+            val routes = mapboxNavigation.requestNavigationRoutes(startCoordinates)
+            val result = mapboxNavigation.switchToAlternativeAsync(routes[0])
+            assertTrue(result.isError)
+        }
+    }
+
+    @Test
+    fun switch_to_not_tracking_alternative() = sdkTest {
+        withMapboxNavigation(
+            historyRecorderRule = mapboxHistoryTestRule,
+        ) { mapboxNavigation ->
+            setupMockRequestHandlers()
+            val routes = mapboxNavigation.requestNavigationRoutes(startCoordinates)
+            val differentRoutes = mapboxNavigation.requestNavigationRoutes(continueCoordinates)
+
+            stayOnPosition(startCoordinates.first(), 0f) {
+                mapboxNavigation.startTripSession()
+                mapboxNavigation.setNavigationRoutes(routes)
+                mapboxNavigation.routeProgressUpdates().first()
+
+                val result = mapboxNavigation.switchToAlternativeAsync(differentRoutes[0])
+                assertTrue(result.isError)
+            }
+        }
+    }
+
+    @Test
+    fun use_primary_during_switching_to_alternative() = sdkTest {
+        withMapboxNavigation(
+            historyRecorderRule = mapboxHistoryTestRule,
+        ) { mapboxNavigation ->
+            setupMockRequestHandlers()
+            val routes = mapboxNavigation.requestNavigationRoutes(startCoordinates)
+
+            stayOnPosition(startCoordinates.first(), 0f) {
+                mapboxNavigation.startTripSession()
+                mapboxNavigation.setNavigationRoutes(routes)
+                mapboxNavigation.routeProgressUpdates().first()
+
+                val result = mapboxNavigation.switchToAlternativeAsync(routes.first())
+                assertTrue(result.isError)
+            }
+        }
+    }
+
     private fun setupMockRequestHandlers() {
         // Nav-native requests alternate routes, so we are only
         // ensuring the initial route has alternatives.

libtesting-ui/src/main/java/com/mapbox/navigation/testing/ui/utils/coroutines/Adapters.kt

@@ -216,6 +216,14 @@ suspend fun MapboxNavigation.setNavigationRoutesAsync(
     setNavigationRoutes(routes, initialLegIndex, callback)
 }
 
+@ExperimentalPreviewMapboxNavigationAPI
+suspend fun MapboxNavigation.switchToAlternativeAsync(
+    alternativeRoute: NavigationRoute,
+) = suspendCoroutine<Expected<RoutesSetError, RoutesSetSuccess>> { continuation ->
+    val callback = RoutesSetCallback { result -> continuation.resume(result) }
+    switchToAlternativeRoute(alternativeRoute, callback)
+}
+
 sealed class RouteRequestResult {
     data class Success(
         val routes: List<NavigationRoute>,

navigation/api/current.txt

@@ -98,6 +98,7 @@ package com.mapbox.navigation.core {
     method @RequiresPermission(anyOf={android.Manifest.permission.ACCESS_COARSE_LOCATION, android.Manifest.permission.ACCESS_FINE_LOCATION}) @com.mapbox.navigation.base.ExperimentalPreviewMapboxNavigationAPI public void startTripSessionWithPermissionCheck(boolean withForegroundService = true);
     method @RequiresPermission(anyOf={android.Manifest.permission.ACCESS_COARSE_LOCATION, android.Manifest.permission.ACCESS_FINE_LOCATION}) @com.mapbox.navigation.base.ExperimentalPreviewMapboxNavigationAPI public void startTripSessionWithPermissionCheck();
     method public void stopTripSession();
+    method @com.mapbox.navigation.base.ExperimentalPreviewMapboxNavigationAPI public void switchToAlternativeRoute(com.mapbox.navigation.base.route.NavigationRoute alternativeRoute, com.mapbox.navigation.core.RoutesSetCallback? callback = null);
     method public void unregisterArrivalObserver(com.mapbox.navigation.core.arrival.ArrivalObserver arrivalObserver);
     method public void unregisterBannerInstructionsObserver(com.mapbox.navigation.core.trip.session.BannerInstructionsObserver bannerInstructionsObserver);
     method @com.mapbox.navigation.base.ExperimentalPreviewMapboxNavigationAPI public void unregisterDeveloperMetadataObserver(com.mapbox.navigation.core.DeveloperMetadataObserver developerMetadataObserver);

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

@@ -25,6 +25,7 @@ import com.mapbox.navigation.base.extensions.applyLanguageAndVoiceUnitOptions
 import com.mapbox.navigation.base.internal.accounts.SkuIdProvider
 import com.mapbox.navigation.base.internal.accounts.SkuIdProviderImpl
 import com.mapbox.navigation.base.internal.clearCache
+import com.mapbox.navigation.base.internal.extensions.internalAlternativeRouteIndices
 import com.mapbox.navigation.base.internal.performance.PerformanceTracker
 import com.mapbox.navigation.base.internal.tilestore.NavigationTileStoreOwner
 import com.mapbox.navigation.base.internal.trip.notification.TripNotificationInterceptorOwner
@@ -1070,6 +1071,52 @@ class MapboxNavigation @VisibleForTesting internal constructor(
         )
     }
 
+    /**
+     * Switches [MapboxNavigation] to alternative route, i.e. the selected alternative become primary
+     * route, while primary route becomes alternative.
+     * Limitation: switch to alternative route could be performed only when [getTripSessionState]
+     * is [TripSessionState.STARTED] and after at lest one [RouteProgress] was emitted after
+     * the latest routes update.
+     * @param alternativeRoute is an alternative route the navigation should switch to. It should be
+     * present among [getNavigationRoutes] and should not be the same as primary route.
+     * @param callback notifies about result.
+     */
+    @ExperimentalPreviewMapboxNavigationAPI
+    fun switchToAlternativeRoute(
+        alternativeRoute: NavigationRoute,
+        callback: RoutesSetCallback? = null,
+    ) {
+        val routeProgress = tripSession.getRouteProgress()
+        if (routeProgress == null) {
+            val errorMessage = "No route progress available"
+            logE(errorMessage, LOG_CATEGORY)
+            callback?.onRoutesSet(ExpectedFactory.createError(RoutesSetError(errorMessage)))
+            return
+        }
+        val alternativeIndices = routeProgress
+            .internalAlternativeRouteIndices()[alternativeRoute.id]
+        val allRoutes = getNavigationRoutes()
+        val alternativeSwitchTo = allRoutes.firstOrNull { it.id == alternativeRoute.id }
+        if (alternativeIndices == null || alternativeSwitchTo == null) {
+            val errorMessage = "Can't switch to alternative ${alternativeRoute.id} " +
+                "as it isn't present among currently tracked alternatives: " +
+                "${allRoutes.drop(1).map { it.id }}"
+            logE(errorMessage, LOG_CATEGORY)
+            callback?.onRoutesSet(
+                ExpectedFactory.createError(RoutesSetError(errorMessage)),
+            )
+            return
+        }
+        logI(LOG_CATEGORY) {
+            "Switching to ${alternativeSwitchTo.id} leg ${alternativeIndices.legIndex}"
+        }
+        val newRoutes = allRoutes.toMutableList().apply {
+            remove(alternativeSwitchTo)
+            add(0, alternativeSwitchTo)
+        }
+        setNavigationRoutes(newRoutes, alternativeIndices.legIndex)
+    }
+
     /***
      * Sets routes to preview.
      * Triggers an update in [RoutesPreviewObserver] and changes [MapboxNavigation.getRoutesPreview].