Merge pull request #33 from opentracing/bhs/format_type

introduce a Format type in Java

opentracing-api/src/main/java/io/opentracing/Span.java

@@ -50,19 +50,19 @@ public interface Span extends AutoCloseable {
 
     /**
      * Add a new log event to the Span, accepting an event name string and an optional structured payload argument.
-     * If specified, the payload argument may be of any type and arbitrary size,
-     * though implementations are not required to retain all payload arguments
-     * (or even all parts of all payload arguments).
+     *
+     * If specified, the payload argument may be of any type and arbitrary size, though implementations are not
+     * required to retain all payload arguments (or even all parts of all payload arguments).
      *
      * The timestamp of this log event is the current time.
      **/
     Span log(String eventName, /* @Nullable */ Object payload);
 
     /**
      * Add a new log event to the Span, accepting an event name string and an optional structured payload argument.
-     * If specified, the payload argument may be of any type and arbitrary size,
-     * though implementations are not required to retain all payload arguments
-     * (or even all parts of all payload arguments).
+     *
+     * If specified, the payload argument may be of any type and arbitrary size, though implementations are not
+     * required to retain all payload arguments (or even all parts of all payload arguments).
      *
      * The timestamp is specified manually here to represent a past log event.
      * The timestamp in microseconds in UTC time.

opentracing-api/src/main/java/io/opentracing/SpanContext.java

@@ -16,17 +16,22 @@
 /**
  * SpanContext represents Span state that must propagate to descendant Spans and across process boundaries.
  *
- * SpanContext is logically divided into two pieces: (1) the user-level "Baggage" (see set_baggage_item and get_baggage_item) that propagates across Span boundaries and (2) any Tracer-implementation-specific fields that are needed to identify or otherwise contextualize the associated Span instance (e.g., a <trace_id, span_id, sampled> tuple).
+ * SpanContext is logically divided into two pieces: (1) the user-level "Baggage" (see set_baggage_item and
+ * get_baggage_item) that propagates across Span boundaries and (2) any Tracer-implementation-specific fields that are
+ * needed to identify or otherwise contextualize the associated Span instance (e.g., a <trace_id, span_id, sampled>
+ * tuple).
  */
 public interface SpanContext {
     /**
      * Sets a baggage item in the SpanContext as a key/value pair.
      *
-     * Baggage enables powerful distributed context propagation functionality where arbitrary application data can be carried along the full path of request execution throughout the system.
+     * Baggage enables powerful distributed context propagation functionality where arbitrary application data can be
+     * carried along the full path of request execution throughout the system.
      *
      * Note 1: Baggage is only propagated to the future (recursive) children of this SpanContext.
      *
-     * Note 2: Baggage is sent in-band with every subsequent local and remote calls, so this feature must be used with care.
+     * Note 2: Baggage is sent in-band with every subsequent local and remote calls, so this feature must be used with
+     * care.
      *
      * @return this SpanContext instance, for chaining
      */

opentracing-api/src/main/java/io/opentracing/Tracer.java

@@ -13,6 +13,7 @@
  */
 package io.opentracing;
 
+import io.opentracing.propagation.Format;
 
 /**
  * Tracer is a simple, thin interface for Span creation and propagation across arbitrary transports.
@@ -45,36 +46,44 @@ public interface Tracer {
    * <pre>{@code
    * Tracer tracer = ...
    * Span clientSpan = ...
-   * HttpHeaderWriter httpHeaderWriter = new AnHttpHeaderCarrier(httpRequest);
-   * tracer.inject(span.context(), httpHeaderWriter);
+   * TextMap httpHeadersCarrier = new AnHttpHeaderCarrier(httpRequest);
+   * tracer.inject(span.context(), Format.Builtin.HTTP_HEADERS, httpHeadersCarrier);
    * }</pre>
    *
+   * @param <C> the carrier type, which also parametrizes the Format.
    * @param spanContext the SpanContext instance to inject into the carrier
-   * @param carrier the carrier for the SpanContext state; when inject() returns, the Tracer implementation will have represented the SpanContext within `carrier`. All Tracer.inject() implementations must support io.opentracing.propagation.TextMapWriter, io.opentracing.propagation.HttpHeaderWriter, and java.nio.ByteBuffer.
+   * @param format the Format of the carrier
+   * @param carrier the carrier for the SpanContext state. All Tracer.inject() implementations must support io.opentracing.propagation.TextMap and java.nio.ByteBuffer.
    *
-   * @see io.opentracing.propagation
+   * @see io.opentracing.propagation.Format
+   * @see io.opentracing.propagation.Format.Builtin
    */
-  void inject(SpanContext spanContext, Object carrier);
+  <C> void inject(SpanContext spanContext, Format<C> format, C carrier);
 
   /**
    * Extract a SpanContext from a `carrier` of a given type, presumably after propagation across a process boundary.
    *
    * <p>Example:
    * <pre>{@code
    * Tracer tracer = ...
-   * HttpHeaderReader httpHeaderReader = new AnHttpHeaderCarrier(httpRequest);
-   * SpanContext spanCtx = tracer.extract(httpHeaderReader);
+   * TextMap httpHeadersCarrier = new AnHttpHeaderCarrier(httpRequest);
+   * SpanContext spanCtx = tracer.extract(Format.Builtin.HTTP_HEADERS, httpHeadersCarrier);
    * tracer.buildSpan('...').withChildOf(spanCtx).start();
    * }</pre>
    *
-   * If the span serialized state is invalid (corrupt, wrong version, etc) inside the carrier this will result in an IllegalArgumentException.
+   * If the span serialized state is invalid (corrupt, wrong version, etc) inside the carrier this will result in an
+   * IllegalArgumentException.
    *
-   * @param carrier the carrier for the SpanContext state. All Tracer.extract() implementations must support io.opentracing.propagation.TextMapReader, io.opentracing.propagation.HttpHeaderReader, and java.nio.ByteBuffer.
+   * @param <C> the carrier type, which also parametrizes the Format.
+   * @param format the Format of the carrier
+   * @param carrier the carrier for the SpanContext state. All Tracer.extract() implementations must support
+   *                io.opentracing.propagation.TextMap and java.nio.ByteBuffer.
    * @returns the SpanContext instance extracted from the carrier
    *
-   * @see io.opentracing.propagation
+   * @see io.opentracing.propagation.Format
+   * @see io.opentracing.propagation.Format.Builtin
    */
-  SpanContext extract(Object carrier);
+  <C> SpanContext extract(Format<C> format, C carrier);
 
 
   interface SpanBuilder {
@@ -90,10 +99,12 @@ interface SpanBuilder {
       SpanBuilder asChildOf(Span parent);
 
       /**
-       * Add a reference from the Span being built to a distinct (usually parent) Span. May be called multiple times to represent multiple such References.
+       * Add a reference from the Span being built to a distinct (usually parent) Span. May be called multiple times to
+       * represent multiple such References.
        *
        * @param referenceType the reference type, typically one of the constants defined in References
-       * @param referencedContext the SpanContext being referenced; e.g., for a References.CHILD_OF referenceType, the referencedContext is the parent
+       * @param referencedContext the SpanContext being referenced; e.g., for a References.CHILD_OF referenceType, the
+       *                          referencedContext is the parent
        *
        * @see io.opentracing.References
        */

opentracing-api/src/main/java/io/opentracing/propagation/Format.java

@@ -0,0 +1,75 @@
+/**
+ * Copyright 2016 The OpenTracing Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License
+ * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+ * or implied. See the License for the specific language governing permissions and limitations under
+ * the License.
+ */
+package io.opentracing.propagation;
+
+import io.opentracing.SpanContext;
+import io.opentracing.Tracer;
+
+import java.nio.ByteBuffer;
+
+/**
+ * Format instances control the behavior of Tracer.inject and Tracer.extract (and also constrain the type of the
+ * carrier parameter to same).
+ *
+ * Most OpenTracing users will only reference the Format.Builtin constants. For example:
+ *
+ * <pre>{@code
+ * Tracer tracer = ...
+ * io.opentracing.propagation.HttpHeaders httpCarrier = new AnHttpHeaderCarrier(httpRequest);
+ * SpanContext spanCtx = tracer.extract(Format.Builtin.HTTP_HEADERS, httpHeaderReader);
+ * }</pre>
+ *
+ * @see Tracer#inject(SpanContext, Format, Object)
+ * @see Tracer#extract(Format, Object)
+ */
+public interface Format<C> {
+    class Builtin<C> implements Format<C> {
+        /**
+         * The TEXT_MAP format allows for arbitrary String->String map encoding of SpanContext state for Tracer.inject
+         * and Tracer.extract.
+         *
+         * Unlike HTTP_HEADERS, the builtin TEXT_MAP format expresses no constraints on keys or values.
+         *
+         * @see io.opentracing.Tracer#inject(SpanContext, Format, Object)
+         * @see io.opentracing.Tracer#extract(Format, Object)
+         * @see Format
+         * @see Builtin#HTTP_HEADERS
+         */
+        public final static Format<TextMap> TEXT_MAP = new Builtin<>();
+
+        /**
+         * The HTTP_HEADERS format allows for HTTP-header-compatible String->String map encoding of SpanContext state
+         * for Tracer.inject and Tracer.extract.
+         *
+         * I.e., keys written to the TextMap MUST be suitable for HTTP header keys (which are poorly defined but
+         * certainly restricted); and similarly for values (i.e., URL-escaped and "not too long").
+         *
+         * @see io.opentracing.Tracer#inject(SpanContext, Format, Object)
+         * @see io.opentracing.Tracer#extract(Format, Object)
+         * @see Format
+         * @see Builtin#TEXT_MAP
+         */
+        public final static Format<TextMap> HTTP_HEADERS = new Builtin<>();
+
+        /**
+         * The BINARY format allows for unconstrained binary encoding of SpanContext state for Tracer.inject and
+         * Tracer.extract.
+         *
+         * @see io.opentracing.Tracer#inject(SpanContext, Format, Object)
+         * @see io.opentracing.Tracer#extract(Format, Object)
+         * @see Format
+         */
+        public final static Format<ByteBuffer> BINARY = new Builtin<>();
+    }
+}

opentracing-api/src/main/java/io/opentracing/propagation/TextMap.java

@@ -0,0 +1,52 @@
+/**
+ * Copyright 2016 The OpenTracing Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License
+ * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+ * or implied. See the License for the specific language governing permissions and limitations under
+ * the License.
+ */
+package io.opentracing.propagation;
+
+import io.opentracing.SpanContext;
+
+import java.util.Iterator;
+import java.util.Map;
+
+/**
+ * TextMap is a built-in carrier for Tracer.inject() and Tracer.extract(). TextMap implementations allows Tracers to
+ * read and write key:value String pairs from arbitrary underlying sources of data.
+ *
+ * @see io.opentracing.Tracer#inject(SpanContext, Format, Object)
+ * @see io.opentracing.Tracer#extract(Format, Object)
+ */
+public interface TextMap {
+    /**
+     * Gets an iterator over arbitrary key:value pairs from the TextMapReader.
+     *
+     * @return entries in the TextMap backing store; note that for some Formats, the iterator may include entries that
+     * were never injected by a Tracer implementation (e.g., unrelated HTTP headers)
+     *
+     * @see io.opentracing.Tracer#extract(Format, Object)
+     * @see Format.Builtin#TEXT_MAP
+     * @see Format.Builtin#HTTP_HEADERS
+     */
+    Iterator<Map.Entry<String,String>> getEntries();
+
+    /**
+     * Puts a key:value pair into the TextMapWriter's backing store.
+     *
+     * @param key a String, possibly with constraints dictated by the particular Format this TextMap is paired with
+     * @param value a String, possibly with constraints dictated by the particular Format this TextMap is paired with
+     *
+     * @see io.opentracing.Tracer#inject(io.opentracing.SpanContext, Format, Object)
+     * @see Format.Builtin#TEXT_MAP
+     * @see Format.Builtin#HTTP_HEADERS
+     */
+    void put(String key, String value);
+}

opentracing-impl/src/main/java/io/opentracing/propagation/TextMapImpl.java → opentracing-api/src/main/java/io/opentracing/propagation/TextMapExtractAdapter.java

@@ -13,25 +13,34 @@
  */
 package io.opentracing.propagation;
 
+import io.opentracing.Tracer;
+
 import java.util.Iterator;
 import java.util.Map;
 
-public final class TextMapImpl implements TextMapWriter, TextMapReader {
-
+/**
+ * A TextMap carrier for use with Tracer.extract() ONLY (it has no mutating methods).
+ *
+ * Note that the TextMap interface can be made to wrap around arbitrary data types (not just Map<String, String> as
+ * illustrated here).
+ *
+ * @see Tracer#extract(Format, Object)
+ */
+public class TextMapExtractAdapter implements TextMap {
     private final Map<String,String> map;
 
-    public TextMapImpl(final Map<String,String> map) {
+    public TextMapExtractAdapter(final Map<String,String> map) {
         this.map = map;
     }
 
-    @Override
-    public void put(String key, String value) {
-        map.put(key, value);
-    }
-
     @Override
     public Iterator<Map.Entry<String, String>> getEntries() {
         return map.entrySet().iterator();
     }
 
+    @Override
+    public void put(String key, String value) {
+        throw new UnsupportedOperationException(
+                "TextMapInjectAdapter should only be used with Tracer.extract()");
+    }
 }