Refactor http, grpc senders and promote to public API

docs/apidiffs/current_vs_latest/opentelemetry-exporter-common.txt

@@ -1,2 +1,120 @@
 Comparing source compatibility of opentelemetry-exporter-common-1.56.0-SNAPSHOT.jar against opentelemetry-exporter-common-1.55.0.jar
-No changes.
++++  NEW INTERFACE: PUBLIC(+) ABSTRACT(+) io.opentelemetry.exporter.compressor.Compressor  (not serializable)
+	+++  CLASS FILE FORMAT VERSION: 52.0 <- n.a.
+	+++  NEW SUPERCLASS: java.lang.Object
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) java.io.OutputStream compress(java.io.OutputStream)
+		+++  NEW EXCEPTION: java.io.IOException
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) java.lang.String getEncoding()
++++  NEW INTERFACE: PUBLIC(+) ABSTRACT(+) io.opentelemetry.exporter.compressor.CompressorProvider  (not serializable)
+	+++  CLASS FILE FORMAT VERSION: 52.0 <- n.a.
+	+++  NEW SUPERCLASS: java.lang.Object
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) io.opentelemetry.exporter.compressor.Compressor getInstance()
++++  NEW INTERFACE: PUBLIC(+) ABSTRACT(+) io.opentelemetry.exporter.grpc.GrpcMessageWriter  (not serializable)
+	+++  CLASS FILE FORMAT VERSION: 52.0 <- n.a.
+	+++  NEW SUPERCLASS: java.lang.Object
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) int contentLength()
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) void writeMessage(java.io.OutputStream)
+		+++  NEW EXCEPTION: java.io.IOException
++++  NEW INTERFACE: PUBLIC(+) ABSTRACT(+) io.opentelemetry.exporter.grpc.GrpcResponse  (not serializable)
+	+++  CLASS FILE FORMAT VERSION: 52.0 <- n.a.
+	+++  NEW SUPERCLASS: java.lang.Object
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) byte[] getResponseMessage()
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) io.opentelemetry.exporter.grpc.GrpcStatusCode getStatusCode()
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) java.lang.String getStatusDescription()
+		+++  NEW ANNOTATION: javax.annotation.Nullable
++++  NEW INTERFACE: PUBLIC(+) ABSTRACT(+) io.opentelemetry.exporter.grpc.GrpcSender  (not serializable)
+	+++  CLASS FILE FORMAT VERSION: 52.0 <- n.a.
+	+++  NEW SUPERCLASS: java.lang.Object
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) void send(io.opentelemetry.exporter.grpc.GrpcMessageWriter, java.util.function.Consumer<io.opentelemetry.exporter.grpc.GrpcResponse>, java.util.function.Consumer<java.lang.Throwable>)
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) io.opentelemetry.sdk.common.CompletableResultCode shutdown()
++++  NEW INTERFACE: PUBLIC(+) ABSTRACT(+) io.opentelemetry.exporter.grpc.GrpcSenderConfig  (not serializable)
+	+++  CLASS FILE FORMAT VERSION: 52.0 <- n.a.
+	+++  NEW SUPERCLASS: java.lang.Object
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) io.opentelemetry.exporter.compressor.Compressor getCompressor()
+		+++  NEW ANNOTATION: javax.annotation.Nullable
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) long getConnectTimeoutNanos()
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) java.net.URI getEndpoint()
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) java.util.concurrent.ExecutorService getExecutorService()
+		+++  NEW ANNOTATION: javax.annotation.Nullable
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) java.lang.String getFullServiceName()
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) java.util.function.Supplier<java.util.Map<java.lang.String,java.util.List<java.lang.String>>> getHeadersSupplier()
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) java.lang.String getMethodName()
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) io.opentelemetry.sdk.common.export.RetryPolicy getRetryPolicy()
+		+++  NEW ANNOTATION: javax.annotation.Nullable
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) javax.net.ssl.SSLContext getSslContext()
+		+++  NEW ANNOTATION: javax.annotation.Nullable
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) long getTimeoutNanos()
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) javax.net.ssl.X509TrustManager getTrustManager()
+		+++  NEW ANNOTATION: javax.annotation.Nullable
++++  NEW INTERFACE: PUBLIC(+) ABSTRACT(+) io.opentelemetry.exporter.grpc.GrpcSenderProvider  (not serializable)
+	+++  CLASS FILE FORMAT VERSION: 52.0 <- n.a.
+	+++  NEW SUPERCLASS: java.lang.Object
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) io.opentelemetry.exporter.grpc.GrpcSender createSender(io.opentelemetry.exporter.grpc.GrpcSenderConfig)
++++  NEW ENUM: PUBLIC(+) FINAL(+) io.opentelemetry.exporter.grpc.GrpcStatusCode  (compatible)
+	+++  CLASS FILE FORMAT VERSION: 52.0 <- n.a.
+	+++  NEW INTERFACE: java.lang.constant.Constable
+	+++  NEW INTERFACE: java.lang.Comparable
+	+++  NEW INTERFACE: java.io.Serializable
+	+++  NEW SUPERCLASS: java.lang.Enum
+	+++  NEW FIELD: PUBLIC(+) STATIC(+) FINAL(+) io.opentelemetry.exporter.grpc.GrpcStatusCode RESOURCE_EXHAUSTED
+	+++  NEW FIELD: PUBLIC(+) STATIC(+) FINAL(+) io.opentelemetry.exporter.grpc.GrpcStatusCode ALREADY_EXISTS
+	+++  NEW FIELD: PUBLIC(+) STATIC(+) FINAL(+) io.opentelemetry.exporter.grpc.GrpcStatusCode UNIMPLEMENTED
+	+++  NEW FIELD: PUBLIC(+) STATIC(+) FINAL(+) io.opentelemetry.exporter.grpc.GrpcStatusCode FAILED_PRECONDITION
+	+++  NEW FIELD: PUBLIC(+) STATIC(+) FINAL(+) io.opentelemetry.exporter.grpc.GrpcStatusCode NOT_FOUND
+	+++  NEW FIELD: PUBLIC(+) STATIC(+) FINAL(+) io.opentelemetry.exporter.grpc.GrpcStatusCode DEADLINE_EXCEEDED
+	+++  NEW FIELD: PUBLIC(+) STATIC(+) FINAL(+) io.opentelemetry.exporter.grpc.GrpcStatusCode OUT_OF_RANGE
+	+++  NEW FIELD: PUBLIC(+) STATIC(+) FINAL(+) io.opentelemetry.exporter.grpc.GrpcStatusCode UNAUTHENTICATED
+	+++  NEW FIELD: PUBLIC(+) STATIC(+) FINAL(+) io.opentelemetry.exporter.grpc.GrpcStatusCode CANCELLED
+	+++  NEW FIELD: PUBLIC(+) STATIC(+) FINAL(+) io.opentelemetry.exporter.grpc.GrpcStatusCode DATA_LOSS
+	+++  NEW FIELD: PUBLIC(+) STATIC(+) FINAL(+) io.opentelemetry.exporter.grpc.GrpcStatusCode INTERNAL
+	+++  NEW FIELD: PUBLIC(+) STATIC(+) FINAL(+) io.opentelemetry.exporter.grpc.GrpcStatusCode UNAVAILABLE
+	+++  NEW FIELD: PUBLIC(+) STATIC(+) FINAL(+) io.opentelemetry.exporter.grpc.GrpcStatusCode UNKNOWN
+	+++  NEW FIELD: PUBLIC(+) STATIC(+) FINAL(+) io.opentelemetry.exporter.grpc.GrpcStatusCode ABORTED
+	+++  NEW FIELD: PUBLIC(+) STATIC(+) FINAL(+) io.opentelemetry.exporter.grpc.GrpcStatusCode OK
+	+++  NEW FIELD: PUBLIC(+) STATIC(+) FINAL(+) io.opentelemetry.exporter.grpc.GrpcStatusCode INVALID_ARGUMENT
+	+++  NEW FIELD: PUBLIC(+) STATIC(+) FINAL(+) io.opentelemetry.exporter.grpc.GrpcStatusCode PERMISSION_DENIED
+	+++  NEW METHOD: PUBLIC(+) STATIC(+) io.opentelemetry.exporter.grpc.GrpcStatusCode fromValue(int)
+	+++  NEW METHOD: PUBLIC(+) int getValue()
+	+++  NEW METHOD: PUBLIC(+) STATIC(+) io.opentelemetry.exporter.grpc.GrpcStatusCode valueOf(java.lang.String)
+	+++  NEW METHOD: PUBLIC(+) STATIC(+) io.opentelemetry.exporter.grpc.GrpcStatusCode[] values()
++++  NEW INTERFACE: PUBLIC(+) ABSTRACT(+) io.opentelemetry.exporter.http.HttpRequestBodyWriter  (not serializable)
+	+++  CLASS FILE FORMAT VERSION: 52.0 <- n.a.
+	+++  NEW SUPERCLASS: java.lang.Object
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) int contentLength()
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) void writeRequestBody(java.io.OutputStream)
+		+++  NEW EXCEPTION: java.io.IOException
++++  NEW INTERFACE: PUBLIC(+) ABSTRACT(+) io.opentelemetry.exporter.http.HttpResponse  (not serializable)
+	+++  CLASS FILE FORMAT VERSION: 52.0 <- n.a.
+	+++  NEW SUPERCLASS: java.lang.Object
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) byte[] getResponseBody()
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) int getStatusCode()
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) java.lang.String getStatusMessage()
++++  NEW INTERFACE: PUBLIC(+) ABSTRACT(+) io.opentelemetry.exporter.http.HttpSender  (not serializable)
+	+++  CLASS FILE FORMAT VERSION: 52.0 <- n.a.
+	+++  NEW SUPERCLASS: java.lang.Object
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) void send(io.opentelemetry.exporter.http.HttpRequestBodyWriter, java.util.function.Consumer<io.opentelemetry.exporter.http.HttpResponse>, java.util.function.Consumer<java.lang.Throwable>)
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) io.opentelemetry.sdk.common.CompletableResultCode shutdown()
++++  NEW INTERFACE: PUBLIC(+) ABSTRACT(+) io.opentelemetry.exporter.http.HttpSenderConfig  (not serializable)
+	+++  CLASS FILE FORMAT VERSION: 52.0 <- n.a.
+	+++  NEW SUPERCLASS: java.lang.Object
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) io.opentelemetry.exporter.compressor.Compressor getCompressor()
+		+++  NEW ANNOTATION: javax.annotation.Nullable
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) long getConnectTimeoutNanos()
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) java.lang.String getContentType()
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) java.net.URI getEndpoint()
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) java.util.concurrent.ExecutorService getExecutorService()
+		+++  NEW ANNOTATION: javax.annotation.Nullable
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) java.util.function.Supplier<java.util.Map<java.lang.String,java.util.List<java.lang.String>>> getHeadersSupplier()
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) io.opentelemetry.sdk.common.export.ProxyOptions getProxyOptions()
+		+++  NEW ANNOTATION: javax.annotation.Nullable
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) io.opentelemetry.sdk.common.export.RetryPolicy getRetryPolicy()
+		+++  NEW ANNOTATION: javax.annotation.Nullable
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) javax.net.ssl.SSLContext getSslContext()
+		+++  NEW ANNOTATION: javax.annotation.Nullable
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) long getTimeoutNanos()
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) javax.net.ssl.X509TrustManager getTrustManager()
+		+++  NEW ANNOTATION: javax.annotation.Nullable
++++  NEW INTERFACE: PUBLIC(+) ABSTRACT(+) io.opentelemetry.exporter.http.HttpSenderProvider  (not serializable)
+	+++  CLASS FILE FORMAT VERSION: 52.0 <- n.a.
+	+++  NEW SUPERCLASS: java.lang.Object
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) io.opentelemetry.exporter.http.HttpSender createSender(io.opentelemetry.exporter.http.HttpSenderConfig)

