Use TransformationException for error listener parameter.

PiperOrigin-RevId: 416307600

RELEASENOTES.md

@@ -67,6 +67,8 @@
         ([#9765](https://github.com/google/ExoPlayer/issues/9765)).
 *   Transformer:
     *   Increase required min API version to 21.
+    *   `TransformationException` is now used to describe errors that occur
+        during a transformation.
 *   MediaSession extension:
     *   Remove deprecated call to `onStop(/* reset= */ true)` and provide an
         opt-out flag for apps that don't want to clear the playlist on stop.

docs/transforming-media.md

@@ -70,7 +70,7 @@ Transformer.Listener transformerListener =
      }
 
      @Override
-     public void onTransformationError(MediaItem inputMediaItem, Exception e) {
+     public void onTransformationError(MediaItem inputMediaItem, TransformationException e) {
        displayError(e);
      }
    };

library/transformer/src/androidTest/java/com/google/android/exoplayer2/transformer/mh/AndroidTestUtil.java

@@ -25,6 +25,7 @@ import android.os.Build;
 import androidx.annotation.Nullable;
 import androidx.test.platform.app.InstrumentationRegistry;
 import com.google.android.exoplayer2.MediaItem;
+import com.google.android.exoplayer2.transformer.TransformationException;
 import com.google.android.exoplayer2.transformer.Transformer;
 import java.io.File;
 import java.io.FileWriter;
@@ -79,7 +80,8 @@ import org.checkerframework.checker.nullness.compatqual.NullableType;
                   }
 
                   @Override
-                  public void onTransformationError(MediaItem inputMediaItem, Exception exception) {
+                  public void onTransformationError(
+                      MediaItem inputMediaItem, TransformationException exception) {
                     exceptionReference.set(exception);
                     countDownLatch.countDown();
                   }

library/transformer/src/main/java/com/google/android/exoplayer2/transformer/Transformer.java

@@ -466,19 +466,26 @@ public final class Transformer {
   public interface Listener {
 
     /**
-     * Called when the transformation is completed.
+     * Called when the transformation is completed successfully.
      *
      * @param inputMediaItem The {@link MediaItem} for which the transformation is completed.
      */
     default void onTransformationCompleted(MediaItem inputMediaItem) {}
 
+    /** @deprecated Use {@link #onTransformationError(MediaItem, TransformationException)}. */
+    @Deprecated
+    default void onTransformationError(MediaItem inputMediaItem, Exception exception) {
+      onTransformationError(inputMediaItem, (TransformationException) exception);
+    }
+
     /**
-     * Called if an error occurs during the transformation.
+     * Called if an exception occurs during the transformation.
      *
-     * @param inputMediaItem The {@link MediaItem} for which the error occurs.
-     * @param exception The exception describing the error.
+     * @param inputMediaItem The {@link MediaItem} for which the exception occurs.
+     * @param exception The {@link TransformationException} describing the exception.
      */
-    default void onTransformationError(MediaItem inputMediaItem, Exception exception) {}
+    default void onTransformationError(
+        MediaItem inputMediaItem, TransformationException exception) {}
   }
 
   /** Provider for views to show diagnostic information during transformation, for debugging. */

library/transformer/src/test/java/com/google/android/exoplayer2/transformer/TransformerTest.java

@@ -238,9 +238,8 @@ public final class TransformerTest {
     MediaItem mediaItem = MediaItem.fromUri("asset:///non-existing-path.mp4");
 
     transformer.startTransformation(mediaItem, outputPath);
-    Exception exception = TransformerTestRunner.runUntilError(transformer);
+    TransformationException exception = TransformerTestRunner.runUntilError(transformer);
 
-    assertThat(exception).isInstanceOf(TransformationException.class);
     assertThat(exception).hasCauseThat().isInstanceOf(ExoPlaybackException.class);
     assertThat(exception).hasCauseThat().hasCauseThat().isInstanceOf(IOException.class);
   }
@@ -252,9 +251,8 @@ public final class TransformerTest {
     MediaItem mediaItem = MediaItem.fromUri(URI_PREFIX + FILE_WITH_ALL_SAMPLE_FORMATS_UNSUPPORTED);
 
     transformer.startTransformation(mediaItem, outputPath);
-    Exception exception = TransformerTestRunner.runUntilError(transformer);
+    TransformationException exception = TransformerTestRunner.runUntilError(transformer);
 
-    assertThat(exception).isInstanceOf(TransformationException.class);
     assertThat(exception).hasCauseThat().isInstanceOf(IllegalStateException.class);
   }
 

library/transformer/src/test/java/com/google/android/exoplayer2/transformer/TransformerTestRunner.java

@@ -56,8 +56,9 @@ public final class TransformerTestRunner {
    * @throws IllegalStateException If the method is not called from the main thread, or if the
    *     transformation completes without error.
    */
-  public static Exception runUntilError(Transformer transformer) throws TimeoutException {
-    @Nullable Exception exception = runUntilListenerCalled(transformer);
+  public static TransformationException runUntilError(Transformer transformer)
+      throws TimeoutException {
+    @Nullable TransformationException exception = runUntilListenerCalled(transformer);
     if (exception == null) {
       throw new IllegalStateException("The transformation completed without error.");
     }
@@ -65,7 +66,8 @@ public final class TransformerTestRunner {
   }
 
   @Nullable
-  private static Exception runUntilListenerCalled(Transformer transformer) throws TimeoutException {
+  private static TransformationException runUntilListenerCalled(Transformer transformer)
+      throws TimeoutException {
     TransformationResult transformationResult = new TransformationResult();
     Transformer.Listener listener =
         new Transformer.Listener() {
@@ -75,7 +77,8 @@ public final class TransformerTestRunner {
           }
 
           @Override
-          public void onTransformationError(MediaItem inputMediaItem, Exception exception) {
+          public void onTransformationError(
+              MediaItem inputMediaItem, TransformationException exception) {
             transformationResult.exception = exception;
           }
         };
@@ -88,6 +91,6 @@ public final class TransformerTestRunner {
 
   private static class TransformationResult {
     public boolean isCompleted;
-    @Nullable public Exception exception;
+    @Nullable public TransformationException exception;
   }
 }