Rename PreloadMediaSource.PreloadControl methods

The IntDefs in `DefaultPreloadManager.Stage` are also renamed accordingly.

PiperOrigin-RevId: 638631357

RELEASENOTES.md

@@ -38,6 +38,9 @@
     *   Fix bug where playback moved to `STATE_ENDED` when re-preparing a
         multi-period DASH live stream after the original period was already
         removed from the manifest.
+    *   Rename `onTimelineRefreshed` to `onSourcePrepared` and `onPrepared` to
+        `onTracksSelected` in `PreloadMediaSource.PreloadControl`. Also rename
+        the IntDefs in `DefaultPreloadManager.Stage` accordingly.
 *   Transformer:
     *   Work around a decoder bug where the number of audio channels was capped
         at stereo when handling PCM input.

libraries/exoplayer/src/main/java/androidx/media3/exoplayer/source/preload/DefaultPreloadManager.java

@@ -24,7 +24,6 @@
 import androidx.annotation.IntDef;
 import androidx.annotation.Nullable;
 import androidx.media3.common.C;
-import androidx.media3.common.Timeline;
 import androidx.media3.common.util.UnstableApi;
 import androidx.media3.common.util.Util;
 import androidx.media3.exoplayer.ExoPlayer;
@@ -57,25 +56,25 @@ public final class DefaultPreloadManager extends BasePreloadManager<Integer> {
   public static class Status implements TargetPreloadStatusControl.PreloadStatus {
 
     /**
-     * Stages that for the preload status. One of {@link #STAGE_TIMELINE_REFRESHED}, {@link
-     * #STAGE_SOURCE_PREPARED} or {@link #STAGE_LOADED_TO_POSITION_MS}.
+     * Stages for the preload status. One of {@link #STAGE_SOURCE_PREPARED}, {@link
+     * #STAGE_TRACKS_SELECTED} or {@link #STAGE_LOADED_TO_POSITION_MS}.
      */
     @Documented
     @Retention(RetentionPolicy.SOURCE)
     @Target(TYPE_USE)
     @IntDef(
         value = {
-          STAGE_TIMELINE_REFRESHED,
           STAGE_SOURCE_PREPARED,
+          STAGE_TRACKS_SELECTED,
           STAGE_LOADED_TO_POSITION_MS,
         })
     public @interface Stage {}
 
-    /** The {@link PreloadMediaSource} has its {@link Timeline} refreshed. */
-    public static final int STAGE_TIMELINE_REFRESHED = 0;
+    /** The {@link PreloadMediaSource} has completed preparation. */
+    public static final int STAGE_SOURCE_PREPARED = 0;
 
-    /** The {@link PreloadMediaSource} is prepared. */
-    public static final int STAGE_SOURCE_PREPARED = 1;
+    /** The {@link PreloadMediaSource} has tracks selected. */
+    public static final int STAGE_TRACKS_SELECTED = 1;
 
     /** The {@link PreloadMediaSource} is loaded to a specific position in microseconds. */
     public static final int STAGE_LOADED_TO_POSITION_MS = 2;
@@ -205,25 +204,25 @@ public int compare(Integer o1, Integer o2) {
 
   private final class SourcePreloadControl implements PreloadMediaSource.PreloadControl {
     @Override
-    public boolean onTimelineRefreshed(PreloadMediaSource mediaSource) {
+    public boolean onSourcePrepared(PreloadMediaSource mediaSource) {
       // The PreloadMediaSource may have more data preloaded than the target preload status if it
       // has been preloaded before, thus we set `clearExceededDataFromTargetPreloadStatus` to
       // `true` to clear the exceeded data.
       return continueOrCompletePreloading(
           mediaSource,
           /* continueLoadingPredicate= */ status ->
-              status.getStage() > Status.STAGE_TIMELINE_REFRESHED,
+              status.getStage() > Status.STAGE_SOURCE_PREPARED,
           /* clearExceededDataFromTargetPreloadStatus= */ true);
     }
 
     @Override
-    public boolean onPrepared(PreloadMediaSource mediaSource) {
+    public boolean onTracksSelected(PreloadMediaSource mediaSource) {
       // Set `clearExceededDataFromTargetPreloadStatus` to `false` as clearing the exceeded data
-      // from the status STAGE_SOURCE_PREPARED is not supported.
+      // from the status STAGE_TRACKS_SELECTED is not supported.
       return continueOrCompletePreloading(
           mediaSource,
           /* continueLoadingPredicate= */ status ->
-              status.getStage() > Status.STAGE_SOURCE_PREPARED,
+              status.getStage() > Status.STAGE_TRACKS_SELECTED,
           /* clearExceededDataFromTargetPreloadStatus= */ false);
     }
 

libraries/exoplayer/src/main/java/androidx/media3/exoplayer/source/preload/PreloadMediaSource.java

@@ -63,20 +63,20 @@ public final class PreloadMediaSource extends WrappingMediaSource {
   public interface PreloadControl {
 
     /**
-     * Called from {@link PreloadMediaSource} when the {@link Timeline} is refreshed.
+     * Called from {@link PreloadMediaSource} when it has completed preparation.
      *
-     * @param mediaSource The {@link PreloadMediaSource} that has its {@link Timeline} refreshed.
+     * @param mediaSource The {@link PreloadMediaSource} that has completed preparation.
      * @return True if the {@code mediaSource} should continue preloading, false otherwise.
      */
-    boolean onTimelineRefreshed(PreloadMediaSource mediaSource);
+    boolean onSourcePrepared(PreloadMediaSource mediaSource);
 
     /**
-     * Called from {@link PreloadMediaSource} when it is prepared.
+     * Called from {@link PreloadMediaSource} when it has tracks selected.
      *
-     * @param mediaSource The {@link PreloadMediaSource} it is prepared.
+     * @param mediaSource The {@link PreloadMediaSource} that has tracks selected.
      * @return True if the {@code mediaSource} should continue preloading, false otherwise.
      */
-    boolean onPrepared(PreloadMediaSource mediaSource);
+    boolean onTracksSelected(PreloadMediaSource mediaSource);
 
     /**
      * Called from {@link PreloadMediaSource} when it requests to continue loading.
@@ -291,7 +291,7 @@ protected void prepareSourceInternal() {
   protected void onChildSourceInfoRefreshed(Timeline newTimeline) {
     this.timeline = newTimeline;
     refreshSourceInfo(newTimeline);
-    if (isUsedByPlayer() || !preloadControl.onTimelineRefreshed(PreloadMediaSource.this)) {
+    if (isUsedByPlayer() || !preloadControl.onSourcePrepared(PreloadMediaSource.this)) {
       return;
     }
     Pair<Object, Long> periodPosition =
@@ -415,7 +415,7 @@ public void onPrepared(MediaPeriod mediaPeriod) {
       if (trackSelectorResult != null) {
         preloadMediaPeriod.selectTracksForPreloading(
             trackSelectorResult.selections, periodStartPositionUs);
-        if (preloadControl.onPrepared(PreloadMediaSource.this)) {
+        if (preloadControl.onTracksSelected(PreloadMediaSource.this)) {
           preloadMediaPeriod.continueLoading(
               new LoadingInfo.Builder().setPlaybackPositionUs(periodStartPositionUs).build());
         }

libraries/exoplayer/src/test/java/androidx/media3/exoplayer/source/preload/DefaultPreloadManagerTest.java

@@ -17,7 +17,7 @@
 
 import static androidx.media3.exoplayer.source.preload.DefaultPreloadManager.Status.STAGE_LOADED_TO_POSITION_MS;
 import static androidx.media3.exoplayer.source.preload.DefaultPreloadManager.Status.STAGE_SOURCE_PREPARED;
-import static androidx.media3.exoplayer.source.preload.DefaultPreloadManager.Status.STAGE_TIMELINE_REFRESHED;
+import static androidx.media3.exoplayer.source.preload.DefaultPreloadManager.Status.STAGE_TRACKS_SELECTED;
 import static androidx.media3.test.utils.FakeMediaSourceFactory.DEFAULT_WINDOW_UID;
 import static androidx.media3.test.utils.robolectric.RobolectricUtil.runMainLooperUntil;
 import static com.google.common.truth.Truth.assertThat;
@@ -192,7 +192,7 @@ public void invalidate_withoutSettingCurrentPlayingIndex_sourcesPreloadedToTarge
           if (abs(rankingData - currentPlayingItemIndex.get()) == 1) {
             return new DefaultPreloadManager.Status(STAGE_LOADED_TO_POSITION_MS, 100L);
           } else {
-            return new DefaultPreloadManager.Status(STAGE_TIMELINE_REFRESHED);
+            return new DefaultPreloadManager.Status(STAGE_SOURCE_PREPARED);
           }
         };
     ProgressiveMediaSource.Factory mediaSourceFactory =
@@ -244,7 +244,7 @@ public void invalidate_withSettingCurrentPlayingIndex_sourcesPreloadedToTargetSt
           if (abs(rankingData - currentPlayingItemIndex.get()) == 1) {
             return new DefaultPreloadManager.Status(STAGE_LOADED_TO_POSITION_MS, 100L);
           } else {
-            return new DefaultPreloadManager.Status(STAGE_TIMELINE_REFRESHED);
+            return new DefaultPreloadManager.Status(STAGE_SOURCE_PREPARED);
           }
         };
     ProgressiveMediaSource.Factory mediaSourceFactory =
@@ -297,7 +297,7 @@ public void invalidate_sourceHandedOverToPlayerDuringPreloading_continuesPreload
     TargetPreloadStatusControl<Integer> targetPreloadStatusControl =
         rankingData -> {
           targetPreloadStatusControlCallStates.add(rankingData);
-          return new DefaultPreloadManager.Status(STAGE_TIMELINE_REFRESHED);
+          return new DefaultPreloadManager.Status(STAGE_SOURCE_PREPARED);
         };
     FakeMediaSourceFactory fakeMediaSourceFactory = new FakeMediaSourceFactory();
     DefaultPreloadManager preloadManager =
@@ -340,7 +340,7 @@ public void invalidate_beforePreloadCompletedForLastInvalidate_preloadRespectsTo
     TargetPreloadStatusControl<Integer> targetPreloadStatusControl =
         rankingData -> {
           targetPreloadStatusControlCallStates.add(rankingData);
-          return new DefaultPreloadManager.Status(STAGE_TIMELINE_REFRESHED);
+          return new DefaultPreloadManager.Status(STAGE_SOURCE_PREPARED);
         };
     FakeMediaSourceFactory fakeMediaSourceFactory = new FakeMediaSourceFactory();
     DefaultPreloadManager preloadManager =
@@ -453,9 +453,9 @@ public void invalidate_clearsDeprioritizedSources() throws Exception {
         rankingData -> {
           targetPreloadStatusControlCallStates.add(rankingData);
           if (abs(rankingData - currentPlayingIndex.get()) <= 2) {
-            return new DefaultPreloadManager.Status(STAGE_SOURCE_PREPARED);
+            return new DefaultPreloadManager.Status(STAGE_TRACKS_SELECTED);
           } else if (abs(rankingData - currentPlayingIndex.get()) == 3) {
-            return new DefaultPreloadManager.Status(STAGE_TIMELINE_REFRESHED);
+            return new DefaultPreloadManager.Status(STAGE_SOURCE_PREPARED);
           }
           return null;
         };
@@ -573,7 +573,7 @@ public void release() {
   @Test
   public void removeByMediaItems_correspondingHeldSourceRemovedAndReleased() {
     TargetPreloadStatusControl<Integer> targetPreloadStatusControl =
-        rankingData -> new DefaultPreloadManager.Status(STAGE_TIMELINE_REFRESHED);
+        rankingData -> new DefaultPreloadManager.Status(STAGE_SOURCE_PREPARED);
     MediaSource.Factory mockMediaSourceFactory = mock(MediaSource.Factory.class);
     DefaultPreloadManager preloadManager =
         new DefaultPreloadManager(
@@ -624,7 +624,7 @@ protected void releaseSourceInternal() {
   @Test
   public void removeByMediaSources_heldSourceRemovedAndReleased() {
     TargetPreloadStatusControl<Integer> targetPreloadStatusControl =
-        rankingData -> new DefaultPreloadManager.Status(STAGE_TIMELINE_REFRESHED);
+        rankingData -> new DefaultPreloadManager.Status(STAGE_SOURCE_PREPARED);
     MediaSource.Factory mockMediaSourceFactory = mock(MediaSource.Factory.class);
     DefaultPreloadManager preloadManager =
         new DefaultPreloadManager(
@@ -682,7 +682,7 @@ protected void releaseSourceInternal() {
   @Test
   public void reset_returnZeroCount_sourcesButNotRendererCapabilitiesListReleased() {
     TargetPreloadStatusControl<Integer> targetPreloadStatusControl =
-        rankingData -> new DefaultPreloadManager.Status(STAGE_TIMELINE_REFRESHED);
+        rankingData -> new DefaultPreloadManager.Status(STAGE_SOURCE_PREPARED);
     MediaSource.Factory mockMediaSourceFactory = mock(MediaSource.Factory.class);
     List<FakeRenderer> underlyingRenderers = new ArrayList<>();
     RenderersFactory renderersFactory =
@@ -753,7 +753,7 @@ protected void releaseSourceInternal() {
   @Test
   public void release_returnZeroCount_sourcesAndRendererCapabilitiesListReleased() {
     TargetPreloadStatusControl<Integer> targetPreloadStatusControl =
-        rankingData -> new DefaultPreloadManager.Status(STAGE_TIMELINE_REFRESHED);
+        rankingData -> new DefaultPreloadManager.Status(STAGE_SOURCE_PREPARED);
     MediaSource.Factory mockMediaSourceFactory = mock(MediaSource.Factory.class);
     List<FakeRenderer> underlyingRenderers = new ArrayList<>();
     RenderersFactory renderersFactory =