DataSpec: Add customData field.

PiperOrigin-RevId: 294520836

RELEASENOTES.md

@@ -19,7 +19,7 @@
   * Move player message-related constants from `C` to `Renderer`, to avoid
     having the constants class depend on player/renderer classes.
   * Split out `common` and `extractor` submodules.
-  * Add `DataSpec.Builder`.
+  * Add `DataSpec.Builder` and `DataSpec.customData`.
 * Text:
   * Parse `<ruby>` and `<rt>` tags in WebVTT subtitles (rendering is coming
     later).

library/common/src/main/java/com/google/android/exoplayer2/upstream/DataSpec.java

@@ -44,6 +44,7 @@ public final class DataSpec {
     private long length;
     @Nullable private String key;
     @Flags private int flags;
+    @Nullable private Object customData;
 
     /** Creates a new instance with default values. */
     public Builder() {
@@ -67,6 +68,7 @@ public final class DataSpec {
       length = dataSpec.length;
       key = dataSpec.key;
       flags = dataSpec.flags;
+      customData = dataSpec.customData;
     }
 
     /**
@@ -169,6 +171,17 @@ public final class DataSpec {
     }
 
     /**
+     * Sets the {@link DataSpec#customData}. The default value is {@code null}.
+     *
+     * @param customData The {@link DataSpec#customData}.
+     * @return The builder.
+     */
+    public Builder setCustomData(@Nullable Object customData) {
+      this.customData = customData;
+      return this;
+    }
+
+    /**
      * Builds a {@link DataSpec} with the builder's current values.
      *
      * @return The build {@link DataSpec}.
@@ -185,7 +198,8 @@ public final class DataSpec {
           position,
           length,
           key,
-          flags);
+          flags,
+          customData);
     }
   }
 
@@ -326,6 +340,14 @@ public final class DataSpec {
   @Flags public final int flags;
 
   /**
+   * Application specific data.
+   *
+   * <p>This field is intended for advanced use cases in which applications require the ability to
+   * attach custom data to {@link DataSpec} instances. The custom data should be immutable.
+   */
+  @Nullable public final Object customData;
+
+  /**
    * Constructs an instance.
    *
    * @param uri {@link #uri}.
@@ -517,7 +539,8 @@ public final class DataSpec {
         position,
         length,
         key,
-        flags);
+        flags,
+        /* customData= */ null);
   }
 
   @SuppressWarnings("deprecation")
@@ -530,7 +553,8 @@ public final class DataSpec {
       long position,
       long length,
       @Nullable String key,
-      @Flags int flags) {
+      @Flags int flags,
+      @Nullable Object customData) {
     // TODO: Replace this assertion with a stricter one checking "uriPositionOffset >= 0", after
     // validating there are no violations in ExoPlayer and 1P apps.
     Assertions.checkArgument(uriPositionOffset + position >= 0);
@@ -546,6 +570,7 @@ public final class DataSpec {
     this.length = length;
     this.key = key;
     this.flags = flags;
+    this.customData = customData;
   }
 
   /**
@@ -601,7 +626,8 @@ public final class DataSpec {
           position + offset,
           length,
           key,
-          flags);
+          flags,
+          customData);
     }
   }
 
@@ -621,7 +647,8 @@ public final class DataSpec {
         position,
         length,
         key,
-        flags);
+        flags,
+        customData);
   }
 
   /**
@@ -641,7 +668,8 @@ public final class DataSpec {
         position,
         length,
         key,
-        flags);
+        flags,
+        customData);
   }
 
   /**
@@ -664,7 +692,8 @@ public final class DataSpec {
         position,
         length,
         key,
-        flags);
+        flags,
+        customData);
   }
 
   @Override

library/common/src/test/java/com/google/android/exoplayer2/upstream/DataSpecTest.java

@@ -141,6 +141,7 @@ public class DataSpecTest {
     Uri uri = Uri.parse("www.google.com");
     Map<String, String> httpRequestHeaders = createHttpRequestHeaders(3);
     byte[] httpBody = new byte[] {0, 1, 2, 3};
+    Object customData = new Object();
 
     DataSpec dataSpec =
         new DataSpec.Builder()
@@ -153,6 +154,7 @@ public class DataSpecTest {
             .setKey("key")
             .setFlags(DataSpec.FLAG_ALLOW_GZIP)
             .setHttpRequestHeaders(httpRequestHeaders)
+            .setCustomData(customData)
             .build();
 
     assertThat(dataSpec.uri).isEqualTo(uri);
@@ -166,6 +168,7 @@ public class DataSpecTest {
     assertThat(dataSpec.length).isEqualTo(5);
     assertThat(dataSpec.key).isEqualTo("key");
     assertThat(dataSpec.flags).isEqualTo(DataSpec.FLAG_ALLOW_GZIP);
+    assertThat(dataSpec.customData).isEqualTo(customData);
     assertHttpRequestHeadersReadOnly(dataSpec);
   }
 
@@ -175,6 +178,7 @@ public class DataSpecTest {
     Uri uri = Uri.parse("www.google.com");
     Map<String, String> httpRequestHeaders = createHttpRequestHeaders(3);
     byte[] httpBody = new byte[] {0, 1, 2, 3};
+    Object customData = new Object();
 
     DataSpec dataSpec =
         new DataSpec.Builder()
@@ -187,6 +191,7 @@ public class DataSpecTest {
             .setKey("key")
             .setFlags(DataSpec.FLAG_ALLOW_GZIP)
             .setHttpRequestHeaders(httpRequestHeaders)
+            .setCustomData(customData)
             .build();
 
     // Build upon the DataSpec.
@@ -203,6 +208,7 @@ public class DataSpecTest {
     assertThat(dataSpec.length).isEqualTo(5);
     assertThat(dataSpec.key).isEqualTo("key");
     assertThat(dataSpec.flags).isEqualTo(DataSpec.FLAG_ALLOW_GZIP);
+    assertThat(dataSpec.customData).isEqualTo(customData);
     assertHttpRequestHeadersReadOnly(dataSpec);
   }
 
@@ -347,6 +353,7 @@ public class DataSpecTest {
     assertThat(dataSpec.length).isEqualTo(C.LENGTH_UNSET);
     assertThat(dataSpec.key).isNull();
     assertThat(dataSpec.flags).isEqualTo(0);
+    assertThat(dataSpec.customData).isNull();
     assertHttpRequestHeadersReadOnly(dataSpec);
   }