Add COMMAND_RELEASE to set whether Player instances can be released

This wasn't added so far because releasing is always allowed from a
MediaController (as it just releases the connection, not the session
player). But Player instances can be created for other purposes and
the receiver of a Player instance should not always be allowed to
call release if it doesn't own the player resource.

PiperOrigin-RevId: 519121122

extensions/cast/src/main/java/com/google/android/exoplayer2/ext/cast/CastPlayer.java

@@ -106,7 +106,8 @@ public final class CastPlayer extends BasePlayer {
               COMMAND_SET_MEDIA_ITEMS_METADATA,
               COMMAND_SET_MEDIA_ITEM,
               COMMAND_CHANGE_MEDIA_ITEMS,
-              COMMAND_GET_TRACKS)
+              COMMAND_GET_TRACKS,
+              COMMAND_RELEASE)
           .build();
 
   public static final float MIN_SPEED_SUPPORTED = 0.5f;

extensions/cast/src/test/java/com/google/android/exoplayer2/ext/cast/CastPlayerTest.java

@@ -1372,6 +1372,7 @@ public class CastPlayerTest {
     assertThat(castPlayer.isCommandAvailable(COMMAND_ADJUST_DEVICE_VOLUME)).isFalse();
     assertThat(castPlayer.isCommandAvailable(COMMAND_SET_VIDEO_SURFACE)).isFalse();
     assertThat(castPlayer.isCommandAvailable(COMMAND_GET_TEXT)).isFalse();
+    assertThat(castPlayer.isCommandAvailable(Player.COMMAND_RELEASE)).isTrue();
   }
 
   @Test

library/common/src/main/java/com/google/android/exoplayer2/Player.java

@@ -383,6 +383,7 @@ public interface Player {
         COMMAND_GET_TEXT,
         COMMAND_SET_TRACK_SELECTION_PARAMETERS,
         COMMAND_GET_TRACKS,
+        COMMAND_RELEASE
       };
 
       private final FlagSet.Builder flagsBuilder;