exporters/common/src/main/java/io/opentelemetry/exporter/internal/compression/Compressor.java → exporters/common/src/main/java/io/opentelemetry/exporter/compressor/Compressor.java

@@ -3,7 +3,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-package io.opentelemetry.exporter.internal.compression;
+package io.opentelemetry.exporter.compressor;
 
 import java.io.IOException;
 import java.io.OutputStream;
@@ -13,8 +13,7 @@
  * An abstraction for compressing messages. Implementation MUST be thread safe as the same instance
  * is expected to be used many times and concurrently. Instances are usually singletons.
  *
- * <p>This class is internal and is hence not for public use. Its APIs are unstable and can change
- * at any time.
+ * @see CompressorProvider
  */
 @ThreadSafe
 public interface Compressor {

exporters/common/src/main/java/io/opentelemetry/exporter/compressor/CompressorProvider.java

@@ -0,0 +1,13 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.exporter.compressor;
+
+/** A service provider interface (SPI) for providing {@link Compressor}s. */
+public interface CompressorProvider {
+
+  /** Return the {@link Compressor}. */
+  Compressor getInstance();
+}

exporters/common/src/main/java/io/opentelemetry/exporter/grpc/GrpcMessageWriter.java

@@ -0,0 +1,19 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.exporter.grpc;
+
+import java.io.IOException;
+import java.io.OutputStream;
+
+/** Writes gRPC messages to an {@link OutputStream}. */
+public interface GrpcMessageWriter {
+
+  /** Write the gRPC message bytes to the {@link OutputStream}. */
+  void writeMessage(OutputStream output) throws IOException;
+
+  /** Returns the message length in bytes. */
+  int contentLength();
+}

exporters/common/src/main/java/io/opentelemetry/exporter/grpc/GrpcResponse.java

@@ -0,0 +1,30 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.exporter.grpc;
+
+import java.util.function.Consumer;
+import javax.annotation.Nullable;
+import javax.annotation.concurrent.Immutable;
+
+/**
+ * A gRPC response.
+ *
+ * @see GrpcSender#send(GrpcMessageWriter, Consumer, Consumer)
+ */
+@Immutable
+public interface GrpcResponse {
+
+  /** The response gRPC status code. */
+  GrpcStatusCode getStatusCode();
+
+  /** A string description of the status. */
+  @Nullable
+  String getStatusDescription();
+
+  /** The gRPC response message bytes. */
+  @SuppressWarnings("mutable")
+  byte[] getResponseMessage();
+}

exporters/common/src/main/java/io/opentelemetry/exporter/grpc/GrpcSender.java

@@ -0,0 +1,40 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.exporter.grpc;
+
+import io.opentelemetry.sdk.common.CompletableResultCode;
+import java.util.function.Consumer;
+
+/**
+ * An abstraction for executing gRPC calls, allowing for implementations backed by different client
+ * libraries.
+ *
+ * <p>While this interface is public, implementing a custom sender is generally not recommended. The
+ * {@code opentelemetry-java} project provides built-in implementations that cover virtually all
+ * cases.
+ *
+ * @see GrpcSenderProvider
+ */
+public interface GrpcSender {
+
+  /**
+   * Execute a gRPC unary call, including any retry attempts. {@code onResponse} is called with the
+   * gRPC response, either a success response or an error response after retries. {@code onError} is
+   * called when the call could not be executed due to cancellation, connectivity problems, or
+   * timeout.
+   *
+   * @param messageWriter the message writer
+   * @param onResponse the callback to invoke with the gRPC response
+   * @param onError the callback to invoke when the gRPC call could not be executed
+   */
+  void send(
+      GrpcMessageWriter messageWriter,
+      Consumer<GrpcResponse> onResponse,
+      Consumer<Throwable> onError);
+
+  /** Shutdown the sender. */
+  CompletableResultCode shutdown();
+}

exporters/common/src/main/java/io/opentelemetry/exporter/grpc/GrpcSenderConfig.java

@@ -0,0 +1,93 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.exporter.grpc;
+
+import io.opentelemetry.exporter.compressor.Compressor;
+import io.opentelemetry.sdk.common.export.RetryPolicy;
+import java.io.OutputStream;
+import java.net.URI;
+import java.util.List;
+import java.util.Map;
+import java.util.concurrent.ExecutorService;
+import java.util.function.Consumer;
+import java.util.function.Supplier;
+import javax.annotation.Nullable;
+import javax.annotation.concurrent.Immutable;
+import javax.net.ssl.SSLContext;
+import javax.net.ssl.X509TrustManager;
+
+/**
+ * Configuration for {@link GrpcSender} implementations, provided via {@link
+ * GrpcSenderProvider#createSender(GrpcSenderConfig)}.
+ */
+@Immutable
+public interface GrpcSenderConfig {
+
+  /**
+   * The gRPC endpoint to send to, including scheme. Omits path, which must be constructed from
+   * {@link #getFullServiceName()} and {@link #getMethodName()}.
+   */
+  URI getEndpoint();
+
+  /**
+   * The fully qualified gRPC service name, e.g. {@code
+   * opentelemetry.proto.collector.trace.v1.TraceService}.
+   */
+  String getFullServiceName();
+
+  /** The gRPC method name, e.g. {@code Export}. */
+  String getMethodName();
+
+  /**
+   * The compressor, or {@code null} if no compression is used. If present, {@link
+   * Compressor#compress(OutputStream)} must be applied to {@link
+   * GrpcMessageWriter#writeMessage(OutputStream)} when {@link GrpcSender#send(GrpcMessageWriter,
+   * Consumer, Consumer)} is called and {@link Compressor#getEncoding()} must be set as the {@code
+   * grpc-encoding}.
+   */
+  @Nullable
+  Compressor getCompressor();
+
+  /**
+   * The max time in nanoseconds allowed to send a request, including resolving DNS, connecting,
+   * writing the request, reading the response, and any retries via {@link #getRetryPolicy()}.
+   */
+  long getTimeoutNanos();
+
+  /** The max time in nanoseconds allowed to connect to a target host. */
+  long getConnectTimeoutNanos();
+
+  /**
+   * Additional headers that must be appended to every request. The resulting {@link Supplier} must
+   * be invoked for each request.
+   */
+  Supplier<Map<String, List<String>>> getHeadersSupplier();
+
+  /** The retry policy, or {@code null} if retry is disabled. */
+  @Nullable
+  RetryPolicy getRetryPolicy();
+
+  /**
+   * The SSL context to use, or {@code null} if the system default is used. If non-null, {@link
+   * #getTrustManager()} will also be non-null.
+   */
+  @Nullable
+  SSLContext getSslContext();
+
+  /**
+   * The trust manager to use, or {@code null} if the system default is used. If non-null, {@link
+   * #getSslContext()} will also be non-null.
+   */
+  @Nullable
+  X509TrustManager getTrustManager();
+
+  /**
+   * The executor service used to execute any asynchronous processing, or {@code null} if the sender
+   * default executor service should be used.
+   */
+  @Nullable
+  ExecutorService getExecutorService();
+}

exporters/common/src/main/java/io/opentelemetry/exporter/internal/grpc/GrpcSenderProvider.java → exporters/common/src/main/java/io/opentelemetry/exporter/grpc/GrpcSenderProvider.java

@@ -3,19 +3,14 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-package io.opentelemetry.exporter.internal.grpc;
-
-import io.opentelemetry.exporter.internal.marshal.Marshaler;
+package io.opentelemetry.exporter.grpc;
 
 /**
  * A service provider interface (SPI) for providing {@link GrpcSender}s backed by different client
  * libraries.
- *
- * <p>This class is internal and is hence not for public use. Its APIs are unstable and can change
- * at any time.
  */
 public interface GrpcSenderProvider {
 
   /** Returns a {@link GrpcSender} configured with the provided config. */
-  <T extends Marshaler> GrpcSender<T> createSender(GrpcSenderConfig<T> grpcSenderConfig);
+  GrpcSender createSender(GrpcSenderConfig grpcSenderConfig);
 }