Add AdOverlayInfo.Builder and tweak @Purpose IntDef definition

PiperOrigin-RevId: 417378468

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

@@ -15,6 +15,12 @@
  */
 package androidx.media3.common;
 
+import static java.lang.annotation.ElementType.FIELD;
+import static java.lang.annotation.ElementType.LOCAL_VARIABLE;
+import static java.lang.annotation.ElementType.METHOD;
+import static java.lang.annotation.ElementType.PARAMETER;
+import static java.lang.annotation.ElementType.TYPE_USE;
+
 import android.view.View;
 import androidx.annotation.IntDef;
 import androidx.annotation.Nullable;
@@ -22,6 +28,7 @@ import androidx.media3.common.util.UnstableApi;
 import java.lang.annotation.Documented;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
 
 /** Provides information about an overlay view shown on top of an ad view group. */
 @UnstableApi
@@ -33,41 +40,70 @@ public final class AdOverlayInfo {
    */
   @Documented
   @Retention(RetentionPolicy.SOURCE)
+  @Target({FIELD, METHOD, PARAMETER, LOCAL_VARIABLE, TYPE_USE})
   @IntDef({PURPOSE_CONTROLS, PURPOSE_CLOSE_AD, PURPOSE_OTHER, PURPOSE_NOT_VISIBLE})
   public @interface Purpose {}
   /** Purpose for playback controls overlaying the player. */
-  public static final int PURPOSE_CONTROLS = 0;
+  public static final int PURPOSE_CONTROLS = 1;
   /** Purpose for ad close buttons overlaying the player. */
-  public static final int PURPOSE_CLOSE_AD = 1;
+  public static final int PURPOSE_CLOSE_AD = 2;
   /** Purpose for other overlays. */
-  public static final int PURPOSE_OTHER = 2;
+  public static final int PURPOSE_OTHER = 3;
   /** Purpose for overlays that are not visible. */
-  public static final int PURPOSE_NOT_VISIBLE = 3;
+  public static final int PURPOSE_NOT_VISIBLE = 4;
+
+  /** A builder for {@link AdOverlayInfo} instances. */
+  public static final class Builder {
+
+    private final View view;
+    private final @Purpose int purpose;
+
+    @Nullable private String detailedReason;
+
+    /**
+     * Creates a new builder.
+     *
+     * @param view The view that is overlaying the player.
+     * @param purpose The purpose of the view.
+     */
+    public Builder(View view, @Purpose int purpose) {
+      this.view = view;
+      this.purpose = purpose;
+    }
+
+    /**
+     * Sets an optional, detailed reason that the view is on top of the player.
+     *
+     * @return This builder, for convenience.
+     */
+    public Builder setDetailedReason(@Nullable String detailedReason) {
+      this.detailedReason = detailedReason;
+      return this;
+    }
+
+    /** Returns a new {@link AdOverlayInfo} instance with the current builder values. */
+    // Using deprecated constructor while it still exists.
+    @SuppressWarnings("deprecation")
+    public AdOverlayInfo build() {
+      return new AdOverlayInfo(view, purpose, detailedReason);
+    }
+  }
 
   /** The overlay view. */
   public final View view;
   /** The purpose of the overlay view. */
-  @Purpose public final int purpose;
+  public final @Purpose int purpose;
   /** An optional, detailed reason that the overlay view is needed. */
   @Nullable public final String reasonDetail;
 
-  /**
+  /** @deprecated Use {@link Builder} instead. */
-   * Creates a new overlay info.
+  @Deprecated
-   *
-   * @param view The view that is overlaying the player.
-   * @param purpose The purpose of the view.
-   */
   public AdOverlayInfo(View view, @Purpose int purpose) {
     this(view, purpose, /* detailedReason= */ null);
   }
 
-  /**
+  /** @deprecated Use {@link Builder} instead. */
-   * Creates a new overlay info.
+  @Deprecated
-   *
-   * @param view The view that is overlaying the player.
-   * @param purpose The purpose of the view.
-   * @param detailedReason An optional, detailed reason that the view is on top of the player.
-   */
   public AdOverlayInfo(View view, @Purpose int purpose, @Nullable String detailedReason) {
     this.view = view;
     this.purpose = purpose;