Deprecate ActionFile and simplify upgrading

PiperOrigin-RevId: 243085292

demos/main/src/main/java/com/google/android/exoplayer2/demo/DemoApplication.java

@@ -19,10 +19,9 @@ import android.app.Application;
 import com.google.android.exoplayer2.DefaultRenderersFactory;
 import com.google.android.exoplayer2.RenderersFactory;
 import com.google.android.exoplayer2.database.ExoDatabaseProvider;
-import com.google.android.exoplayer2.offline.ActionFile;
+import com.google.android.exoplayer2.offline.ActionFileUpgradeUtil;
 import com.google.android.exoplayer2.offline.DefaultDownloadIndex;
 import com.google.android.exoplayer2.offline.DefaultDownloaderFactory;
-import com.google.android.exoplayer2.offline.DownloadIndexUtil;
 import com.google.android.exoplayer2.offline.DownloadManager;
 import com.google.android.exoplayer2.offline.DownloaderConstructorHelper;
 import com.google.android.exoplayer2.upstream.DataSource;
@@ -132,16 +131,15 @@ public class DemoApplication extends Application {
     }
   }
 
-  private void upgradeActionFile(String file, DefaultDownloadIndex downloadIndex) {
-    ActionFile actionFile = new ActionFile(new File(getDownloadDirectory(), file));
-    if (actionFile.exists()) {
+  private void upgradeActionFile(String fileName, DefaultDownloadIndex downloadIndex) {
     try {
-        DownloadIndexUtil.mergeActionFile(
-            actionFile, /* downloadIdProvider= */ null, downloadIndex);
+      ActionFileUpgradeUtil.upgradeAndDelete(
+          new File(getDownloadDirectory(), fileName),
+          /* downloadIdProvider= */ null,
+          downloadIndex,
+          /* deleteOnFailure= */ true);
     } catch (IOException e) {
-        Log.e(TAG, "Upgrading action file failed", e);
-      }
-      actionFile.delete();
+      Log.e(TAG, "Failed to upgrade action file: " + fileName, e);
     }
   }
 

demos/main/src/main/java/com/google/android/exoplayer2/demo/DownloadTracker.java

@@ -23,7 +23,6 @@ import androidx.fragment.app.FragmentManager;
 import android.widget.Toast;
 import com.google.android.exoplayer2.C;
 import com.google.android.exoplayer2.RenderersFactory;
-import com.google.android.exoplayer2.offline.ActionFile;
 import com.google.android.exoplayer2.offline.DefaultDownloadIndex;
 import com.google.android.exoplayer2.offline.Download;
 import com.google.android.exoplayer2.offline.DownloadAction;
@@ -44,10 +43,6 @@ import java.util.concurrent.CopyOnWriteArraySet;
 
 /**
  * Tracks media that has been downloaded.
- *
- * <p>Tracked downloads are persisted using an {@link ActionFile}, however in a real application
- * it's expected that state will be stored directly in the application's media database, so that it
- * can be queried efficiently together with other information about the media.
  */
 public class DownloadTracker implements DownloadManager.Listener {
 

library/core/src/main/java/com/google/android/exoplayer2/offline/ActionFile.java

@@ -27,8 +27,14 @@ import java.io.InputStream;
 import java.util.ArrayList;
 import java.util.List;
 
-/** Loads {@link DownloadAction DownloadActions} from legacy action files. */
-public final class ActionFile {
+/**
+ * Loads {@link DownloadAction DownloadActions} from legacy action files.
+ *
+ * @deprecated Legacy action files should be merged into download indices using {@link
+ *     ActionFileUpgradeUtil}.
+ */
+@Deprecated
+/* package */ final class ActionFile {
 
   private static final int VERSION = 0;
 

library/core/src/main/java/com/google/android/exoplayer2/offline/ActionFileUpgradeUtil.java

@@ -16,52 +16,69 @@
 package com.google.android.exoplayer2.offline;
 
 import androidx.annotation.Nullable;
+import java.io.File;
 import java.io.IOException;
 
-/** {@link DownloadIndex} related utility methods. */
-public final class DownloadIndexUtil {
+/** Utility class for upgrading legacy action files into {@link DefaultDownloadIndex}. */
+public final class ActionFileUpgradeUtil {
 
-  /** An interface to provide custom download ids during ActionFile upgrade. */
+  /** Provides download IDs during action file upgrade. */
   public interface DownloadIdProvider {
 
     /**
-     * Returns a custom download id for given action.
+     * Returns a download id for given action.
      *
-     * @param downloadAction The action which is an id requested for.
-     * @return A custom download id for given action.
+     * @param downloadAction The action for which an ID is required.
+     * @return A corresponding download ID.
      */
     String getId(DownloadAction downloadAction);
   }
 
-  private DownloadIndexUtil() {}
+  private ActionFileUpgradeUtil() {}
 
   /**
-   * Merges {@link DownloadAction DownloadActions} contained in an {@link ActionFile} into a {@link
-   * DownloadIndex}.
+   * Merges {@link DownloadAction DownloadActions} contained in a legacy action file into a {@link
+   * DefaultDownloadIndex}, deleting the action file if the merge is successful or if {@code
+   * deleteOnFailure} is {@code true}.
    *
-   * <p>This method must not be called while the {@link DownloadIndex} is being used by a {@link
-   * DownloadManager}.
+   * <p>This method must not be called while the {@link DefaultDownloadIndex} is being used by a
+   * {@link DownloadManager}.
    *
-   * @param actionFile The action file.
-   * @param downloadIdProvider A custom download id provider, or {@code null}.
+   * @param actionFilePath The action file path.
+   * @param downloadIdProvider A download ID provider, or {@code null}. If {@code null} then ID of
+   *     each download will be its custom cache key if one is specified, or else its URL.
    * @param downloadIndex The index into which the action will be merged.
+   * @param deleteOnFailure Whether to delete the action file if the merge fails.
    * @throws IOException If an error occurs loading or merging the actions.
    */
-  public static void mergeActionFile(
-      ActionFile actionFile,
+  @SuppressWarnings("deprecation")
+  public static void upgradeAndDelete(
+      File actionFilePath,
       @Nullable DownloadIdProvider downloadIdProvider,
-      DefaultDownloadIndex downloadIndex)
+      DefaultDownloadIndex downloadIndex,
+      boolean deleteOnFailure)
       throws IOException {
+    ActionFile actionFile = new ActionFile(actionFilePath);
+    if (actionFile.exists()) {
+      boolean success = false;
+      try {
         for (DownloadAction action : actionFile.load()) {
           if (downloadIdProvider != null) {
             action = action.copyWithId(downloadIdProvider.getId(action));
           }
           mergeAction(action, downloadIndex);
         }
+        success = true;
+      } finally {
+        if (success || deleteOnFailure) {
+          actionFile.delete();
+        }
+      }
+    }
   }
 
   /**
-   * Merges a {@link DownloadAction} into a {@link DownloadIndexUtil}.
+   * Merges a {@link DownloadAction} into a {@link DefaultDownloadIndex}.
    *
    * @param action The action to be merged.
    * @param downloadIndex The index into which the action will be merged.

library/core/src/test/java/com/google/android/exoplayer2/offline/ActionFileUpgradeUtilTest.java

@@ -34,9 +34,9 @@ import org.junit.Before;
 import org.junit.Test;
 import org.junit.runner.RunWith;
 
-/** Unit tests for {@link DownloadIndexUtil}. */
+/** Unit tests for {@link ActionFileUpgradeUtil}. */
 @RunWith(AndroidJUnit4.class)
-public class DownloadIndexUtilTest {
+public class ActionFileUpgradeUtilTest {
 
   private File tempFile;
   private ExoDatabaseProvider databaseProvider;
@@ -69,7 +69,7 @@ public class DownloadIndexUtilTest {
             /* customCacheKey= */ "key123",
             data);
 
-    DownloadIndexUtil.mergeAction(action, downloadIndex);
+    ActionFileUpgradeUtil.mergeAction(action, downloadIndex);
 
     assertDownloadIndexContainsAction(action, Download.STATE_QUEUED);
   }
@@ -96,9 +96,9 @@ public class DownloadIndexUtilTest {
             asList(streamKey2),
             /* customCacheKey= */ "key123",
             new byte[] {5, 4, 3, 2, 1});
-    DownloadIndexUtil.mergeAction(action1, downloadIndex);
+    ActionFileUpgradeUtil.mergeAction(action1, downloadIndex);
 
-    DownloadIndexUtil.mergeAction(action2, downloadIndex);
+    ActionFileUpgradeUtil.mergeAction(action2, downloadIndex);
 
     Download download = downloadIndex.getDownload(action2.id);
     assertThat(download).isNotNull();
@@ -142,8 +142,8 @@ public class DownloadIndexUtilTest {
             /* customCacheKey= */ "key234",
             new byte[] {5, 4, 3, 2, 1});
 
-    ActionFile actionFile = new ActionFile(tempFile);
-    DownloadIndexUtil.mergeActionFile(actionFile, /* downloadIdProvider= */ null, downloadIndex);
+    ActionFileUpgradeUtil.upgradeAndDelete(
+        tempFile, /* downloadIdProvider= */ null, downloadIndex, /* deleteOnFailure= */ true);
     assertDownloadIndexContainsAction(expectedAction1, Download.STATE_QUEUED);
     assertDownloadIndexContainsAction(expectedAction2, Download.STATE_QUEUED);
   }