Add MediaRouter2#stop

MediaRouter2#stop stops the current media routing and
invokes the callback onStopped.
According to the change transferTo doesn't accept null route
as its argument.

CTS is changed as well.

Bug: 150472061
Test: CTS tests related to media router2

Change-Id: I6bc7b7ad394189e035e4c018677efb94e5497c85

2 files changed, 41 insertions, 25 deletions

diff --git a/api/current.txt b/api/current.txt
index 16475e238442..3acf2f93d8f3 100644
--- a/api/current.txt
+++ b/api/current.txt
@@ -27062,7 +27062,8 @@ package android.media {
     method public void registerRouteCallback(@NonNull java.util.concurrent.Executor, @NonNull android.media.MediaRouter2.RouteCallback, @NonNull android.media.RouteDiscoveryPreference);
     method public void registerTransferCallback(@NonNull java.util.concurrent.Executor, @NonNull android.media.MediaRouter2.TransferCallback);
     method public void setOnGetControllerHintsListener(@Nullable android.media.MediaRouter2.OnGetControllerHintsListener);
-    method public void transferTo(@Nullable android.media.MediaRoute2Info);
+    method public void stop();
+    method public void transferTo(@NonNull android.media.MediaRoute2Info);
     method public void unregisterControllerCallback(@NonNull android.media.MediaRouter2.ControllerCallback);
     method public void unregisterRouteCallback(@NonNull android.media.MediaRouter2.RouteCallback);
     method public void unregisterTransferCallback(@NonNull android.media.MediaRouter2.TransferCallback);
@@ -27102,8 +27103,9 @@ package android.media {
 
   public abstract static class MediaRouter2.TransferCallback {
     ctor public MediaRouter2.TransferCallback();
+    method public void onStopped(@NonNull android.media.MediaRouter2.RoutingController);
     method public void onTransferFailed(@NonNull android.media.MediaRoute2Info);
-    method public void onTransferred(@NonNull android.media.MediaRouter2.RoutingController, @Nullable android.media.MediaRouter2.RoutingController);
+    method public void onTransferred(@NonNull android.media.MediaRouter2.RoutingController, @NonNull android.media.MediaRouter2.RoutingController);
   }
 
   public class MediaScannerConnection implements android.content.ServiceConnection {
diff --git a/media/java/android/media/MediaRouter2.java b/media/java/android/media/MediaRouter2.java
index fd2408935fff..59cb78716ecb 100644
--- a/media/java/android/media/MediaRouter2.java
+++ b/media/java/android/media/MediaRouter2.java
@@ -372,7 +372,9 @@ public class MediaRouter2 {
      * @see TransferCallback#onTransferred
      * @see TransferCallback#onTransferFailed
      */
-    public void transferTo(@Nullable MediaRoute2Info route) {
+    public void transferTo(@NonNull MediaRoute2Info route) {
+        Objects.requireNonNull(route, "route must not be null");
+
         List<RoutingController> controllers = getControllers();
         RoutingController controller = controllers.get(controllers.size() - 1);
 
@@ -380,19 +382,25 @@ public class MediaRouter2 {
     }
 
     /**
+     * Stops the current media routing. If the {@link #getSystemController() system controller}
+     * controls the media routing, this method is a no-op.
+     */
+    public void stop() {
+        List<RoutingController> controllers = getControllers();
+        RoutingController controller = controllers.get(controllers.size() - 1);
+
+        controller.release();
+    }
+
+    /**
      * Transfers the media of a routing controller to the given route.
      * @param controller a routing controller controlling media routing.
-     * @param route the route you want to transfer the media to. Pass {@code null} to stop
-     *              routing controlled by the given controller.
+     * @param route the route you want to transfer the media to.
      * @hide
      */
-    void transfer(@NonNull RoutingController controller, @Nullable MediaRoute2Info route) {
+    void transfer(@NonNull RoutingController controller, @NonNull MediaRoute2Info route) {
         Objects.requireNonNull(controller, "controller must not be null");
-
-        if (route == null) {
-            controller.release();
-            return;
-        }
+        Objects.requireNonNull(route, "route must not be null");
 
         // TODO: Check thread-safety
         if (!mRoutes.containsKey(route.getId())) {
@@ -676,7 +684,7 @@ public class MediaRouter2 {
 
         if (removed) {
             matchingController.release();
-            notifyControllerReleased(matchingController);
+            notifyStopped(matchingController);
         }
     }
 
@@ -733,16 +741,16 @@ public class MediaRouter2 {
         }
     }
 
-    private void notifyControllerUpdated(RoutingController controller) {
-        for (ControllerCallbackRecord record: mControllerCallbackRecords) {
-            record.mExecutor.execute(() -> record.mCallback.onControllerUpdated(controller));
+    private void notifyStopped(RoutingController controller) {
+        for (TransferCallbackRecord record: mTransferCallbackRecords) {
+            record.mExecutor.execute(
+                    () -> record.mTransferCallback.onStopped(controller));
         }
     }
 
-    private void notifyControllerReleased(RoutingController controller) {
-        for (TransferCallbackRecord record: mTransferCallbackRecords) {
-            record.mExecutor.execute(
-                    () -> record.mTransferCallback.onTransferred(controller, null));
+    private void notifyControllerUpdated(RoutingController controller) {
+        for (ControllerCallbackRecord record: mControllerCallbackRecords) {
+            record.mExecutor.execute(() -> record.mCallback.onControllerUpdated(controller));
         }
     }
 
@@ -783,20 +791,26 @@ public class MediaRouter2 {
          * This can happen by calling {@link #transferTo(MediaRoute2Info)} or
          * {@link RoutingController#release()}.
          *
-         * @param oldController the previous controller that controlled routing.
-         * @param newController the new controller to control routing or {@code null} if the
-         *                      previous controller is released.
+         * @param oldController the previous controller that controlled routing
+         * @param newController the new controller to control routing
          * @see #transferTo(MediaRoute2Info)
          */
         public void onTransferred(@NonNull RoutingController oldController,
-                @Nullable RoutingController newController) {}
+                @NonNull RoutingController newController) {}
 
         /**
          * Called when {@link #transferTo(MediaRoute2Info)} failed.
          *
-         * @param requestedRoute the route info which was used for the transfer.
+         * @param requestedRoute the route info which was used for the transfer
          */
         public void onTransferFailed(@NonNull MediaRoute2Info requestedRoute) {}
+
+        /**
+         * Called when a media routing stops. It can be stopped by a user or a provider.
+         *
+         * @param controller the controller that controlled the stopped media routing.
+         */
+        public void onStopped(@NonNull RoutingController controller) { }
     }
 
     /**
@@ -1181,7 +1195,7 @@ public class MediaRouter2 {
             }
 
             if (removed) {
-                mHandler.post(() -> notifyControllerReleased(RoutingController.this));
+                mHandler.post(() -> notifyStopped(RoutingController.this));
             }
 
             if (stub != null) {