@@ -1430,6 +1431,7 @@ public interface Player {
    *   <li>{@link #COMMAND_GET_TEXT}
    *   <li>{@link #COMMAND_SET_TRACK_SELECTION_PARAMETERS}
    *   <li>{@link #COMMAND_GET_TRACKS}
+   *   <li>{@link #COMMAND_RELEASE}
    * </ul>
    */
   // @Target list includes both 'default' targets and TYPE_USE, to ensure backwards compatibility
@@ -1470,6 +1472,7 @@ public interface Player {
     COMMAND_GET_TEXT,
     COMMAND_SET_TRACK_SELECTION_PARAMETERS,
     COMMAND_GET_TRACKS,
+    COMMAND_RELEASE,
   })
   @interface Command {}
   /**
@@ -1825,6 +1828,13 @@ public interface Player {
    * #isCommandAvailable(int) available}.
    */
   int COMMAND_GET_TRACKS = 30;
+  /**
+   * Command to release the player.
+   *
+   * <p>The {@link #release()} method must only be called if this command is {@linkplain
+   * #isCommandAvailable(int) available}.
+   */
+  int COMMAND_RELEASE = 32;
 
   /** Represents an invalid {@link Command}. */
   int COMMAND_INVALID = -1;
@@ -2505,8 +2515,10 @@ public interface Player {
   /**
    * Releases the player. This method must be called when the player is no longer required. The
    * player must not be used after calling this method.
+   *
+   * <p>This method must only be called if {@link #COMMAND_RELEASE} is {@linkplain
+   * #getAvailableCommands() available}.
    */
-  // TODO(b/261158047): Document that COMMAND_RELEASE must be available once it exists.
   void release();
 
   /**

library/common/src/main/java/com/google/android/exoplayer2/SimpleBasePlayer.java

@@ -2341,7 +2341,7 @@ public abstract class SimpleBasePlayer extends BasePlayer {
     verifyApplicationThreadAndInitState();
     // Use a local copy to ensure the lambda below uses the current state value.
     State state = this.state;
-    if (released) { // TODO(b/261158047): Replace by !shouldHandleCommand(Player.COMMAND_RELEASE)
+    if (!shouldHandleCommand(Player.COMMAND_RELEASE)) {
       return;
     }
     updateStateForPendingOperation(
@@ -2840,10 +2840,11 @@ public abstract class SimpleBasePlayer extends BasePlayer {
   /**
    * Handles calls to {@link Player#release}.
    *
+   * <p>Will only be called if {@link Player#COMMAND_RELEASE} is available.
+   *
    * @return A {@link ListenableFuture} indicating the completion of all immediate {@link State}
    *     changes caused by this call.
    */
-  // TODO(b/261158047): Add that this method will only be called if COMMAND_RELEASE is available.
   @ForOverride
   protected ListenableFuture<?> handleRelease() {
     throw new IllegalStateException("Missing implementation to handle COMMAND_RELEASE");

library/common/src/test/java/com/google/android/exoplayer2/SimpleBasePlayerTest.java

@@ -61,7 +61,6 @@ import java.util.List;
 import java.util.concurrent.atomic.AtomicBoolean;
 import java.util.concurrent.atomic.AtomicInteger;
 import java.util.concurrent.atomic.AtomicReference;
-import org.junit.Ignore;
 import org.junit.Test;
 import org.junit.runner.RunWith;
 import org.robolectric.shadows.ShadowLooper;
@@ -2480,14 +2479,12 @@ public class SimpleBasePlayerTest {
     verifyNoMoreInteractions(listener);
   }
 
-  @Ignore("b/261158047: Ignore test while Player.COMMAND_RELEASE doesn't exist.")
   @Test
   public void release_withoutAvailableCommand_isNotForwarded() {
     State state =
         new State.Builder()
-            // TODO(b/261158047): Uncomment once test is no longer ignored.
-            // .setAvailableCommands(
-            //    new Commands.Builder().addAllCommands().remove(Player.COMMAND_RELEASE).build())
+            .setAvailableCommands(
+                new Commands.Builder().addAllCommands().remove(Player.COMMAND_RELEASE).build())
             .build();
     AtomicBoolean callForwarded = new AtomicBoolean();
     SimpleBasePlayer player =

library/core/src/main/java/com/google/android/exoplayer2/ExoPlayerImpl.java

@@ -300,7 +300,8 @@ import java.util.concurrent.TimeoutException;
                   COMMAND_SET_DEVICE_VOLUME,
                   COMMAND_ADJUST_DEVICE_VOLUME,
                   COMMAND_SET_VIDEO_SURFACE,
-                  COMMAND_GET_TEXT)
+                  COMMAND_GET_TEXT,
+                  COMMAND_RELEASE)
               .addIf(
                   COMMAND_SET_TRACK_SELECTION_PARAMETERS, trackSelector.isSetParametersSupported())
               .build();

library/core/src/test/java/com/google/android/exoplayer2/ExoPlayerTest.java

@@ -27,6 +27,7 @@ import static com.google.android.exoplayer2.Player.COMMAND_GET_TRACKS;
 import static com.google.android.exoplayer2.Player.COMMAND_GET_VOLUME;
 import static com.google.android.exoplayer2.Player.COMMAND_PLAY_PAUSE;
 import static com.google.android.exoplayer2.Player.COMMAND_PREPARE;
+import static com.google.android.exoplayer2.Player.COMMAND_RELEASE;
 import static com.google.android.exoplayer2.Player.COMMAND_SEEK_BACK;
 import static com.google.android.exoplayer2.Player.COMMAND_SEEK_FORWARD;
 import static com.google.android.exoplayer2.Player.COMMAND_SEEK_IN_CURRENT_MEDIA_ITEM;
@@ -9142,6 +9143,7 @@ public final class ExoPlayerTest {
     assertThat(player.isCommandAvailable(COMMAND_GET_TEXT)).isTrue();
     assertThat(player.isCommandAvailable(COMMAND_SET_TRACK_SELECTION_PARAMETERS)).isTrue();
     assertThat(player.isCommandAvailable(COMMAND_GET_TRACKS)).isTrue();
+    assertThat(player.isCommandAvailable(COMMAND_RELEASE)).isTrue();
   }
 
   @Test
@@ -12493,7 +12495,8 @@ public final class ExoPlayerTest {
         COMMAND_SET_VIDEO_SURFACE,
         COMMAND_GET_TEXT,
         COMMAND_SET_TRACK_SELECTION_PARAMETERS,
-        COMMAND_GET_TRACKS);
+        COMMAND_GET_TRACKS,
+        COMMAND_RELEASE);
     if (!isTimelineEmpty) {
       builder.add(COMMAND_SEEK_TO_PREVIOUS);
     }