Remove experimental from MapboxNavigationApp

CHANGELOG.md

@@ -9,6 +9,8 @@ Mapbox welcomes participation and contributions from everyone.
 
 #### Bug fixes and improvements
 - Fixed an issue where `NavigationView` switches from Active Guidance to Free Drive state after rotating device when replay is enabled. [#6140](https://github.com/mapbox/mapbox-navigation-android/pull/6140)
+- Commit to a stable api for `MapboxNavigationApp` and `MapboxNavigationObserver`. This deprecates the `MapboxNavigationProvider`. [#6143](https://github.com/mapbox/mapbox-navigation-android/pull/6143)
+
 
 ## Mapbox Navigation SDK 2.7.0-rc.2 - 11 August, 2022
 ### Changelog

libnavigation-core/api/current.txt

@@ -94,12 +94,12 @@ package com.mapbox.navigation.core {
  public final class MapboxNavigationKt {
  }
 
- @UiThread public final class MapboxNavigationProvider {
- method public static com.mapbox.navigation.core.MapboxNavigation create(com.mapbox.navigation.base.options.NavigationOptions navigationOptions);
- method public static void destroy();
- method public static boolean isCreated();
- method public static com.mapbox.navigation.core.MapboxNavigation retrieve();
- field public static final com.mapbox.navigation.core.MapboxNavigationProvider INSTANCE;
+ @Deprecated @UiThread public final class MapboxNavigationProvider {
+ method @Deprecated public static com.mapbox.navigation.core.MapboxNavigation create(com.mapbox.navigation.base.options.NavigationOptions navigationOptions);
+ method @Deprecated public static void destroy();
+ method @Deprecated public static boolean isCreated();
+ method @Deprecated public static com.mapbox.navigation.core.MapboxNavigation retrieve();
+ field @Deprecated public static final com.mapbox.navigation.core.MapboxNavigationProvider INSTANCE;
  }
 
  public interface NavigationVersionSwitchObserver {
@@ -310,7 +310,7 @@ package com.mapbox.navigation.core.history.model {
 
 package com.mapbox.navigation.core.lifecycle {
 
- @com.mapbox.navigation.base.ExperimentalPreviewMapboxNavigationAPI public final class MapboxNavigationApp {
+ public final class MapboxNavigationApp {
  method public com.mapbox.navigation.core.lifecycle.MapboxNavigationApp attach(androidx.lifecycle.LifecycleOwner lifecycleOwner);
  method public com.mapbox.navigation.core.lifecycle.MapboxNavigationApp attachAllActivities(android.app.Application application);
  method public com.mapbox.navigation.core.MapboxNavigation? current();
@@ -328,12 +328,12 @@ package com.mapbox.navigation.core.lifecycle {
  field public static final com.mapbox.navigation.core.lifecycle.MapboxNavigationApp INSTANCE;
  }
 
- @com.mapbox.navigation.base.ExperimentalPreviewMapboxNavigationAPI public interface MapboxNavigationObserver {
+ public interface MapboxNavigationObserver {
  method public void onAttached(com.mapbox.navigation.core.MapboxNavigation mapboxNavigation);
  method public void onDetached(com.mapbox.navigation.core.MapboxNavigation mapboxNavigation);
  }
 
- @com.mapbox.navigation.base.ExperimentalPreviewMapboxNavigationAPI public fun interface NavigationOptionsProvider {
+ public fun interface NavigationOptionsProvider {
  method public com.mapbox.navigation.base.options.NavigationOptions createNavigationOptions();
  }
 

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

@@ -60,6 +60,7 @@ import com.mapbox.navigation.core.internal.utils.InternalUtils
 import com.mapbox.navigation.core.internal.utils.ModuleParams
 import com.mapbox.navigation.core.internal.utils.isInternalImplementation
 import com.mapbox.navigation.core.internal.utils.paramsProvider
+import com.mapbox.navigation.core.lifecycle.MapboxNavigationApp
 import com.mapbox.navigation.core.navigator.CacheHandleWrapper
 import com.mapbox.navigation.core.navigator.TilesetDescriptorFactory
 import com.mapbox.navigation.core.replay.MapboxReplayer
@@ -154,7 +155,7 @@ private const val MAPBOX_NOTIFICATION_ACTION_CHANNEL = "notificationActionButton
  * An entry point for interacting with the Mapbox Navigation SDK.
  *
  * **Only one instance of this class should be used per application process.**
- * Use [MapboxNavigationProvider] to easily manage the instance across lifecycle.
+ * Use [MapboxNavigationApp] to easily manage the instance across lifecycle.
  *
  * Feel free to visit our [docs pages and examples](https://docs.mapbox.com/android/beta/navigation/overview/) before diving in!
  *
@@ -401,7 +402,7 @@ class MapboxNavigation @VisibleForTesting internal constructor(
  * Describes whether this instance of `MapboxNavigation` has been destroyed by calling
  * [onDestroy]. Once an instance is destroyed, it cannot be used anymore.
  *
- * @see [MapboxNavigationProvider]
+ * @see [MapboxNavigationApp]
  */
  @Volatile
  var isDestroyed = false
@@ -415,7 +416,7 @@ class MapboxNavigation @VisibleForTesting internal constructor(
  """
  A different MapboxNavigation instance already exists.
  Make sure to destroy it with #onDestroy before creating a new one.
- Also see MapboxNavigationProvider for instance management assistance.
+ Also see MapboxNavigationApp for instance management assistance.
  """.trimIndent()
  )
  }
@@ -840,8 +841,9 @@ class MapboxNavigation @VisibleForTesting internal constructor(
  * versionInfo: RoadGraphVersionInfo?
  * ) {
  * if (isUpdateAvailable) {
- * mapboxNavigation.onDestroy()
- * mapboxNavigation = MapboxNavigationProvider.create(...)
+ * val currentOptions = mapboxNavigation.navigationOptions
+ * MapboxNavigationApp.disable()
+ * MapboxNavigationApp.setup(currentOptions)
  * }
  * }
  * })

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

@@ -7,6 +7,9 @@ import com.mapbox.navigation.base.options.NavigationOptions
  * Singleton responsible for ensuring there is only one MapboxNavigation instance.
  */
 @UiThread
+@Deprecated(
+ message = "Use MapboxNavigationApp to attach MapboxNavigation to lifecycles."
+)
 object MapboxNavigationProvider {
  @Volatile
  private var mapboxNavigation: MapboxNavigation? = null
@@ -18,6 +21,9 @@ object MapboxNavigationProvider {
  * @param navigationOptions
  */
  @JvmStatic
+ @Deprecated(
+ message = "Set the navigation options with MapboxNavigationApp.setup"
+ )
  fun create(navigationOptions: NavigationOptions): MapboxNavigation {
  mapboxNavigation?.onDestroy()
  mapboxNavigation = MapboxNavigation(
@@ -33,6 +39,10 @@ object MapboxNavigationProvider {
  * @see [isCreated]
  */
  @JvmStatic
+ @Deprecated(
+ message = "Get the MapboxNavigation instance through MapboxNavigationObserver or" +
+ " MapboxNavigationApp.current"
+ )
  fun retrieve(): MapboxNavigation {
  if (!isCreated()) {
  throw RuntimeException("Need to create MapboxNavigation before using it.")
@@ -45,6 +55,9 @@ object MapboxNavigationProvider {
  * Destroy MapboxNavigation when your process/activity exits.
  */
  @JvmStatic
+ @Deprecated(
+ message = "MapboxNavigationApp will determine when to destroy MapboxNavigation instances"
+ )
  fun destroy() {
  mapboxNavigation?.onDestroy()
  mapboxNavigation = null

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

@@ -9,10 +9,8 @@ import androidx.lifecycle.DefaultLifecycleObserver
 import androidx.lifecycle.Lifecycle
 import androidx.lifecycle.LifecycleOwner
 import androidx.lifecycle.LifecycleRegistry
-import com.mapbox.navigation.base.ExperimentalPreviewMapboxNavigationAPI
 import com.mapbox.navigation.utils.internal.logI
 
-@ExperimentalPreviewMapboxNavigationAPI
 internal class CarAppLifecycleOwner : LifecycleOwner {
 
  // Keeps track of the activities created and foregrounded

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

@@ -4,7 +4,6 @@ import android.app.Activity
 import android.app.Application
 import androidx.lifecycle.Lifecycle
 import androidx.lifecycle.LifecycleOwner
-import com.mapbox.navigation.base.ExperimentalPreviewMapboxNavigationAPI
 import com.mapbox.navigation.base.options.NavigationOptions
 import com.mapbox.navigation.core.MapboxNavigation
 import kotlin.reflect.KClass
@@ -53,7 +52,6 @@ import kotlin.reflect.KClass
  * }
  * ```
  */
-@ExperimentalPreviewMapboxNavigationAPI
 object MapboxNavigationApp {
 
  // The singleton MapboxNavigationApp is not good for unit testing.

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

@@ -2,7 +2,6 @@ package com.mapbox.navigation.core.lifecycle
 
 import android.app.Application
 import androidx.lifecycle.LifecycleOwner
-import com.mapbox.navigation.base.ExperimentalPreviewMapboxNavigationAPI
 import com.mapbox.navigation.core.MapboxNavigation
 import com.mapbox.navigation.utils.internal.logI
 import kotlin.reflect.KClass
@@ -11,7 +10,6 @@ import kotlin.reflect.KClass
  * This is a testable version of [MapboxNavigationApp]. Please refer to the singleton
  * for documented functions and expected behaviors.
  */
-@ExperimentalPreviewMapboxNavigationAPI
 internal class MapboxNavigationAppDelegate {
  private val mapboxNavigationOwner by lazy { MapboxNavigationOwner() }
  private val carAppLifecycleOwner by lazy { CarAppLifecycleOwner() }

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

@@ -2,8 +2,8 @@ package com.mapbox.navigation.core.lifecycle
 
 import androidx.lifecycle.Lifecycle
 import androidx.lifecycle.LifecycleOwner
-import com.mapbox.navigation.base.ExperimentalPreviewMapboxNavigationAPI
 import com.mapbox.navigation.core.MapboxNavigation
+
 /**
  * Defines an object that needs to interact with or observe [MapboxNavigation]. Use the
  * [MapboxNavigationApp] singleton to register and unregister observers with
@@ -49,7 +49,6 @@ import com.mapbox.navigation.core.MapboxNavigation
  * }
  * ```
  */
-@ExperimentalPreviewMapboxNavigationAPI
 interface MapboxNavigationObserver {
  /**
  * Signals that the [mapboxNavigation] instance is ready for use. Use this function to

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

@@ -2,14 +2,12 @@ package com.mapbox.navigation.core.lifecycle
 
 import androidx.lifecycle.DefaultLifecycleObserver
 import androidx.lifecycle.LifecycleOwner
-import com.mapbox.navigation.base.ExperimentalPreviewMapboxNavigationAPI
 import com.mapbox.navigation.core.MapboxNavigation
 import com.mapbox.navigation.core.MapboxNavigationProvider
 import com.mapbox.navigation.utils.internal.logI
 import java.util.concurrent.CopyOnWriteArraySet
 import kotlin.reflect.KClass
 
-@ExperimentalPreviewMapboxNavigationAPI
 internal class MapboxNavigationOwner {
 
  private lateinit var navigationOptionsProvider: NavigationOptionsProvider

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

@@ -1,12 +1,10 @@
 package com.mapbox.navigation.core.lifecycle
 
-import com.mapbox.navigation.base.ExperimentalPreviewMapboxNavigationAPI
 import com.mapbox.navigation.base.options.NavigationOptions
 
 /**
  * Represents a function that returns [NavigationOptions]
  */
-@ExperimentalPreviewMapboxNavigationAPI
 fun interface NavigationOptionsProvider {
 
  /**