Stabilise HttpDataSource and its nested exceptions

PiperOrigin-RevId: 438558981

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

@@ -21,7 +21,6 @@ import androidx.media3.common.util.UnstableApi;
 import java.io.IOException;
 import java.io.IOException;
 
 
 /** Used to specify reason of a DataSource error. */
 /** Used to specify reason of a DataSource error. */
-@UnstableApi
 public class DataSourceException extends IOException {
 public class DataSourceException extends IOException {
 
 
   /**
   /**
@@ -29,6 +28,7 @@ public class DataSourceException extends IOException {
    * {@link #reason} is {@link PlaybackException#ERROR_CODE_IO_READ_POSITION_OUT_OF_RANGE} in its
    * {@link #reason} is {@link PlaybackException#ERROR_CODE_IO_READ_POSITION_OUT_OF_RANGE} in its
    * cause stack.
    * cause stack.
    */
    */
+  @UnstableApi
   public static boolean isCausedByPositionOutOfRange(IOException e) {
   public static boolean isCausedByPositionOutOfRange(IOException e) {
     @Nullable Throwable cause = e;
     @Nullable Throwable cause = e;
     while (cause != null) {
     while (cause != null) {
@@ -49,7 +49,7 @@ public class DataSourceException extends IOException {
    *
    *
    * @deprecated Use {@link PlaybackException#ERROR_CODE_IO_READ_POSITION_OUT_OF_RANGE}.
    * @deprecated Use {@link PlaybackException#ERROR_CODE_IO_READ_POSITION_OUT_OF_RANGE}.
    */
    */
-  @Deprecated
+  @UnstableApi @Deprecated
   public static final int POSITION_OUT_OF_RANGE =
   public static final int POSITION_OUT_OF_RANGE =
       PlaybackException.ERROR_CODE_IO_READ_POSITION_OUT_OF_RANGE;
       PlaybackException.ERROR_CODE_IO_READ_POSITION_OUT_OF_RANGE;
 
 
@@ -65,6 +65,7 @@ public class DataSourceException extends IOException {
    * @param reason Reason of the error, should be one of the {@code ERROR_CODE_IO_*} in {@link
    * @param reason Reason of the error, should be one of the {@code ERROR_CODE_IO_*} in {@link
    *     PlaybackException.ErrorCode}.
    *     PlaybackException.ErrorCode}.
    */
    */
+  @UnstableApi
   public DataSourceException(@PlaybackException.ErrorCode int reason) {
   public DataSourceException(@PlaybackException.ErrorCode int reason) {
     this.reason = reason;
     this.reason = reason;
   }
   }
@@ -76,6 +77,7 @@ public class DataSourceException extends IOException {
    * @param reason Reason of the error, should be one of the {@code ERROR_CODE_IO_*} in {@link
    * @param reason Reason of the error, should be one of the {@code ERROR_CODE_IO_*} in {@link
    *     PlaybackException.ErrorCode}.
    *     PlaybackException.ErrorCode}.
    */
    */
+  @UnstableApi
   public DataSourceException(@Nullable Throwable cause, @PlaybackException.ErrorCode int reason) {
   public DataSourceException(@Nullable Throwable cause, @PlaybackException.ErrorCode int reason) {
     super(cause);
     super(cause);
     this.reason = reason;
     this.reason = reason;
@@ -88,6 +90,7 @@ public class DataSourceException extends IOException {
    * @param reason Reason of the error, should be one of the {@code ERROR_CODE_IO_*} in {@link
    * @param reason Reason of the error, should be one of the {@code ERROR_CODE_IO_*} in {@link
    *     PlaybackException.ErrorCode}.
    *     PlaybackException.ErrorCode}.
    */
    */
+  @UnstableApi
   public DataSourceException(@Nullable String message, @PlaybackException.ErrorCode int reason) {
   public DataSourceException(@Nullable String message, @PlaybackException.ErrorCode int reason) {
     super(message);
     super(message);
     this.reason = reason;
     this.reason = reason;
@@ -101,6 +104,7 @@ public class DataSourceException extends IOException {
    * @param reason Reason of the error, should be one of the {@code ERROR_CODE_IO_*} in {@link
    * @param reason Reason of the error, should be one of the {@code ERROR_CODE_IO_*} in {@link
    *     PlaybackException.ErrorCode}.
    *     PlaybackException.ErrorCode}.
    */
    */
+  @UnstableApi
   public DataSourceException(
   public DataSourceException(
       @Nullable String message,
       @Nullable String message,
       @Nullable Throwable cause,
       @Nullable Throwable cause,

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

@@ -38,12 +38,12 @@ import java.util.List;
 import java.util.Map;
 import java.util.Map;
 
 
 /** An HTTP {@link DataSource}. */
 /** An HTTP {@link DataSource}. */
-@UnstableApi
 public interface HttpDataSource extends DataSource {
 public interface HttpDataSource extends DataSource {
 
 
   /** A factory for {@link HttpDataSource} instances. */
   /** A factory for {@link HttpDataSource} instances. */
   interface Factory extends DataSource.Factory {
   interface Factory extends DataSource.Factory {
 
 
+    @UnstableApi
     @Override
     @Override
     HttpDataSource createDataSource();
     HttpDataSource createDataSource();
 
 
@@ -59,6 +59,7 @@ public interface HttpDataSource extends DataSource {
      * @param defaultRequestProperties The default request properties.
      * @param defaultRequestProperties The default request properties.
      * @return This factory.
      * @return This factory.
      */
      */
+    @UnstableApi
     Factory setDefaultRequestProperties(Map<String, String> defaultRequestProperties);
     Factory setDefaultRequestProperties(Map<String, String> defaultRequestProperties);
   }
   }
 
 
@@ -67,6 +68,7 @@ public interface HttpDataSource extends DataSource {
    * a thread safe way to avoid the potential of creating snapshots of an inconsistent or unintended
    * a thread safe way to avoid the potential of creating snapshots of an inconsistent or unintended
    * state.
    * state.
    */
    */
+  @UnstableApi
   final class RequestProperties {
   final class RequestProperties {
 
 
     private final Map<String, String> requestProperties;
     private final Map<String, String> requestProperties;
@@ -141,6 +143,7 @@ public interface HttpDataSource extends DataSource {
   }
   }
 
 
   /** Base implementation of {@link Factory} that sets default request properties. */
   /** Base implementation of {@link Factory} that sets default request properties. */
+  @UnstableApi
   abstract class BaseFactory implements Factory {
   abstract class BaseFactory implements Factory {
 
 
     private final RequestProperties defaultRequestProperties;
     private final RequestProperties defaultRequestProperties;
@@ -209,6 +212,7 @@ public interface HttpDataSource extends DataSource {
      * Returns a {@code HttpDataSourceException} whose error code is assigned according to the cause
      * Returns a {@code HttpDataSourceException} whose error code is assigned according to the cause
      * and type.
      * and type.
      */
      */
+    @UnstableApi
     public static HttpDataSourceException createForIOException(
     public static HttpDataSourceException createForIOException(
         IOException cause, DataSpec dataSpec, @Type int type) {
         IOException cause, DataSpec dataSpec, @Type int type) {
       @PlaybackException.ErrorCode int errorCode;
       @PlaybackException.ErrorCode int errorCode;
@@ -232,7 +236,7 @@ public interface HttpDataSource extends DataSource {
     }
     }
 
 
     /** The {@link DataSpec} associated with the current connection. */
     /** The {@link DataSpec} associated with the current connection. */
-    public final DataSpec dataSpec;
+    @UnstableApi public final DataSpec dataSpec;
 
 
     public final @Type int type;
     public final @Type int type;
 
 
@@ -240,6 +244,7 @@ public interface HttpDataSource extends DataSource {
      * @deprecated Use {@link #HttpDataSourceException(DataSpec, int, int)
      * @deprecated Use {@link #HttpDataSourceException(DataSpec, int, int)
      *     HttpDataSourceException(DataSpec, PlaybackException.ERROR_CODE_IO_UNSPECIFIED, int)}.
      *     HttpDataSourceException(DataSpec, PlaybackException.ERROR_CODE_IO_UNSPECIFIED, int)}.
      */
      */
+    @UnstableApi
     @Deprecated
     @Deprecated
     public HttpDataSourceException(DataSpec dataSpec, @Type int type) {
     public HttpDataSourceException(DataSpec dataSpec, @Type int type) {
       this(dataSpec, PlaybackException.ERROR_CODE_IO_UNSPECIFIED, type);
       this(dataSpec, PlaybackException.ERROR_CODE_IO_UNSPECIFIED, type);
@@ -253,6 +258,7 @@ public interface HttpDataSource extends DataSource {
      *     PlaybackException.ErrorCode}.
      *     PlaybackException.ErrorCode}.
      * @param type See {@link Type}.
      * @param type See {@link Type}.
      */
      */
+    @UnstableApi
     public HttpDataSourceException(
     public HttpDataSourceException(
         DataSpec dataSpec, @PlaybackException.ErrorCode int errorCode, @Type int type) {
         DataSpec dataSpec, @PlaybackException.ErrorCode int errorCode, @Type int type) {
       super(assignErrorCode(errorCode, type));
       super(assignErrorCode(errorCode, type));
@@ -265,6 +271,7 @@ public interface HttpDataSource extends DataSource {
      *     HttpDataSourceException(String, DataSpec, PlaybackException.ERROR_CODE_IO_UNSPECIFIED,
      *     HttpDataSourceException(String, DataSpec, PlaybackException.ERROR_CODE_IO_UNSPECIFIED,
      *     int)}.
      *     int)}.
      */
      */
+    @UnstableApi
     @Deprecated
     @Deprecated
     public HttpDataSourceException(String message, DataSpec dataSpec, @Type int type) {
     public HttpDataSourceException(String message, DataSpec dataSpec, @Type int type) {
       this(message, dataSpec, PlaybackException.ERROR_CODE_IO_UNSPECIFIED, type);
       this(message, dataSpec, PlaybackException.ERROR_CODE_IO_UNSPECIFIED, type);
@@ -279,6 +286,7 @@ public interface HttpDataSource extends DataSource {
      *     PlaybackException.ErrorCode}.
      *     PlaybackException.ErrorCode}.
      * @param type See {@link Type}.
      * @param type See {@link Type}.
      */
      */
+    @UnstableApi
     public HttpDataSourceException(
     public HttpDataSourceException(
         String message,
         String message,
         DataSpec dataSpec,
         DataSpec dataSpec,
@@ -294,6 +302,7 @@ public interface HttpDataSource extends DataSource {
      *     HttpDataSourceException(IOException, DataSpec,
      *     HttpDataSourceException(IOException, DataSpec,
      *     PlaybackException.ERROR_CODE_IO_UNSPECIFIED, int)}.
      *     PlaybackException.ERROR_CODE_IO_UNSPECIFIED, int)}.
      */
      */
+    @UnstableApi
     @Deprecated
     @Deprecated
     public HttpDataSourceException(IOException cause, DataSpec dataSpec, @Type int type) {
     public HttpDataSourceException(IOException cause, DataSpec dataSpec, @Type int type) {
       this(cause, dataSpec, PlaybackException.ERROR_CODE_IO_UNSPECIFIED, type);
       this(cause, dataSpec, PlaybackException.ERROR_CODE_IO_UNSPECIFIED, type);
@@ -308,6 +317,7 @@ public interface HttpDataSource extends DataSource {
      *     PlaybackException.ErrorCode}.
      *     PlaybackException.ErrorCode}.
      * @param type See {@link Type}.
      * @param type See {@link Type}.
      */
      */
+    @UnstableApi
     public HttpDataSourceException(
     public HttpDataSourceException(
         IOException cause,
         IOException cause,
         DataSpec dataSpec,
         DataSpec dataSpec,
@@ -323,6 +333,7 @@ public interface HttpDataSource extends DataSource {
      *     HttpDataSourceException(String, IOException, DataSpec,
      *     HttpDataSourceException(String, IOException, DataSpec,
      *     PlaybackException.ERROR_CODE_IO_UNSPECIFIED, int)}.
      *     PlaybackException.ERROR_CODE_IO_UNSPECIFIED, int)}.
      */
      */
+    @UnstableApi
     @Deprecated
     @Deprecated
     public HttpDataSourceException(
     public HttpDataSourceException(
         String message, IOException cause, DataSpec dataSpec, @Type int type) {
         String message, IOException cause, DataSpec dataSpec, @Type int type) {
@@ -339,6 +350,7 @@ public interface HttpDataSource extends DataSource {
      *     PlaybackException.ErrorCode}.
      *     PlaybackException.ErrorCode}.
      * @param type See {@link Type}.
      * @param type See {@link Type}.
      */
      */
+    @UnstableApi
     public HttpDataSourceException(
     public HttpDataSourceException(
         String message,
         String message,
         @Nullable IOException cause,
         @Nullable IOException cause,
@@ -366,6 +378,7 @@ public interface HttpDataSource extends DataSource {
    */
    */
   final class CleartextNotPermittedException extends HttpDataSourceException {
   final class CleartextNotPermittedException extends HttpDataSourceException {
 
 
+    @UnstableApi
     public CleartextNotPermittedException(IOException cause, DataSpec dataSpec) {
     public CleartextNotPermittedException(IOException cause, DataSpec dataSpec) {
       super(
       super(
           "Cleartext HTTP traffic not permitted. See"
           "Cleartext HTTP traffic not permitted. See"
@@ -382,6 +395,7 @@ public interface HttpDataSource extends DataSource {
 
 
     public final String contentType;
     public final String contentType;
 
 
+    @UnstableApi
     public InvalidContentTypeException(String contentType, DataSpec dataSpec) {
     public InvalidContentTypeException(String contentType, DataSpec dataSpec) {
       super(
       super(
           "Invalid content type: " + contentType,
           "Invalid content type: " + contentType,
@@ -413,6 +427,7 @@ public interface HttpDataSource extends DataSource {
      * @deprecated Use {@link #InvalidResponseCodeException(int, String, IOException, Map, DataSpec,
      * @deprecated Use {@link #InvalidResponseCodeException(int, String, IOException, Map, DataSpec,
      *     byte[])}.
      *     byte[])}.
      */
      */
+    @UnstableApi
     @Deprecated
     @Deprecated
     public InvalidResponseCodeException(
     public InvalidResponseCodeException(
         int responseCode, Map<String, List<String>> headerFields, DataSpec dataSpec) {
         int responseCode, Map<String, List<String>> headerFields, DataSpec dataSpec) {
@@ -429,6 +444,7 @@ public interface HttpDataSource extends DataSource {
      * @deprecated Use {@link #InvalidResponseCodeException(int, String, IOException, Map, DataSpec,
      * @deprecated Use {@link #InvalidResponseCodeException(int, String, IOException, Map, DataSpec,
      *     byte[])}.
      *     byte[])}.
      */
      */
+    @UnstableApi
     @Deprecated
     @Deprecated
     public InvalidResponseCodeException(
     public InvalidResponseCodeException(
         int responseCode,
         int responseCode,
@@ -444,6 +460,7 @@ public interface HttpDataSource extends DataSource {
           /* responseBody= */ Util.EMPTY_BYTE_ARRAY);
           /* responseBody= */ Util.EMPTY_BYTE_ARRAY);
     }
     }
 
 
+    @UnstableApi
     public InvalidResponseCodeException(
     public InvalidResponseCodeException(
         int responseCode,
         int responseCode,
         @Nullable String responseMessage,
         @Nullable String responseMessage,
@@ -471,12 +488,15 @@ public interface HttpDataSource extends DataSource {
    * (in order of decreasing priority) the {@code dataSpec}, {@link #setRequestProperty} and the
    * (in order of decreasing priority) the {@code dataSpec}, {@link #setRequestProperty} and the
    * default parameters set in the {@link Factory}.
    * default parameters set in the {@link Factory}.
    */
    */
+  @UnstableApi
   @Override
   @Override
   long open(DataSpec dataSpec) throws HttpDataSourceException;
   long open(DataSpec dataSpec) throws HttpDataSourceException;
 
 
+  @UnstableApi
   @Override
   @Override
   void close() throws HttpDataSourceException;
   void close() throws HttpDataSourceException;
 
 
+  @UnstableApi
   @Override
   @Override
   int read(byte[] buffer, int offset, int length) throws HttpDataSourceException;
   int read(byte[] buffer, int offset, int length) throws HttpDataSourceException;
 
 
@@ -491,6 +511,7 @@ public interface HttpDataSource extends DataSource {
    * @param name The name of the header field.
    * @param name The name of the header field.
    * @param value The value of the field.
    * @param value The value of the field.
    */
    */
+  @UnstableApi
   void setRequestProperty(String name, String value);
   void setRequestProperty(String name, String value);
 
 
   /**
   /**
@@ -499,17 +520,21 @@ public interface HttpDataSource extends DataSource {
    *
    *
    * @param name The name of the header field.
    * @param name The name of the header field.
    */
    */
+  @UnstableApi
   void clearRequestProperty(String name);
   void clearRequestProperty(String name);
 
 
   /** Clears all request headers that were set by {@link #setRequestProperty(String, String)}. */
   /** Clears all request headers that were set by {@link #setRequestProperty(String, String)}. */
+  @UnstableApi
   void clearAllRequestProperties();
   void clearAllRequestProperties();
 
 
   /**
   /**
    * When the source is open, returns the HTTP response status code associated with the last {@link
    * When the source is open, returns the HTTP response status code associated with the last {@link
    * #open} call. Otherwise, returns a negative value.
    * #open} call. Otherwise, returns a negative value.
    */
    */
+  @UnstableApi
   int getResponseCode();
   int getResponseCode();
 
 
+  @UnstableApi
   @Override
   @Override
   Map<String, List<String>> getResponseHeaders();
   Map<String, List<String>> getResponseHeaders();
 }
 }