Add support for @Supersedes annotation in ServiceLoaderWrapper

This allows us to explicitly mark an implementation as being a
replacement for another implementation. This is useful for
cases where two or more implementations of a service exist,
but only one should be used and the other can't be removed.

PiperOrigin-RevId: 766669871

Author: copybara-androidxtest

runner/monitor/CHANGELOG.md

@@ -8,6 +8,9 @@
 
 **New Features**
 
+* Adds @Supersedes to ServiceLoaderWrapper so it's possible to choose one
+implementation over another when multiple exist.
+
 **Breaking Changes**
 
 **API Changes**

runner/monitor/java/androidx/test/api/current_internal.txt

@@ -11,6 +11,10 @@ package androidx.test.internal.platform {
     method public T! create();
   }
 
+  @RestrictTo(androidx.annotation.RestrictTo.Scope.LIBRARY_GROUP) @java.lang.annotation.Documented @java.lang.annotation.Retention(java.lang.annotation.RetentionPolicy.RUNTIME) @java.lang.annotation.Target(java.lang.annotation.ElementType.TYPE) public @interface Supersedes {
+    method public abstract Class<? extends java.lang.Object!> value();
+  }
+
   @RestrictTo(androidx.annotation.RestrictTo.Scope.LIBRARY_GROUP) public interface ThreadChecker {
     method public void checkMainThread();
     method public void checkNotMainThread();

runner/monitor/java/androidx/test/internal/platform/ServiceLoaderWrapper.java

@@ -18,8 +18,10 @@
 import android.os.StrictMode;
 import androidx.annotation.RestrictTo;
 import java.util.ArrayList;
+import java.util.HashSet;
 import java.util.List;
 import java.util.ServiceLoader;
+import java.util.Set;
 
 /**
  * Wrapper class for {@link ServiceLoader} that disables StrictMode.
@@ -79,14 +81,16 @@ public static <T> T loadSingleService(Class<T> serviceClass, Factory<T> defaultI
 
   /**
    * A wrapper method around {@link #loadService(Class)} that returns one implementation of the
-   * service or {@code null} if no implementation is found.
+   * service or {@code null} if no implementation is found. If an implementation is marked with
+   * {@link Supersedes}, the implementation in Supersedes will be filtered out.
    *
    * @param serviceClass the service type class to load implementation for
-   * @return the implementing service or null if none is found.
+   * @return the implementing service or null if none is found. If an implementation is marked with
+   *     {@link Supersedes}, the implementation in Supersedes will be filtered out.
    * @throws IllegalStateException if more than one service implementations are found
    */
   public static <T> T loadSingleServiceOrNull(Class<T> serviceClass) {
-    List<T> impls = ServiceLoaderWrapper.loadService(serviceClass);
+    List<T> impls = filter(ServiceLoaderWrapper.loadService(serviceClass));
     if (impls.isEmpty()) {
       return null;
     } else if (impls.size() == 1) {
@@ -102,4 +106,27 @@ public static <T> T loadSingleServiceOrNull(Class<T> serviceClass) {
           "Found more than one implementation for " + serviceClass.getName() + combinedImpls);
     }
   }
+
+  @SuppressWarnings("unchecked")
+  private static <T> List<T> filter(List<T> services) {
+    Set<Class<?>> superseded = new HashSet<>();
+    for (T service : services) {
+      Class<? extends T> clazz = (Class<? extends T>) service.getClass();
+      Supersedes supersedes = clazz.getAnnotation(Supersedes.class);
+      if (supersedes != null) {
+        superseded.add(supersedes.value());
+      }
+    }
+    if (superseded.isEmpty()) {
+      return services;
+    } else {
+      List<T> filtered = new ArrayList<>();
+      for (T service : services) {
+        if (!superseded.contains(service.getClass())) {
+          filtered.add(service);
+        }
+      }
+      return filtered;
+    }
+  }
 }

runner/monitor/java/androidx/test/internal/platform/Supersedes.java

@@ -0,0 +1,24 @@
+package androidx.test.internal.platform;
+
+import androidx.annotation.RestrictTo;
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Indicates that the annotated type loaded by ServiceLoadWrapper is intended as a replacement for
+ * another type.
+ *
+ * @hide
+ */
+@RestrictTo(RestrictTo.Scope.LIBRARY_GROUP)
+@Documented
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.TYPE)
+public @interface Supersedes {
+
+  /** The type that is superseded by the annotated type. */
+  Class<?> value();
+}