Introduce multiple back stack compatible Navigator APIs

The current Navigator APIs operated on a single
destination at a time, which made it impossible to
coordinate a set of navigate() calls or a popBackStack()
that would pop multiple destinations at once - both
of which are required to fully support the saving
and restoring of state needed to support
multiple back stacks.

In addition to supporting batch operations, these
new Navigator APIs give the Navigator direct access
to the NavBackStackEntry instance that is being
navigated to. This allows the new APIs to be
backward compatible - translating calls to the new
APIs back into the old API internally while still
allowing a Navigator to fully switch over to the
new APIs (and just not call the superclass
implementation).

The NavController was fully rebuilt to only call
the new APIs while continuing to work with
existing Navigator implementations without any
changes. The previous temporary solution required
for TestNavigator (calling the NavigatorState APIs
from the old navigate/popBackStack() methods) was
removed entirely as the default implementations
correctly update the NavigatorState.

Relnote: N/A
BUG: 80029773
Test: existing tests for all Navigators pass
Change-Id: Ia1ff09a4b76f15a35d6a9c520687033d6f1565a7

diff --git a/navigation/navigation-common/api/restricted_current.txt b/navigation/navigation-common/api/restricted_current.txt
index ea02b21..ebd7e05 100644
--- a/navigation/navigation-common/api/restricted_current.txt
+++ b/navigation/navigation-common/api/restricted_current.txt

@@ -285,7 +285,6 @@
     ctor public NavGraphNavigator(androidx.navigation.NavigatorProvider navigatorProvider);
     method public androidx.navigation.NavGraph createDestination();
     method public androidx.navigation.NavDestination? navigate(androidx.navigation.NavGraph destination, android.os.Bundle? args, androidx.navigation.NavOptions? navOptions, androidx.navigation.Navigator.Extras? navigatorExtras);
-    method public boolean popBackStack();
   }
 
   public final class NavOptions {
@@ -413,11 +412,14 @@
     method public abstract D createDestination();
     method protected final androidx.navigation.NavigatorState getState();
     method public final boolean isAttached();
-    method public abstract androidx.navigation.NavDestination? navigate(D destination, android.os.Bundle? args, androidx.navigation.NavOptions? navOptions, androidx.navigation.Navigator.Extras? navigatorExtras);
+    method public void navigate(java.util.List<androidx.navigation.NavBackStackEntry> entries, androidx.navigation.NavOptions? navOptions, androidx.navigation.Navigator.Extras? navigatorExtras);
+    method public androidx.navigation.NavDestination? navigate(D destination, android.os.Bundle? args, androidx.navigation.NavOptions? navOptions, androidx.navigation.Navigator.Extras? navigatorExtras);
     method @CallSuper public void onAttach(androidx.navigation.NavigatorState state);
+    method public void onLaunchSingleTop(androidx.navigation.NavBackStackEntry backStackEntry);
     method public void onRestoreState(android.os.Bundle savedState);
     method public android.os.Bundle? onSaveState();
-    method public abstract boolean popBackStack();
+    method public void popBackStack(androidx.navigation.NavBackStackEntry popUpTo, boolean savedState);
+    method public boolean popBackStack();
     property public final boolean isAttached;
     property protected final androidx.navigation.NavigatorState state;
   }