rename AsyncOperationEndXX to AsyncEndXX, rename AttributeForReturnValue to AttributeReturnValue

Author: Duncan-tree-zhou

CHANGELOG.md

@@ -1995,7 +1995,7 @@ too disruptive to adopt right away.
   - `io.opentelemetry.instrumentation.graphql.GraphQLTelemetry`
     → `io.opentelemetry.instrumentation.graphql.v12_0.GraphQLTelemetry`
   - `io.opentelemetry.instrumentation.guava.GuavaAsyncOperationEndStrategy`
-    → `io.opentelemetry.instrumentation.guava.v10_0.GuavaAsyncOperationEndStrategy`
+    → `io.opentelemetry.instrumentation.guava.v10_0.GuavaAsyncEndStrategy`
   - `io.opentelemetry.instrumentation.hikaricp.HikariTelemetry`
     → `io.opentelemetry.instrumentation.hikaricp.v3_0.HikariTelemetry`
   - `io.opentelemetry.instrumentation.kafkaclients.KafkaTelemetry`

instrumentation-annotations-incubator/src/main/java/io/opentelemetry/instrumentation/annotations/incubator/AttributeForReturnValue.java renamed to instrumentation-annotations-incubator/src/main/java/io/opentelemetry/instrumentation/annotations/incubator/AttributeReturnValue.java

@@ -26,7 +26,7 @@
  */
 @Target(ElementType.METHOD)
 @Retention(RetentionPolicy.RUNTIME)
