Promote ComponentLoader to new opentelemetry-api-util, standardize SPI loading (#7446)

Author: jack-berg

README.md

@@ -71,6 +71,7 @@ The OpenTelemetry API for recording telemetry.
 | [API](./api/all)                  | OpenTelemetry API, including metrics, traces, baggage, context                       | `opentelemetry-api`           | <!--VERSION_STABLE-->1.51.0<!--/VERSION_STABLE-->           | [![Javadocs](https://www.javadoc.io/badge/io.opentelemetry/opentelemetry-api.svg)](https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-api)                     |
 | [API  Incubator](./api/incubator) | API incubator, including pass through propagator, and extended tracer, and Event API | `opentelemetry-api-incubator` | <!--VERSION_UNSTABLE-->1.51.0-alpha<!--/VERSION_UNSTABLE--> | [![Javadocs](https://www.javadoc.io/badge/io.opentelemetry/opentelemetry-api-incubator.svg)](https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-api-incubator) |
 | [Context API](./context)          | OpenTelemetry context API                                                            | `opentelemetry-context`       | <!--VERSION_STABLE-->1.51.0<!--/VERSION_STABLE-->           | [![Javadocs](https://www.javadoc.io/badge/io.opentelemetry/opentelemetry-context.svg)](https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-context)             |
+| [Common](./common)                | Common utility methods used across API components                                    | `opentelemetry-common`        | TODO: add after first publish                               | TODO: add link after first publish                                                                                                                                    |
 </details>
 
 <details>

all/src/test/java/io/opentelemetry/all/SdkDesignTest.java

@@ -28,7 +28,7 @@ class SdkDesignTest {
    * Ensures that all SDK methods that: - are defined in classes that extend or implement API model
    * and are public (to exclude protected builders) - are public (avoids issues with protected
    * methods returning classes unavailable to test's CL) - override or implement parent method
-   * return only API, Context or generic Java type.
+   * return only API, Context, Common, or generic Java type.
    */
   @Test
   void sdkImplementationOfApiClassesShouldReturnApiTypeOnly() {
@@ -45,7 +45,11 @@ void sdkImplementationOfApiClassesShouldReturnApiTypeOnly() {
             .and(implementOrOverride())
             .should()
             .haveRawReturnType(
-                inPackage("io.opentelemetry.api..", "io.opentelemetry.context..", "java.."))
+                inPackage(
+                    "io.opentelemetry.api..",
+                    "io.opentelemetry.context..",
+                    "io.opentelemetry.common..",
+                    "java.."))
             .orShould()
             .haveRawReturnType("void");
 

api/incubator/src/main/java/io/opentelemetry/api/incubator/config/DeclarativeConfigProperties.java

@@ -7,6 +7,7 @@
 
 import static io.opentelemetry.api.internal.ConfigUtil.defaultIfNull;
 
+import io.opentelemetry.common.ComponentLoader;
 import java.util.List;
 import java.util.Map;
 import java.util.Set;
@@ -228,4 +229,7 @@ default List<DeclarativeConfigProperties> getStructuredList(
    * @return the configuration property keys
    */
   Set<String> getPropertyKeys();
+
+  /** Return a {@link ComponentLoader} that should be used to load SPIs. */
+  ComponentLoader getComponentLoader();
 }

api/incubator/src/main/java/io/opentelemetry/api/incubator/config/EmptyDeclarativeConfigProperties.java

@@ -5,6 +5,7 @@
 
 package io.opentelemetry.api.incubator.config;
 
+import io.opentelemetry.common.ComponentLoader;
 import java.util.Collections;
 import java.util.List;
 import java.util.Set;
@@ -15,6 +16,8 @@ final class EmptyDeclarativeConfigProperties implements DeclarativeConfigPropert
 
   private static final EmptyDeclarativeConfigProperties INSTANCE =
       new EmptyDeclarativeConfigProperties();
+  private static final ComponentLoader COMPONENT_LOADER =
+      ComponentLoader.forClassLoader(EmptyDeclarativeConfigProperties.class.getClassLoader());
 
   private EmptyDeclarativeConfigProperties() {}
 
@@ -74,4 +77,9 @@ public List<DeclarativeConfigProperties> getStructuredList(String name) {
   public Set<String> getPropertyKeys() {
     return Collections.emptySet();
   }
+
+  @Override
+  public ComponentLoader getComponentLoader() {
+    return COMPONENT_LOADER;
+  }
 }

common/build.gradle.kts

@@ -0,0 +1,12 @@
+plugins {
+  id("otel.java-conventions")
+  id("otel.publish-conventions")
+
+  id("otel.animalsniffer-conventions")
+}
+
+description = "OpenTelemetry API Common"
+otelJava.moduleName.set("io.opentelemetry.common")
+
+dependencies {
+}

common/src/main/java/io/opentelemetry/common/ComponentLoader.java

@@ -0,0 +1,28 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.common;
+
+import java.util.ServiceLoader;
+
+/** A loader for components that are discovered via SPI. */
+public interface ComponentLoader {
+  /**
+   * Load implementations of an SPI.
+   *
+   * @param spiClass the SPI class
+   * @param <T> the SPI type
+   * @return iterable of SPI implementations
+   */
+  <T> Iterable<T> load(Class<T> spiClass);
+
+  /**
+   * Create an instance for the {@code classLoader} using {@link ServiceLoader#load(Class,
+   * ClassLoader)}.
+   */
+  static ComponentLoader forClassLoader(ClassLoader classLoader) {
+    return new ServiceLoaderComponentLoader(classLoader);
+  }
+}

common/src/main/java/io/opentelemetry/common/ServiceLoaderComponentLoader.java

@@ -0,0 +1,27 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.common;
+
+import java.util.ServiceLoader;
+
+class ServiceLoaderComponentLoader implements ComponentLoader {
+
+  private final ClassLoader classLoader;
+
+  ServiceLoaderComponentLoader(ClassLoader classLoader) {
+    this.classLoader = classLoader;
+  }
+
+  @Override
+  public <T> Iterable<T> load(Class<T> spiClass) {
+    return ServiceLoader.load(spiClass, classLoader);
+  }
+
+  @Override
+  public String toString() {
+    return "ServiceLoaderComponentLoader{classLoader=" + classLoader + "}";
+  }
+}

context/build.gradle.kts

@@ -10,6 +10,7 @@ description = "OpenTelemetry Context (Incubator)"
 otelJava.moduleName.set("io.opentelemetry.context")
 
 dependencies {
+  api(project(":common"))
   // MustBeClosed
   compileOnly("com.google.errorprone:error_prone_annotations")
 

context/src/main/java/io/opentelemetry/context/LazyStorage.java

@@ -37,9 +37,9 @@
 
 package io.opentelemetry.context;
 
+import io.opentelemetry.common.ComponentLoader;
 import java.util.ArrayList;
 import java.util.List;
-import java.util.ServiceLoader;
 import java.util.concurrent.atomic.AtomicReference;
 import java.util.function.Function;
 import java.util.logging.Level;
@@ -103,9 +103,10 @@ static ContextStorage createStorage(AtomicReference<Throwable> deferredStorageFa
       return ContextStorage.defaultStorage();
     }
 
+    ComponentLoader componentLoader =
+        ComponentLoader.forClassLoader(LazyStorage.class.getClassLoader());
     List<ContextStorageProvider> providers = new ArrayList<>();
-    for (ContextStorageProvider provider :
-        ServiceLoader.load(ContextStorageProvider.class, LazyStorage.class.getClassLoader())) {
+    for (ContextStorageProvider provider : componentLoader.load(ContextStorageProvider.class)) {
       if (provider
           .getClass()
           .getName()

docs/apidiffs/current_vs_latest/opentelemetry-common.txt

@@ -0,0 +1,7 @@
+Comparing source compatibility of opentelemetry-common-1.52.0-SNAPSHOT.jar against 
++++  NEW INTERFACE: PUBLIC(+) ABSTRACT(+) io.opentelemetry.common.ComponentLoader  (not serializable)
+	+++  CLASS FILE FORMAT VERSION: 52.0 <- n.a.
+	+++  NEW SUPERCLASS: java.lang.Object
+	+++  NEW METHOD: PUBLIC(+) STATIC(+) io.opentelemetry.common.ComponentLoader forClassLoader(java.lang.ClassLoader)
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) java.lang.Iterable<T> load(java.lang.Class<T>)
+		GENERIC TEMPLATES: +++ T:java.lang.Object