Rename 'HttpTextFormat' to 'TextMapPropagator' (#1586)

* #1581 Rename 'HttpTextFormat' to 'TextMapPropagator' Signed-off-by: Sergei Malafeev <sergei@malafeev.org> * fix long line Signed-off-by: Sergei Malafeev <sergei@malafeev.org> * add change log entry Signed-off-by: Sergei Malafeev <sergei@malafeev.org> * add change log entry Signed-off-by: Sergei Malafeev <sergei@malafeev.org>
open-telemetry · Aug 26, 2020 · 8858220 · 8858220
1 parent 20669f4
commit 8858220
Show file tree

Hide file tree

Showing 33 changed files with 172 additions and 168 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,6 +1,7 @@
 # Changelog
 
 ## Unreleased
+- BREAKING CHANGE: Renamed HttpTextFormat to TextMapPropagator and implementations
 
 ## 0.7.0 - 2020-08-02
 

diff --git a/QUICKSTART.md b/QUICKSTART.md
@@ -178,8 +178,8 @@ The following presents an example of an outgoing HTTP request using `HttpURLConn
 
 ```java
 // Tell OpenTelemetry to inject the context in the HTTP headers
-HttpTextFormat.Setter<HttpURLConnection> setter =
-  new HttpTextFormat.Setter<HttpURLConnection>() {
+TextMapPropagator.Setter<HttpURLConnection> setter =
+  new TextMapPropagator.Setter<HttpURLConnection>() {
     @Override
     public void put(HttpURLConnection carrier, String key, String value) {
         // Insert the context as Header
@@ -196,7 +196,7 @@ try (Scope scope = tracer.withSpan(outGoing)) {
   outGoing.setAttribute("http.url", url.toString());
   HttpURLConnection transportLayer = (HttpURLConnection) url.openConnection();
   // Inject the request with the *current*  Context, which contains our current Span.
-  OpenTelemetry.getPropagators().getHttpTextFormat().inject(Context.current(), transportLayer, setter);
+  OpenTelemetry.getPropagators().getTextMapPropagator().inject(Context.current(), transportLayer, setter);
   // Make outgoing call
 } finally {
   outGoing.end();
@@ -209,8 +209,8 @@ The following presents an example of processing an incoming HTTP request using
 [HttpExchange](https://docs.oracle.com/javase/8/docs/jre/api/net/httpserver/spec/com/sun/net/httpserver/HttpExchange.html).
 
 ```java
-HttpTextFormat.Getter<HttpExchange> getter =
-  new HttpTextFormat.Getter<HttpExchange>() {
+TextMapPropagator.Getter<HttpExchange> getter =
+  new TextMapPropagator.Getter<HttpExchange>() {
     @Override
     public String get(HttpExchange carrier, String key) {
       if (carrier.getRequestHeaders().containsKey(key)) {
@@ -222,7 +222,7 @@ HttpTextFormat.Getter<HttpExchange> getter =
 ...
 public void handle(HttpExchange httpExchange) {
   // Extract the SpanContext and other elements from the request.
-  Context extractedContext = OpenTelemetry.getPropagators().getHttpTextFormat()
+  Context extractedContext = OpenTelemetry.getPropagators().getTextMapPropagator()
         .extract(Context.current(), httpExchange, getter);
   Span serverSpan = null;
   try (Scope scope = ContextUtils.withScopedContext(extractedContext)) {

diff --git a/api/src/jmh/java/io/opentelemetry/trace/propagation/HttpTraceContextExtractBenchmark.java b/api/src/jmh/java/io/opentelemetry/trace/propagation/HttpTraceContextExtractBenchmark.java
@@ -17,7 +17,7 @@
 package io.opentelemetry.trace.propagation;
 
 import io.grpc.Context;
-import io.opentelemetry.context.propagation.HttpTextFormat.Getter;
+import io.opentelemetry.context.propagation.TextMapPropagator.Getter;
 import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.HashMap;

diff --git a/api/src/jmh/java/io/opentelemetry/trace/propagation/HttpTraceContextInjectBenchmark.java b/api/src/jmh/java/io/opentelemetry/trace/propagation/HttpTraceContextInjectBenchmark.java
@@ -17,7 +17,7 @@
 package io.opentelemetry.trace.propagation;
 
 import io.grpc.Context;
-import io.opentelemetry.context.propagation.HttpTextFormat.Setter;
+import io.opentelemetry.context.propagation.TextMapPropagator.Setter;
 import io.opentelemetry.trace.DefaultSpan;
 import io.opentelemetry.trace.SpanContext;
 import io.opentelemetry.trace.SpanId;

diff --git a/api/src/main/java/io/opentelemetry/OpenTelemetry.java b/api/src/main/java/io/opentelemetry/OpenTelemetry.java
@@ -57,7 +57,7 @@ public final class OpenTelemetry {
   private final CorrelationContextManager contextManager;
 
   private volatile ContextPropagators propagators =
-      DefaultContextPropagators.builder().addHttpTextFormat(new HttpTraceContext()).build();
+      DefaultContextPropagators.builder().addTextMapPropagator(new HttpTraceContext()).build();
 
   /**
    * Returns a singleton {@link TracerProvider}.

diff --git a/api/src/main/java/io/opentelemetry/trace/propagation/HttpTraceContext.java b/api/src/main/java/io/opentelemetry/trace/propagation/HttpTraceContext.java
@@ -20,7 +20,7 @@
 import static io.opentelemetry.internal.Utils.checkNotNull;
 
 import io.grpc.Context;
-import io.opentelemetry.context.propagation.HttpTextFormat;
+import io.opentelemetry.context.propagation.TextMapPropagator;
 import io.opentelemetry.internal.TemporaryBuffers;
 import io.opentelemetry.trace.DefaultSpan;
 import io.opentelemetry.trace.Span;
@@ -42,7 +42,7 @@
  * href=https://github.com/w3c/distributed-tracing>w3c/distributed-tracing</a>.
  */
 @Immutable
-public class HttpTraceContext implements HttpTextFormat {
+public class HttpTraceContext implements TextMapPropagator {
   private static final Logger logger = Logger.getLogger(HttpTraceContext.class.getName());
 
   private static final TraceState TRACE_STATE_DEFAULT = TraceState.builder().build();

diff --git a/api/src/test/java/io/opentelemetry/trace/propagation/HttpTraceContextTest.java b/api/src/test/java/io/opentelemetry/trace/propagation/HttpTraceContextTest.java
@@ -22,8 +22,8 @@
 import static org.assertj.core.api.Assertions.entry;
 
 import io.grpc.Context;
-import io.opentelemetry.context.propagation.HttpTextFormat.Getter;
-import io.opentelemetry.context.propagation.HttpTextFormat.Setter;
+import io.opentelemetry.context.propagation.TextMapPropagator.Getter;
+import io.opentelemetry.context.propagation.TextMapPropagator.Setter;
 import io.opentelemetry.trace.DefaultSpan;
 import io.opentelemetry.trace.SpanContext;
 import io.opentelemetry.trace.SpanId;

diff --git a/context_prop/src/main/java/io/opentelemetry/context/propagation/ContextPropagators.java b/context_prop/src/main/java/io/opentelemetry/context/propagation/ContextPropagators.java
@@ -34,12 +34,12 @@
  * void onSendRequest() {
  *   try (Scope scope = tracer.withSpan(span)) {
  *     ContextPropagators propagators = OpenTelemetry.getPropagators();
- *     HttpTextFormat textFormat = propagators.getHttpTextFormat();
+ *     TextMapPropagator textMapPropagator = propagators.getTextMapPropagator();
  *
  *     // Inject the span's SpanContext and other available concerns (such as correlations)
  *     // contained in the specified Context.
  *     Map<String, String> map = new HashMap<>();
- *     httpTextFormat.inject(Context.current(), map, new Setter<String, String>() {
+ *     textMapPropagator.inject(Context.current(), map, new Setter<String, String>() {
  *       public void put(Map<String, String> map, String key, String value) {
  *         map.put(key, value);
  *       }
@@ -55,15 +55,17 @@
  * private static final Tracer tracer = OpenTelemetry.getTracer();
  * void onRequestReceived() {
  *   ContextPropagators propagators = OpenTelemetry.getPropagators();
- *   HttpTextFormat textFormat = propagators.getHttpTextFormat();
+ *   TextMapPropagator textMapPropagator = propagators.getTextMapPropagator();
  *
  *   // Extract and store the propagated span's SpanContext and other available concerns
  *   // in the specified Context.
- *   Context context = textFormat.extract(Context.current(), request, new Getter<String, String>() {
- *     public String get(Object request, String key) {
- *       // Return the value associated to the key, if available.
+ *   Context context = textMapPropagator.extract(Context.current(), request,
+ *     new Getter<String, String>() {
+ *       public String get(Object request, String key) {
+ *         // Return the value associated to the key, if available.
+ *       }
  *     }
- *   });
+ *   );
  *   Span span = tracer.spanBuilder("MyRequest")
  *       .setParent(context)
  *       .setSpanKind(Span.Kind.SERVER).startSpan();
@@ -81,14 +83,14 @@
 public interface ContextPropagators {
 
   /**
-   * Returns a {@link HttpTextFormat} propagator.
+   * Returns a {@link TextMapPropagator} propagator.
    *
    * <p>The returned value will be a composite instance containing all the registered {@link
-   * HttpTextFormat} propagators. If none is registered, the returned value will be a no-op
+   * TextMapPropagator} propagators. If none is registered, the returned value will be a no-op
    * instance.
    *
-   * @return the {@link HttpTextFormat} propagator to inject and extract data.
+   * @return the {@link TextMapPropagator} propagator to inject and extract data.
    * @since 0.3.0
    */
-  HttpTextFormat getHttpTextFormat();
+  TextMapPropagator getTextMapPropagator();
 }
diff --git a/...xt_prop/src/main/java/io/opentelemetry/context/propagation/DefaultContextPropagators.java b/...xt_prop/src/main/java/io/opentelemetry/context/propagation/DefaultContextPropagators.java
@@ -31,11 +31,11 @@
  * @since 0.3.0
  */
 public final class DefaultContextPropagators implements ContextPropagators {
-  private final HttpTextFormat textFormat;
+  private final TextMapPropagator textMapPropagator;
 
   @Override
-  public HttpTextFormat getHttpTextFormat() {
-    return textFormat;
+  public TextMapPropagator getTextMapPropagator() {
+    return textMapPropagator;
   }
 
   /**
@@ -49,8 +49,8 @@ public static Builder builder() {
     return new Builder();
   }
 
-  private DefaultContextPropagators(HttpTextFormat textFormat) {
-    this.textFormat = textFormat;
+  private DefaultContextPropagators(TextMapPropagator textMapPropagator) {
+    this.textMapPropagator = textMapPropagator;
   }
 
   /**
@@ -61,34 +61,34 @@ private DefaultContextPropagators(HttpTextFormat textFormat) {
    *
    * <pre>{@code
    * ContextPropagators propagators = DefaultContextPropagators.builder()
-   *     .addHttpTextFormat(new HttpTraceContext())
-   *     .addHttpTextFormat(new HttpCorrelationContext())
-   *     .addHttpTextFormat(new MyCustomContextPropagator())
+   *     .addTextMapPropagator(new HttpTraceContext())
+   *     .addTextMapPropagator(new HttpCorrelationContext())
+   *     .addTextMapPropagator(new MyCustomContextPropagator())
    *     .build();
    * }</pre>
    *
    * @since 0.3.0
    */
   public static final class Builder {
-    List<HttpTextFormat> textPropagators = new ArrayList<>();
+    List<TextMapPropagator> textPropagators = new ArrayList<>();
 
     /**
-     * Adds a {@link HttpTextFormat} propagator.
+     * Adds a {@link TextMapPropagator} propagator.
      *
      * <p>One propagator per concern (traces, correlations, etc) should be added if this format is
      * supported.
      *
-     * @param textFormat the propagator to be added.
+     * @param textMapPropagator the propagator to be added.
      * @return this.
-     * @throws NullPointerException if {@code textFormat} is {@code null}.
+     * @throws NullPointerException if {@code textMapPropagator} is {@code null}.
      * @since 0.3.0
      */
-    public Builder addHttpTextFormat(HttpTextFormat textFormat) {
-      if (textFormat == null) {
-        throw new NullPointerException("textFormat");
+    public Builder addTextMapPropagator(TextMapPropagator textMapPropagator) {
+      if (textMapPropagator == null) {
+        throw new NullPointerException("textMapPropagator");
       }
 
-      textPropagators.add(textFormat);
+      textPropagators.add(textMapPropagator);
       return this;
     }
 
@@ -100,19 +100,19 @@ public Builder addHttpTextFormat(HttpTextFormat textFormat) {
      */
     public ContextPropagators build() {
       if (textPropagators.isEmpty()) {
-        return new DefaultContextPropagators(NoopHttpTextFormat.INSTANCE);
+        return new DefaultContextPropagators(NoopTextMapPropagator.INSTANCE);
       }
 
-      return new DefaultContextPropagators(new MultiHttpTextFormat(textPropagators));
+      return new DefaultContextPropagators(new MultiTextMapPropagator(textPropagators));
     }
   }
 
-  private static final class MultiHttpTextFormat implements HttpTextFormat {
-    private final HttpTextFormat[] textPropagators;
+  private static final class MultiTextMapPropagator implements TextMapPropagator {
+    private final TextMapPropagator[] textPropagators;
     private final List<String> allFields;
 
-    private MultiHttpTextFormat(List<HttpTextFormat> textPropagators) {
-      this.textPropagators = new HttpTextFormat[textPropagators.size()];
+    private MultiTextMapPropagator(List<TextMapPropagator> textPropagators) {
+      this.textPropagators = new TextMapPropagator[textPropagators.size()];
       textPropagators.toArray(this.textPropagators);
       this.allFields = getAllFields(this.textPropagators);
     }
@@ -122,7 +122,7 @@ public List<String> fields() {
       return allFields;
     }
 
-    private static List<String> getAllFields(HttpTextFormat[] textPropagators) {
+    private static List<String> getAllFields(TextMapPropagator[] textPropagators) {
       List<String> fields = new ArrayList<>();
       for (int i = 0; i < textPropagators.length; i++) {
         fields.addAll(textPropagators[i].fields());
@@ -147,8 +147,8 @@ public <C> Context extract(Context context, C carrier, Getter<C> getter) {
     }
   }
 
-  private static final class NoopHttpTextFormat implements HttpTextFormat {
-    private static final NoopHttpTextFormat INSTANCE = new NoopHttpTextFormat();
+  private static final class NoopTextMapPropagator implements TextMapPropagator {
+    private static final NoopTextMapPropagator INSTANCE = new NoopTextMapPropagator();
 
     @Override
     public List<String> fields() {

diff --git a/...y/context/propagation/HttpTextFormat.java → ...ontext/propagation/TextMapPropagator.java b/...y/context/propagation/HttpTextFormat.java → ...ontext/propagation/TextMapPropagator.java
@@ -36,7 +36,7 @@
  *
  * <pre>{@code
  * public static final Context.Key CONCERN_KEY = Context.key("my-concern-key");
- * public MyConcernPropagator implements HttpTextFormat {
+ * public MyConcernPropagator implements TextMapPropagator {
  *   public <C> void inject(Context context, C carrier, Setter<C> setter) {
  *     Object concern = CONCERN_KEY.get(context);
  *     // Use concern in the specified context to propagate data.
@@ -51,7 +51,7 @@
  * @since 0.1.0
  */
 @ThreadSafe
-public interface HttpTextFormat {
+public interface TextMapPropagator {
   /**
    * The propagation fields defined. If your carrier is reused, you should delete the fields here
    * before calling {@link #inject(Context, Object, Setter)} )}.
@@ -82,7 +82,7 @@ public interface HttpTextFormat {
   <C> void inject(Context context, @Nullable C carrier, Setter<C> setter);
 
   /**
-   * Class that allows a {@code HttpTextFormat} to set propagated fields into a carrier.
+   * Class that allows a {@code TextMapPropagator} to set propagated fields into a carrier.
    *
    * <p>{@code Setter} is stateless and allows to be saved as a constant to avoid runtime
    * allocations.
@@ -124,7 +124,7 @@ interface Setter<C> {
   <C> Context extract(Context context, C carrier, Getter<C> getter);
 
   /**
-   * Interface that allows a {@code HttpTextFormat} to read propagated fields from a carrier.
+   * Interface that allows a {@code TextMapPropagator} to read propagated fields from a carrier.
    *
    * <p>{@code Getter} is stateless and allows to be saved as a constant to avoid runtime
    * allocations.