Cleanup the MediaItem.Builder javadoc for 'conditional' setters

Many of the setters are ignored unless others are set - this change:
* Lists these conditions exhaustively.
* Uses more concise language to avoid overshadowing the main details
  of what the setter sets.
* Tweaks the language from 'is ignored' to 'shouldn't be called', to
  open up the future possibility of throwing an error if these are
  called without the 'required' setter also being present (see
  Issue: #8957).

#minor-release

PiperOrigin-RevId: 376162385

RELEASENOTES.md

@@ -6,6 +6,8 @@
     *   Fix gradle config to allow specifying a relative path for
         `exoplayerRoot` when [depending on ExoPlayer locally](README.md#locally)
         ([#8927](https://github.com/google/ExoPlayer/issues/8927)).
+    *   Update `MediaItem.Builder` javadoc to discourage calling setters that
+        will be (currently) ignored if another setter is not also called.
 *   Extractors:
     *   Add support for MPEG-H 3D Audio in MP4 extractors
         ([#8860](https://github.com/google/ExoPlayer/pull/8860)).

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

@@ -159,9 +159,9 @@ public final class MediaItem implements Bundleable {
     /**
      * Sets the optional URI.
      *
-     * <p>If {@code uri} is null or unset no {@link PlaybackProperties} object is created during
+     * <p>If {@code uri} is null or unset then no {@link PlaybackProperties} object is created
-     * {@link #build()} and any other {@code Builder} methods that would populate {@link
+     * during {@link #build()} and no other {@code Builder} methods that would populate {@link
-     * MediaItem#playbackProperties} are ignored.
+     * MediaItem#playbackProperties} should be called.
      */
     public Builder setUri(@Nullable String uri) {
       return setUri(uri == null ? null : Uri.parse(uri));
@@ -170,9 +170,9 @@ public final class MediaItem implements Bundleable {
     /**
      * Sets the optional URI.
      *
-     * <p>If {@code uri} is null or unset no {@link PlaybackProperties} object is created during
+     * <p>If {@code uri} is null or unset then no {@link PlaybackProperties} object is created
-     * {@link #build()} and any other {@code Builder} methods that would populate {@link
+     * during {@link #build()} and no other {@code Builder} methods that would populate {@link
-     * MediaItem#playbackProperties} are ignored.
+     * MediaItem#playbackProperties} should be called.
      */
     public Builder setUri(@Nullable Uri uri) {
       this.uri = uri;
@@ -184,8 +184,7 @@ public final class MediaItem implements Bundleable {
      *
      * <p>The MIME type may be used as a hint for inferring the type of the media item.
      *
-     * <p>If {@link #setUri} is passed a non-null {@code uri}, the MIME type is used to create a
+     * <p>This method should only be called if {@link #setUri} is passed a non-null value.
-     * {@link PlaybackProperties} object. Otherwise it will be ignored.
      *
      * @param mimeType The MIME type.
      */
@@ -247,8 +246,8 @@ public final class MediaItem implements Bundleable {
      * Sets the optional default DRM license server URI. If this URI is set, the {@link
      * DrmConfiguration#uuid} needs to be specified as well.
      *
-     * <p>If {@link #setUri} is passed a non-null {@code uri}, the DRM license server URI is used to
+     * <p>This method should only be called if both {@link #setUri} and {@link #setDrmUuid(UUID)}
-     * create a {@link PlaybackProperties} object. Otherwise it will be ignored.
+     * are passed non-null values.
      */
     public Builder setDrmLicenseUri(@Nullable Uri licenseUri) {
       drmLicenseUri = licenseUri;
@@ -259,8 +258,8 @@ public final class MediaItem implements Bundleable {
      * Sets the optional default DRM license server URI. If this URI is set, the {@link
      * DrmConfiguration#uuid} needs to be specified as well.
      *
-     * <p>If {@link #setUri} is passed a non-null {@code uri}, the DRM license server URI is used to
+     * <p>This method should only be called if both {@link #setUri} and {@link #setDrmUuid(UUID)}
-     * create a {@link PlaybackProperties} object. Otherwise it will be ignored.
+     * are passed non-null values.
      */
     public Builder setDrmLicenseUri(@Nullable String licenseUri) {
       drmLicenseUri = licenseUri == null ? null : Uri.parse(licenseUri);
@@ -272,7 +271,8 @@ public final class MediaItem implements Bundleable {
      *
      * <p>{@code null} or an empty {@link Map} can be used for a reset.
      *
-     * <p>If no valid DRM configuration is specified, the DRM license request headers are ignored.
+     * <p>This method should only be called if both {@link #setUri} and {@link #setDrmUuid(UUID)}
+     * are passed non-null values.
      */
     public Builder setDrmLicenseRequestHeaders(
         @Nullable Map<String, String> licenseRequestHeaders) {
@@ -286,8 +286,11 @@ public final class MediaItem implements Bundleable {
     /**
      * Sets the {@link UUID} of the protection scheme.
      *
-     * <p>If {@link #setUri} is passed a non-null {@code uri}, the DRM system UUID is used to create
+     * <p>If {@code uuid} is null or unset then no {@link DrmConfiguration} object is created during
-     * a {@link PlaybackProperties} object. Otherwise it will be ignored.
+     * {@link #build()} and no other {@code Builder} methods that would populate {@link
+     * MediaItem.PlaybackProperties#drmConfiguration} should be called.
+     *
+     * <p>This method should only be called if {@link #setUri} is passed a non-null value.
      */
     public Builder setDrmUuid(@Nullable UUID uuid) {
       drmUuid = uuid;
@@ -297,8 +300,8 @@ public final class MediaItem implements Bundleable {
     /**
      * Sets whether the DRM configuration is multi session enabled.
      *
-     * <p>If {@link #setUri} is passed a non-null {@code uri}, the DRM multi session flag is used to
+     * <p>This method should only be called if both {@link #setUri} and {@link #setDrmUuid(UUID)}
-     * create a {@link PlaybackProperties} object. Otherwise it will be ignored.
+     * are passed non-null values.
      */
     public Builder setDrmMultiSession(boolean multiSession) {
       drmMultiSession = multiSession;
@@ -309,8 +312,8 @@ public final class MediaItem implements Bundleable {
      * Sets whether to force use the default DRM license server URI even if the media specifies its
      * own DRM license server URI.
      *
-     * <p>If {@link #setUri} is passed a non-null {@code uri}, the DRM force default license flag is
+     * <p>This method should only be called if both {@link #setUri} and {@link #setDrmUuid(UUID)}
-     * used to create a {@link PlaybackProperties} object. Otherwise it will be ignored.
+     * are passed non-null values.
      */
     public Builder setDrmForceDefaultLicenseUri(boolean forceDefaultLicenseUri) {
       this.drmForceDefaultLicenseUri = forceDefaultLicenseUri;
@@ -320,6 +323,9 @@ public final class MediaItem implements Bundleable {
     /**
      * Sets whether clear samples within protected content should be played when keys for the
      * encrypted part of the content have yet to be loaded.
+     *
+     * <p>This method should only be called if both {@link #setUri} and {@link #setDrmUuid(UUID)}
+     * are passed non-null values.
      */
     public Builder setDrmPlayClearContentWithoutKey(boolean playClearContentWithoutKey) {
       this.drmPlayClearContentWithoutKey = playClearContentWithoutKey;
@@ -332,6 +338,9 @@ public final class MediaItem implements Bundleable {
      *
      * <p>This method overrides what has been set by previously calling {@link
      * #setDrmSessionForClearTypes(List)}.
+     *
+     * <p>This method should only be called if both {@link #setUri} and {@link #setDrmUuid(UUID)}
+     * are passed non-null values.
      */
     public Builder setDrmSessionForClearPeriods(boolean sessionForClearPeriods) {
       this.setDrmSessionForClearTypes(
@@ -352,6 +361,9 @@ public final class MediaItem implements Bundleable {
      * #setDrmSessionForClearPeriods(boolean)}.
      *
      * <p>{@code null} or an empty {@link List} can be used for a reset.
+     *
+     * <p>This method should only be called if both {@link #setUri} and {@link #setDrmUuid(UUID)}
+     * are passed non-null values.
      */
     public Builder setDrmSessionForClearTypes(@Nullable List<Integer> sessionForClearTypes) {
       this.drmSessionForClearTypes =
@@ -368,7 +380,8 @@ public final class MediaItem implements Bundleable {
      * release an existing offline license (see {@code DefaultDrmSessionManager#setMode(int
      * mode,byte[] offlineLicenseKeySetId)}).
      *
-     * <p>If no valid DRM configuration is specified, the key set ID is ignored.
+     * <p>This method should only be called if both {@link #setUri} and {@link #setDrmUuid(UUID)}
+     * are passed non-null values.
      */
     public Builder setDrmKeySetId(@Nullable byte[] keySetId) {
       this.drmKeySetId = keySetId != null ? Arrays.copyOf(keySetId, keySetId.length) : null;
@@ -395,8 +408,7 @@ public final class MediaItem implements Bundleable {
     /**
      * Sets the optional custom cache key (only used for progressive streams).
      *
-     * <p>If {@link #setUri} is passed a non-null {@code uri}, the custom cache key is used to
+     * <p>This method should only be called if {@link #setUri} is passed a non-null value.
-     * create a {@link PlaybackProperties} object. Otherwise it will be ignored.
      */
     public Builder setCustomCacheKey(@Nullable String customCacheKey) {
       this.customCacheKey = customCacheKey;
@@ -408,8 +420,7 @@ public final class MediaItem implements Bundleable {
      *
      * <p>{@code null} or an empty {@link List} can be used for a reset.
      *
-     * <p>If {@link #setUri} is passed a non-null {@code uri}, the subtitles are used to create a
+     * <p>This method should only be called if {@link #setUri} is passed a non-null value.
-     * {@link PlaybackProperties} object. Otherwise they will be ignored.
      */
     public Builder setSubtitles(@Nullable List<Subtitle> subtitles) {
       this.subtitles =
@@ -422,13 +433,12 @@ public final class MediaItem implements Bundleable {
     /**
      * Sets the optional ad tag {@link Uri}.
      *
-     * <p>If {@link #setUri} is passed a non-null {@code uri}, the ad tag URI is used to create a
-     * {@link PlaybackProperties} object. Otherwise it will be ignored.
-     *
      * <p>Media items in the playlist with the same ad tag URI, media ID and ads loader will share
      * the same ad playback state. To resume ad playback when recreating the playlist on returning
      * from the background, pass media items with the same ad tag URIs and media IDs to the player.
      *
+     * <p>This method should only be called if {@link #setUri} is passed a non-null value.
+     *
      * @param adTagUri The ad tag URI to load.
      */
     public Builder setAdTagUri(@Nullable String adTagUri) {
@@ -438,13 +448,12 @@ public final class MediaItem implements Bundleable {
     /**
      * Sets the optional ad tag {@link Uri}.
      *
-     * <p>If {@link #setUri} is passed a non-null {@code uri}, the ad tag URI is used to create a
-     * {@link PlaybackProperties} object. Otherwise it will be ignored.
-     *
      * <p>Media items in the playlist with the same ad tag URI, media ID and ads loader will share
      * the same ad playback state. To resume ad playback when recreating the playlist on returning
      * from the background, pass media items with the same ad tag URIs and media IDs to the player.
      *
+     * <p>This method should only be called if {@link #setUri} is passed a non-null value.
+     *
      * @param adTagUri The ad tag URI to load.
      */
     public Builder setAdTagUri(@Nullable Uri adTagUri) {
@@ -454,13 +463,12 @@ public final class MediaItem implements Bundleable {
     /**
      * Sets the optional ad tag {@link Uri} and ads identifier.
      *
-     * <p>If {@link #setUri} is passed a non-null {@code uri}, the ad tag URI is used to create a
-     * {@link PlaybackProperties} object. Otherwise it will be ignored.
-     *
      * <p>Media items in the playlist that have the same ads identifier and ads loader share the
      * same ad playback state. To resume ad playback when recreating the playlist on returning from
      * the background, pass the same ads IDs to the player.
      *
+     * <p>This method should only be called if {@link #setUri} is passed a non-null value.
+     *
      * @param adTagUri The ad tag URI to load.
      * @param adsId An opaque identifier for ad playback state associated with this item. Ad loading
      *     and playback state is shared among all media items that have the same ads ID (by {@link
@@ -544,8 +552,7 @@ public final class MediaItem implements Bundleable {
      * published in the {@code com.google.android.exoplayer2.Timeline} of the source as {@code
      * com.google.android.exoplayer2.Timeline.Window#tag}.
      *
-     * <p>If {@link #setUri} is passed a non-null {@code uri}, the tag is used to create a {@link
+     * <p>This method should only be called if {@link #setUri} is passed a non-null value.
-     * PlaybackProperties} object. Otherwise it will be ignored.
      */
     public Builder setTag(@Nullable Object tag) {
       this.tag = tag;