-public @interface AttributeForReturnValue {
+public @interface AttributeReturnValue {
 
   /**
    * Attribute name for the return value.

instrumentation-annotations-support/src/main/java/io/opentelemetry/instrumentation/api/annotation/support/async/AsyncOperationEndHandler.java renamed to instrumentation-annotations-support/src/main/java/io/opentelemetry/instrumentation/api/annotation/support/async/AsyncEndHandler.java

@@ -9,7 +9,7 @@
 import javax.annotation.Nullable;
 
 /** Callback that is called when async computation completes. */
-public interface AsyncOperationEndHandler<REQUEST, RESPONSE> {
+public interface AsyncEndHandler<REQUEST, RESPONSE> {
   void handle(
       Context context, REQUEST request, @Nullable RESPONSE response, @Nullable Throwable error);
 }

instrumentation-annotations-support/src/main/java/io/opentelemetry/instrumentation/api/annotation/support/async/AsyncEndStrategies.java

@@ -0,0 +1,45 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.api.annotation.support.async;
+
+import javax.annotation.Nullable;
+
+/** A global registry of {@link AsyncEndStrategy} implementations. */
+public abstract class AsyncEndStrategies {
+  private static volatile AsyncEndStrategies instance;
+
+  /**
+   * Sets the actual strategies' registry implementation. The javaagent uses weak references to make
+   * unloading strategy classes possible.
+   *
+   * <p>This is supposed to be only called by the javaagent. <b>Instrumentation must not call
+   * this.</b>
+   */
+  public static void internalSetStrategiesStorage(AsyncEndStrategies strategies) {
+    instance = strategies;
+  }
+
+  /** Obtain instance of the async strategy registry. */
+  public static AsyncEndStrategies instance() {
+    if (instance == null) {
+      instance = new AsyncEndStrategiesImpl();
+    }
+    return instance;
+  }
+
+  /** Add the passed {@code strategy} to the registry. */
+  public abstract void registerStrategy(AsyncEndStrategy strategy);
+
+  /** Remove the passed {@code strategy} from the registry. */
+  public abstract void unregisterStrategy(AsyncEndStrategy strategy);
+
+  /**
+   * Returns an {@link AsyncEndStrategy} that is able to compose over {@code returnType}, or {@code
+   * null} if passed type is not supported by any of the strategies stored in this registry.
+   */
+  @Nullable
+  public abstract AsyncEndStrategy resolveStrategy(Class<?> returnType);
+}

instrumentation-annotations-support/src/main/java/io/opentelemetry/instrumentation/api/annotation/support/async/AsyncOperationEndStrategiesImpl.java renamed to instrumentation-annotations-support/src/main/java/io/opentelemetry/instrumentation/api/annotation/support/async/AsyncEndStrategiesImpl.java

@@ -12,27 +12,27 @@
 import javax.annotation.Nullable;
 
 /** Default strategies' registry implementation that uses strong references. */
-final class AsyncOperationEndStrategiesImpl extends AsyncOperationEndStrategies {
-  private final List<AsyncOperationEndStrategy> strategies = new CopyOnWriteArrayList<>();
+final class AsyncEndStrategiesImpl extends AsyncEndStrategies {
+  private final List<AsyncEndStrategy> strategies = new CopyOnWriteArrayList<>();
 
-  AsyncOperationEndStrategiesImpl() {
-    registerStrategy(Jdk8AsyncOperationEndStrategy.INSTANCE);
+  AsyncEndStrategiesImpl() {
+    registerStrategy(Jdk8AsyncEndStrategy.INSTANCE);
   }
 
   @Override
-  public void registerStrategy(AsyncOperationEndStrategy strategy) {
+  public void registerStrategy(AsyncEndStrategy strategy) {
     strategies.add(requireNonNull(strategy));
   }
 
   @Override
-  public void unregisterStrategy(AsyncOperationEndStrategy strategy) {
+  public void unregisterStrategy(AsyncEndStrategy strategy) {
     strategies.remove(strategy);
   }
 
   @Nullable
   @Override
-  public AsyncOperationEndStrategy resolveStrategy(Class<?> returnType) {
-    for (AsyncOperationEndStrategy strategy : strategies) {
+  public AsyncEndStrategy resolveStrategy(Class<?> returnType) {
+    for (AsyncEndStrategy strategy : strategies) {
       if (strategy.supports(returnType)) {
         return strategy;
       }

instrumentation-annotations-support/src/main/java/io/opentelemetry/instrumentation/api/annotation/support/async/AsyncOperationEndStrategy.java renamed to instrumentation-annotations-support/src/main/java/io/opentelemetry/instrumentation/api/annotation/support/async/AsyncEndStrategy.java

@@ -12,9 +12,9 @@
  * Implementations of this interface describe how to compose over {@linkplain #supports(Class)
  * supported} asynchronous computation types and delay marking the operation as ended by calling
  * {@link Instrumenter#end(Context, Object, Object, Throwable)} or {@link
- * AsyncOperationEndHandler#handle(Context, Object, Object, Throwable)}.
+ * AsyncEndHandler#handle(Context, Object, Object, Throwable)}.
  */
-public interface AsyncOperationEndStrategy {
+public interface AsyncEndStrategy {
 
   /**
    * Returns true for every asynchronous computation type {@code asyncType} this strategy supports.
@@ -47,12 +47,12 @@ default <REQUEST, RESPONSE> Object end(
   }
 
   /**
-   * Composes over {@code asyncValue} and delays the {@link AsyncOperationEndHandler#handle(Context,
-   * Object, Object, Throwable)} call until after the asynchronous operation represented by {@code
+   * Composes over {@code asyncValue} and delays the {@link AsyncEndHandler#handle(Context, Object,
+   * Object, Throwable)} call until after the asynchronous operation represented by {@code
    * asyncValue} completes.
    *
-   * @param handler The {@link AsyncOperationEndHandler} to be used to end the operation stored in
-   *     the {@code context}.
+   * @param handler The {@link AsyncEndHandler} to be used to end the operation stored in the {@code
+   *     context}.
    * @param asyncValue Return value from the instrumented method. Must be an instance of a {@code
    *     asyncType} for which {@link #supports(Class)} returned true (in particular it must not be
    *     {@code null}).
@@ -63,7 +63,7 @@ default <REQUEST, RESPONSE> Object end(
    *     of completion.
    */
   <REQUEST, RESPONSE> Object end(
-      AsyncOperationEndHandler<REQUEST, RESPONSE> handler,
+      AsyncEndHandler<REQUEST, RESPONSE> handler,
       Context context,
       REQUEST request,
       Object asyncValue,

instrumentation-annotations-support/src/main/java/io/opentelemetry/instrumentation/api/annotation/support/async/AsyncEndSupport.java

@@ -0,0 +1,109 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.api.annotation.support.async;
+
+import io.opentelemetry.context.Context;
+import io.opentelemetry.instrumentation.api.instrumenter.Instrumenter;
+import javax.annotation.Nullable;
+
+/**
+ * A wrapper over {@link AsyncEndHandler} that is able to defer {@link
+ * AsyncEndHandler#handle(Context, Object, Object, Throwable)} until asynchronous computation
+ * finishes.
+ */
+public final class AsyncEndSupport<REQUEST, RESPONSE> {
+
+  /**
+   * Returns a new {@link AsyncEndSupport} that wraps over passed {@code instrumenter}, configured
+   * for usage with asynchronous computations that are instances of {@code asyncType}. If the result
+   * of the async computation ends up being an instance of {@code responseType} it will be passed as
+   * the response to the {@code instrumenter} call; otherwise {@code null} value will be used as the
+   * response.
+   */
+  public static <REQUEST, RESPONSE> AsyncEndSupport<REQUEST, RESPONSE> create(
+      Instrumenter<REQUEST, RESPONSE> instrumenter,
+      Class<RESPONSE> responseType,
+      Class<?> asyncType) {
+    return new AsyncEndSupport<>(
+        instrumenter::end,
+        responseType,
+        asyncType,
+        AsyncEndStrategies.instance().resolveStrategy(asyncType));
+  }
+
+  /**
+   * Returns a new {@link AsyncEndSupport} that wraps over passed {@code handler}, configured for
+   * usage with asynchronous computations that are instances of {@code asyncType}. If the result of
+   * the async computation ends up being an instance of {@code responseType} it will be passed as
+   * the response to the {@code handler} call; otherwise {@code null} value will be used as the
+   * response.
+   */
+  public static <REQUEST, RESPONSE> AsyncEndSupport<REQUEST, RESPONSE> create(
+      AsyncEndHandler<REQUEST, RESPONSE> handler,
+      Class<RESPONSE> responseType,
+      Class<?> asyncType) {
+    return new AsyncEndSupport<>(
+        handler, responseType, asyncType, AsyncEndStrategies.instance().resolveStrategy(asyncType));
+  }
+
+  private final AsyncEndHandler<REQUEST, RESPONSE> handler;
+  private final Class<RESPONSE> responseType;
+  private final Class<?> asyncType;
+  @Nullable private final AsyncEndStrategy asyncEndStrategy;
+
+  private AsyncEndSupport(
+      AsyncEndHandler<REQUEST, RESPONSE> handler,
+      Class<RESPONSE> responseType,
+      Class<?> asyncType,
+      @Nullable AsyncEndStrategy asyncEndStrategy) {
+    this.handler = handler;
+    this.responseType = responseType;
+    this.asyncType = asyncType;
+    this.asyncEndStrategy = asyncEndStrategy;
+  }
+
+  /**
+   * Attempts to compose over passed {@code asyncValue} and delay the {@link
+   * Instrumenter#end(Context, Object, Object, Throwable)} call until the async operation completes.
+   *
+   * <p>This method will end the operation immediately if {@code throwable} is passed, if there is
+   * no {@link AsyncEndStrategy} for the {@code asyncType} used, or if there is a type mismatch
+   * between passed {@code asyncValue} and the {@code asyncType} that was used to create this
+   * object.
+   *
+   * <p>If the passed {@code asyncValue} is recognized as an asynchronous computation, the operation
+   * won't be {@link Instrumenter#end(Context, Object, Object, Throwable) ended} until {@code
+   * asyncValue} completes.
+   */
+  @SuppressWarnings("unchecked")
+  @Nullable
+  public <ASYNC> ASYNC asyncEnd(
+      Context context, REQUEST request, @Nullable ASYNC asyncValue, @Nullable Throwable throwable) {
+    // we can end early if an exception was thrown
+    if (throwable != null) {
+      handler.handle(context, request, null, throwable);
+      return asyncValue;
+    }
+
+    // use the configured strategy to compose over the asyncValue
+    if (asyncEndStrategy != null && asyncType.isInstance(asyncValue)) {
+      return (ASYNC) asyncEndStrategy.end(handler, context, request, asyncValue, responseType);
+    }
+
+    // fall back to sync end() if asyncValue type doesn't match
+    handler.handle(context, request, tryToGetResponse(responseType, asyncValue), null);
+    return asyncValue;
+  }
+
+  @Nullable
+  public static <RESPONSE> RESPONSE tryToGetResponse(
+      Class<RESPONSE> responseType, @Nullable Object asyncValue) {
+    if (responseType.isInstance(asyncValue)) {
+      return responseType.cast(asyncValue);
+    }
+    return null;
+  }
+}