From 443468d1037d9562051d6e8ea34035b22d5f9a8e Mon Sep 17 00:00:00 2001 From: ibaker Date: Tue, 11 Aug 2020 13:34:29 +0100 Subject: [PATCH] Clarify MediaItem.Builder javadoc Make it clear that setUri sets PlaybackProperties.uri Also capitalise all references to DRM, ID, URI and UUID PiperOrigin-RevId: 326002853 --- .../google/android/exoplayer2/MediaItem.java | 116 ++++++++++-------- 1 file changed, 63 insertions(+), 53 deletions(-) diff --git a/library/common/src/main/java/com/google/android/exoplayer2/MediaItem.java b/library/common/src/main/java/com/google/android/exoplayer2/MediaItem.java index b84e86deeb..dfff9a9e73 100644 --- a/library/common/src/main/java/com/google/android/exoplayer2/MediaItem.java +++ b/library/common/src/main/java/com/google/android/exoplayer2/MediaItem.java @@ -42,10 +42,10 @@ public final class MediaItem { } /** - * Creates a {@link MediaItem} for the given {@link Uri uri}. + * Creates a {@link MediaItem} for the given {@link Uri URI}. * * @param uri The {@link Uri uri}. - * @return An {@link MediaItem} for the given uri. + * @return An {@link MediaItem} for the given URI. */ public static MediaItem fromUri(Uri uri) { return new MediaItem.Builder().setUri(uri).build(); @@ -119,22 +119,32 @@ public final class MediaItem { } /** - * Sets the optional media id which identifies the media item. If not specified, {@link #setUri} + * Sets the optional media ID which identifies the media item. If not specified, {@link #setUri} * must be called and the string representation of {@link PlaybackProperties#uri} is used as the - * media id. + * media ID. */ public Builder setMediaId(@Nullable String mediaId) { this.mediaId = mediaId; return this; } - /** Sets the optional uri. If not specified, {@link #setMediaId(String)} must be called. */ + /** + * Sets the optional URI. If not specified, {@link #setMediaId(String)} must be called. + * + *

If {@code uri} is null or unset no {@link PlaybackProperties} object is created during + * {@link #build()} and any other {@code Builder} methods that would populate {@link + * MediaItem#playbackProperties} are ignored. + */ public Builder setUri(@Nullable String uri) { return setUri(uri == null ? null : Uri.parse(uri)); } /** - * Sets the optional {@link Uri}. If not specified, {@link #setMediaId(String)} must be called. + * Sets the optional URI. If not specified, {@link #setMediaId(String)} must be called. + * + *

If {@code uri} is null or unset no {@link PlaybackProperties} object is created during + * {@link #build()} and any other {@code Builder} methods that would populate {@link + * MediaItem#playbackProperties} are ignored. */ public Builder setUri(@Nullable Uri uri) { this.uri = uri; @@ -142,14 +152,14 @@ public final class MediaItem { } /** - * Sets the optional mime type. + * Sets the optional MIME type. * - *

The mime type may be used as a hint for inferring the type of the media item. + *

The MIME type may be used as a hint for inferring the type of the media item. * - *

If a {@link PlaybackProperties#uri} is set, the mime type is used to create a {@link - * PlaybackProperties} object. Otherwise it will be ignored. + *

If {@link #setUri} is passed a non-null {@code uri}, the MIME type is used to create a + * {@link PlaybackProperties} object. Otherwise it will be ignored. * - * @param mimeType The mime type. + * @param mimeType The MIME type. */ public Builder setMimeType(@Nullable String mimeType) { this.mimeType = mimeType; @@ -206,11 +216,11 @@ public final class MediaItem { } /** - * Sets the optional license server {@link Uri}. If a license uri is set, the {@link + * Sets the optional DRM license server URI. If this URI is set, the {@link * DrmConfiguration#uuid} needs to be specified as well. * - *

If a {@link PlaybackProperties#uri} is set, the drm license uri is used to create a {@link - * PlaybackProperties} object. Otherwise it will be ignored. + *

If {@link #setUri} is passed a non-null {@code uri}, the DRM license server URI is used to + * create a {@link PlaybackProperties} object. Otherwise it will be ignored. */ public Builder setDrmLicenseUri(@Nullable Uri licenseUri) { drmLicenseUri = licenseUri; @@ -218,11 +228,11 @@ public final class MediaItem { } /** - * Sets the optional license server uri as a {@link String}. If a license uri is set, the {@link + * Sets the optional DRM license server URI. If this URI is set, the {@link * DrmConfiguration#uuid} needs to be specified as well. * - *

If a {@link PlaybackProperties#uri} is set, the drm license uri is used to create a {@link - * PlaybackProperties} object. Otherwise it will be ignored. + *

If {@link #setUri} is passed a non-null {@code uri}, the DRM license server URI is used to + * create a {@link PlaybackProperties} object. Otherwise it will be ignored. */ public Builder setDrmLicenseUri(@Nullable String licenseUri) { drmLicenseUri = licenseUri == null ? null : Uri.parse(licenseUri); @@ -230,11 +240,11 @@ public final class MediaItem { } /** - * Sets the optional request headers attached to the drm license request. + * Sets the optional request headers attached to the DRM license request. * *

{@code null} or an empty {@link Map} can be used for a reset. * - *

If no valid drm configuration is specified, the drm license request headers are ignored. + *

If no valid DRM configuration is specified, the DRM license request headers are ignored. */ public Builder setDrmLicenseRequestHeaders( @Nullable Map licenseRequestHeaders) { @@ -246,11 +256,11 @@ public final class MediaItem { } /** - * Sets the {@link UUID} of the protection scheme. If a drm system uuid is set, the {@link + * Sets the {@link UUID} of the protection scheme. If a DRM system UUID is set, the {@link * DrmConfiguration#licenseUri} needs to be set as well. * - *

If a {@link PlaybackProperties#uri} is set, the drm system uuid is used to create a {@link - * PlaybackProperties} object. Otherwise it will be ignored. + *

If {@link #setUri} is passed a non-null {@code uri}, the DRM system UUID is used to create + * a {@link PlaybackProperties} object. Otherwise it will be ignored. */ public Builder setDrmUuid(@Nullable UUID uuid) { drmUuid = uuid; @@ -258,10 +268,10 @@ public final class MediaItem { } /** - * Sets whether the drm configuration is multi session enabled. + * Sets whether the DRM configuration is multi session enabled. * - *

If a {@link PlaybackProperties#uri} is set, the drm multi session flag is used to create a - * {@link PlaybackProperties} object. Otherwise it will be ignored. + *

If {@link #setUri} is passed a non-null {@code uri}, the DRM multi session flag is used to + * create a {@link PlaybackProperties} object. Otherwise it will be ignored. */ public Builder setDrmMultiSession(boolean multiSession) { drmMultiSession = multiSession; @@ -269,11 +279,11 @@ public final class MediaItem { } /** - * Sets whether to use the license URI of the media item for key requests that include their own - * license URI. + * Sets whether to use the DRM license server URI of the media item for key requests that + * include their own DRM license server URI. * - *

If a {@link PlaybackProperties#uri} is set, the drm force default license flag is used to - * create a {@link PlaybackProperties} object. Otherwise it will be ignored. + *

If {@link #setUri} is passed a non-null {@code uri}, the DRM force default license flag is + * used to create a {@link PlaybackProperties} object. Otherwise it will be ignored. */ public Builder setDrmForceDefaultLicenseUri(boolean forceDefaultLicenseUri) { this.drmForceDefaultLicenseUri = forceDefaultLicenseUri; @@ -290,7 +300,7 @@ public final class MediaItem { } /** - * Sets whether a drm session should be used for clear tracks of type {@link C#TRACK_TYPE_VIDEO} + * Sets whether a DRM session should be used for clear tracks of type {@link C#TRACK_TYPE_VIDEO} * and {@link C#TRACK_TYPE_AUDIO}. * *

This method overrides what has been set by previously calling {@link @@ -305,10 +315,10 @@ public final class MediaItem { } /** - * Sets a list of {@link C}{@code .TRACK_TYPE_*} constants for which to use a drm session even + * Sets a list of {@link C}{@code .TRACK_TYPE_*} constants for which to use a DRM session even * when the tracks are in the clear. * - *

For the common case of using a drm session for {@link C#TRACK_TYPE_VIDEO} and {@link + *

For the common case of using a DRM session for {@link C#TRACK_TYPE_VIDEO} and {@link * C#TRACK_TYPE_AUDIO} the {@link #setDrmSessionForClearPeriods(boolean)} can be used. * *

This method overrides what has been set by previously calling {@link @@ -344,8 +354,8 @@ public final class MediaItem { * *

{@code null} or an empty {@link List} can be used for a reset. * - *

If a {@link PlaybackProperties#uri} is set, the stream keys are used to create a {@link - * PlaybackProperties} object. Otherwise it will be ignored. + *

If {@link #setUri} is passed a non-null {@code uri}, the stream keys are used to create a + * {@link PlaybackProperties} object. Otherwise they will be ignored. */ public Builder setStreamKeys(@Nullable List streamKeys) { this.streamKeys = @@ -358,8 +368,8 @@ public final class MediaItem { /** * Sets the optional custom cache key (only used for progressive streams). * - *

If a {@link PlaybackProperties#uri} is set, the custom cache key is used to create a - * {@link PlaybackProperties} object. Otherwise it will be ignored. + *

If {@link #setUri} is passed a non-null {@code uri}, the custom cache key is used to + * create a {@link PlaybackProperties} object. Otherwise it will be ignored. */ public Builder setCustomCacheKey(@Nullable String customCacheKey) { this.customCacheKey = customCacheKey; @@ -371,8 +381,8 @@ public final class MediaItem { * *

{@code null} or an empty {@link List} can be used for a reset. * - *

If a {@link PlaybackProperties#uri} is set, the subtitles are used to create a {@link - * PlaybackProperties} object. Otherwise it will be ignored. + *

If {@link #setUri} is passed a non-null {@code uri}, the subtitles are used to create a + * {@link PlaybackProperties} object. Otherwise they will be ignored. */ public Builder setSubtitles(@Nullable List subtitles) { this.subtitles = @@ -385,8 +395,8 @@ public final class MediaItem { /** * Sets the optional ad tag URI. * - *

If a {@link PlaybackProperties#uri} is set, the ad tag URI is used to create a {@link - * PlaybackProperties} object. Otherwise it will be ignored. + *

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. */ public Builder setAdTagUri(@Nullable String adTagUri) { this.adTagUri = adTagUri != null ? Uri.parse(adTagUri) : null; @@ -396,8 +406,8 @@ public final class MediaItem { /** * Sets the optional ad tag {@link Uri}. * - *

If a {@link PlaybackProperties#uri} is set, the ad tag URI is used to create a {@link - * PlaybackProperties} object. Otherwise it will be ignored. + *

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. */ public Builder setAdTagUri(@Nullable Uri adTagUri) { this.adTagUri = adTagUri; @@ -409,7 +419,7 @@ public final class MediaItem { * published in the {@code com.google.android.exoplayer2.Timeline} of the source as {@code * com.google.android.exoplayer2.Timeline.Window#tag}. * - *

If a {@link PlaybackProperties#uri} is set, the tag is used to create a {@link + *

If {@link #setUri} is passed a non-null {@code uri}, the tag is used to create a {@link * PlaybackProperties} object. Otherwise it will be ignored. */ public Builder setTag(@Nullable Object tag) { @@ -472,15 +482,15 @@ public final class MediaItem { public final UUID uuid; /** - * Optional license server {@link Uri}. If {@code null} then the license server must be + * Optional DRM license server {@link Uri}. If {@code null} then the DRM license server must be * specified by the media. */ @Nullable public final Uri licenseUri; - /** The headers to attach to the request for the license URI. */ + /** The headers to attach to the request to the DRM license server. */ public final Map requestHeaders; - /** Whether the drm configuration is multi session enabled. */ + /** Whether the DRM configuration is multi session enabled. */ public final boolean multiSession; /** @@ -490,12 +500,12 @@ public final class MediaItem { public final boolean playClearContentWithoutKey; /** - * Sets whether to use the license URI of the media item for key requests that include their own - * license URI. + * Sets whether to use the DRM license server URI of the media item for key requests that + * include their own DRM license server URI. */ public final boolean forceDefaultLicenseUri; - /** The types of clear tracks for which to use a drm session. */ + /** The types of clear tracks for which to use a DRM session. */ public final List sessionForClearTypes; @Nullable private final byte[] keySetId; @@ -566,9 +576,9 @@ public final class MediaItem { public final Uri uri; /** - * The optional mime type of the item, or {@code null} if unspecified. + * The optional MIME type of the item, or {@code null} if unspecified. * - *

The mime type can be used to disambiguate media items that have a uri which does not allow + *

The MIME type can be used to disambiguate media items that have a URI which does not allow * to infer the actual media type. */ @Nullable public final String mimeType; @@ -664,7 +674,7 @@ public final class MediaItem { * Creates an instance. * * @param uri The {@link Uri URI} to the subtitle file. - * @param mimeType The mime type. + * @param mimeType The MIME type. * @param language The optional language. */ public Subtitle(Uri uri, String mimeType, @Nullable String language) { @@ -675,7 +685,7 @@ public final class MediaItem { * Creates an instance with the given selection flags. * * @param uri The {@link Uri URI} to the subtitle file. - * @param mimeType The mime type. + * @param mimeType The MIME type. * @param language The optional language. * @param selectionFlags The selection flags. */