Add IntDef for priority values

This makes it easier to reference these values in documentation
and method parameters.

PiperOrigin-RevId: 629072314

libraries/common/src/main/java/androidx/media3/common/C.java

@@ -1235,17 +1235,33 @@ public final class C {
   @UnstableApi public static final int PROJECTION_MESH = 3;
 
   /**
-   * Priority for media playback.
+   * A value indicating the priority of a operation.
    *
    * <p>Larger values indicate higher priorities.
+   *
+   * <p>The predefined priority values are used by default and it's recommended to align any custom
+   * values relative to these defaults (for example, {@code C.PRIORITY_PLAYBACK - 1}.
+   *
+   * <p>Predefined values are (in descending priority order):
+   *
+   * <ul>
+   *   <li>{@link #PRIORITY_PLAYBACK}
+   *   <li>{@link #PRIORITY_DOWNLOAD}
+   * </ul>
    */
+  @Documented
+  @UnstableApi
+  @Retention(RetentionPolicy.SOURCE)
+  @Target(TYPE_USE)
+  @IntDef(
+      open = true,
+      value = {PRIORITY_PLAYBACK, PRIORITY_DOWNLOAD})
+  public @interface Priority {}
+
+  /** {@link Priority} for active media playback. */
   @UnstableApi public static final int PRIORITY_PLAYBACK = 0;
 
-  /**
+  /** {@link Priority} for media downloading unrelated to active playback. */
-   * Priority for media downloading.
-   *
-   * <p>Larger values indicate higher priorities.
-   */
   @UnstableApi public static final int PRIORITY_DOWNLOAD = PRIORITY_PLAYBACK - 1000;
 
   /**

libraries/common/src/main/java/androidx/media3/common/PriorityTaskManager.java

@@ -24,12 +24,16 @@ import java.util.Collections;
 import java.util.PriorityQueue;
 
 /**
- * Allows tasks with associated priorities to control how they proceed relative to one another.
+ * Allows tasks with associated {@linkplain C.Priority priorities} to control how they proceed
+ * relative to one another.
  *
  * <p>A task should call {@link #add(int)} to register with the manager and {@link #remove(int)} to
  * unregister. A registered task will prevent tasks of lower priority from proceeding, and should
  * call {@link #proceed(int)}, {@link #proceedNonBlocking(int)} or {@link #proceedOrThrow(int)} each
  * time it wishes to check whether it is itself allowed to proceed.
+ *
+ * <p>It is recommended to use predefined {@linkplain C.Priority priorities} or priority values
+ * defined relative to those defaults.
  */
 @UnstableApi
 public final class PriorityTaskManager {
@@ -37,7 +41,7 @@ public final class PriorityTaskManager {
   /** Thrown when task attempts to proceed when another registered task has a higher priority. */
   public static class PriorityTooLowException extends IOException {
 
-    public PriorityTooLowException(int priority, int highestPriority) {
+    public PriorityTooLowException(@C.Priority int priority, @C.Priority int highestPriority) {
       super("Priority too low [priority=" + priority + ", highest=" + highestPriority + "]");
     }
   }
@@ -45,8 +49,8 @@ public final class PriorityTaskManager {
   private final Object lock = new Object();
 
   // Guarded by lock.
-  private final PriorityQueue<Integer> queue;
+  private final PriorityQueue<@C.Priority Integer> queue;
-  private int highestPriority;
+  private @C.Priority int highestPriority;
 
   public PriorityTaskManager() {
     queue = new PriorityQueue<>(10, Collections.reverseOrder());
@@ -56,9 +60,12 @@ public final class PriorityTaskManager {
   /**
    * Register a new task. The task must call {@link #remove(int)} when done.
    *
-   * @param priority The priority of the task. Larger values indicate higher priorities.
+   * <p>It is recommended to use predefined {@linkplain C.Priority priorities} or priority values
+   * defined relative to those defaults.
+   *
+   * @param priority The {@link C.Priority} of the task. Larger values indicate higher priorities.
    */
-  public void add(int priority) {
+  public void add(@C.Priority int priority) {
     synchronized (lock) {
       queue.add(priority);
       highestPriority = max(highestPriority, priority);
@@ -68,10 +75,10 @@ public final class PriorityTaskManager {
   /**
    * Blocks until the task is allowed to proceed.
    *
-   * @param priority The priority of the task.
+   * @param priority The {@link C.Priority} of the task.
    * @throws InterruptedException If the thread is interrupted.
    */
-  public void proceed(int priority) throws InterruptedException {
+  public void proceed(@C.Priority int priority) throws InterruptedException {
     synchronized (lock) {
       while (highestPriority != priority) {
         lock.wait();
@@ -82,10 +89,10 @@ public final class PriorityTaskManager {
   /**
    * A non-blocking variant of {@link #proceed(int)}.
    *
-   * @param priority The priority of the task.
+   * @param priority The {@link C.Priority} of the task.
    * @return Whether the task is allowed to proceed.
    */
-  public boolean proceedNonBlocking(int priority) {
+  public boolean proceedNonBlocking(@C.Priority int priority) {
     synchronized (lock) {
       return highestPriority == priority;
     }
@@ -94,10 +101,10 @@ public final class PriorityTaskManager {
   /**
    * A throwing variant of {@link #proceed(int)}.
    *
-   * @param priority The priority of the task.
+   * @param priority The {@link C.Priority} of the task.
    * @throws PriorityTooLowException If the task is not allowed to proceed.
    */
-  public void proceedOrThrow(int priority) throws PriorityTooLowException {
+  public void proceedOrThrow(@C.Priority int priority) throws PriorityTooLowException {
     synchronized (lock) {
       if (highestPriority != priority) {
         throw new PriorityTooLowException(priority, highestPriority);
@@ -108,9 +115,9 @@ public final class PriorityTaskManager {
   /**
    * Unregister a task.
    *
-   * @param priority The priority of the task.
+   * @param priority The {@link C.Priority} of the task.
    */
-  public void remove(int priority) {
+  public void remove(@C.Priority int priority) {
     synchronized (lock) {
       queue.remove(priority);
       highestPriority = queue.isEmpty() ? Integer.MIN_VALUE : Util.castNonNull(queue.peek());

libraries/datasource/src/main/java/androidx/media3/datasource/PriorityDataSource.java

@@ -17,6 +17,7 @@ package androidx.media3.datasource;
 
 import android.net.Uri;
 import androidx.annotation.Nullable;
+import androidx.media3.common.C;
 import androidx.media3.common.PriorityTaskManager;
 import androidx.media3.common.util.Assertions;
 import androidx.media3.common.util.UnstableApi;
@@ -45,7 +46,7 @@ public final class PriorityDataSource implements DataSource {
 
     private final DataSource.Factory upstreamFactory;
     private final PriorityTaskManager priorityTaskManager;
-    private final int priority;
+    private final @C.Priority int priority;
 
     /**
      * Creates an instance.
@@ -54,11 +55,13 @@ public final class PriorityDataSource implements DataSource {
      *     DataSources} for {@link PriorityDataSource} instances created by the factory.
      * @param priorityTaskManager The {@link PriorityTaskManager} to which tasks using {@link
      *     PriorityDataSource} instances created by this factory will be registered.
-     * @param priority The priority of the tasks using {@link PriorityDataSource} instances created
+     * @param priority The {@link C.Priority} of the tasks using {@link PriorityDataSource}
-     *     by this factory.
+     *     instances created by this factory.
      */
     public Factory(
-        DataSource.Factory upstreamFactory, PriorityTaskManager priorityTaskManager, int priority) {
+        DataSource.Factory upstreamFactory,
+        PriorityTaskManager priorityTaskManager,
+        @C.Priority int priority) {
       this.upstreamFactory = upstreamFactory;
       this.priorityTaskManager = priorityTaskManager;
       this.priority = priority;
@@ -73,15 +76,15 @@ public final class PriorityDataSource implements DataSource {
 
   private final DataSource upstream;
   private final PriorityTaskManager priorityTaskManager;
-  private final int priority;
+  private final @C.Priority int priority;
 
   /**
    * @param upstream The upstream {@link DataSource}.
    * @param priorityTaskManager The priority manager to which the task is registered.
-   * @param priority The priority of the task.
+   * @param priority The {@link C.Priority} of the task.
    */
   public PriorityDataSource(
-      DataSource upstream, PriorityTaskManager priorityTaskManager, int priority) {
+      DataSource upstream, PriorityTaskManager priorityTaskManager, @C.Priority int priority) {
     this.upstream = Assertions.checkNotNull(upstream);
     this.priorityTaskManager = Assertions.checkNotNull(priorityTaskManager);
     this.priority = priority;

libraries/datasource/src/main/java/androidx/media3/datasource/PriorityDataSourceFactory.java

@@ -15,6 +15,7 @@
  */
 package androidx.media3.datasource;
 
+import androidx.media3.common.C;
 import androidx.media3.common.PriorityTaskManager;
 import androidx.media3.common.util.UnstableApi;
 import androidx.media3.datasource.DataSource.Factory;
@@ -28,16 +29,16 @@ public final class PriorityDataSourceFactory implements Factory {
 
   private final Factory upstreamFactory;
   private final PriorityTaskManager priorityTaskManager;
-  private final int priority;
+  private final @C.Priority int priority;
 
   /**
    * @param upstreamFactory A {@link DataSource.Factory} to be used to create an upstream {@link
    *     DataSource} for {@link PriorityDataSource}.
    * @param priorityTaskManager The priority manager to which PriorityDataSource task is registered.
-   * @param priority The priority of PriorityDataSource task.
+   * @param priority The {@link C.Priority} of the {@link PriorityDataSource} task.
    */
   public PriorityDataSourceFactory(
-      Factory upstreamFactory, PriorityTaskManager priorityTaskManager, int priority) {
+      Factory upstreamFactory, PriorityTaskManager priorityTaskManager, @C.Priority int priority) {
     this.upstreamFactory = upstreamFactory;
     this.priorityTaskManager = priorityTaskManager;
     this.priority = priority;

libraries/datasource/src/main/java/androidx/media3/datasource/cache/CacheDataSource.java

@@ -72,7 +72,7 @@ public final class CacheDataSource implements DataSource {
     private boolean cacheIsReadOnly;
     @Nullable private DataSource.Factory upstreamDataSourceFactory;
     @Nullable private PriorityTaskManager upstreamPriorityTaskManager;
-    private int upstreamPriority;
+    private @C.Priority int upstreamPriority;
     private @CacheDataSource.Flags int flags;
     @Nullable private CacheDataSource.EventListener eventListener;
 
@@ -209,16 +209,17 @@ public final class CacheDataSource implements DataSource {
     }
 
     /**
-     * Sets the priority to use when requesting data from upstream. The priority is only used if a
+     * Sets the {@link C.Priority} to use when requesting data from upstream. The priority is only
-     * {@link PriorityTaskManager} is set by calling {@link #setUpstreamPriorityTaskManager}.
+     * used if a {@link PriorityTaskManager} is set by calling {@link
+     * #setUpstreamPriorityTaskManager}.
      *
      * <p>The default is {@link C#PRIORITY_PLAYBACK}.
      *
-     * @param upstreamPriority The priority to use when requesting data from upstream.
+     * @param upstreamPriority The {@link C.Priority} to use when requesting data from upstream.
      * @return This factory.
      */
     @CanIgnoreReturnValue
-    public Factory setUpstreamPriority(int upstreamPriority) {
+    public Factory setUpstreamPriority(@C.Priority int upstreamPriority) {
       this.upstreamPriority = upstreamPriority;
       return this;
     }
@@ -297,7 +298,9 @@ public final class CacheDataSource implements DataSource {
     }
 
     private CacheDataSource createDataSourceInternal(
-        @Nullable DataSource upstreamDataSource, @Flags int flags, int upstreamPriority) {
+        @Nullable DataSource upstreamDataSource,
+        @Flags int flags,
+        @C.Priority int upstreamPriority) {
       Cache cache = checkNotNull(this.cache);
       @Nullable DataSink cacheWriteDataSink;
       if (cacheIsReadOnly || upstreamDataSource == null) {
@@ -531,7 +534,7 @@ public final class CacheDataSource implements DataSource {
       @Nullable CacheKeyFactory cacheKeyFactory,
       @Flags int flags,
       @Nullable PriorityTaskManager upstreamPriorityTaskManager,
-      int upstreamPriority,
+      @C.Priority int upstreamPriority,
       @Nullable EventListener eventListener) {
     this.cache = cache;
     this.cacheReadDataSource = cacheReadDataSource;