Split Inject and Extract Builtin interfaces (#316)

If we had separate formats for inject and extract this refactor would have been much cleaner.

This allows us to better avoid partially implementing the TextMap interface and throwing an exception for the other method.

Since Binary is a new addition, I applied a similar refactoring to that.

Closes #315.

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

@@ -13,6 +13,7 @@
  */
 package io.opentracing.propagation;
 
+import io.opentracing.SpanContext;
 import java.nio.ByteBuffer;
 
 /**
@@ -31,31 +32,5 @@
  * @see io.opentracing.Tracer#inject(SpanContext, Format, Object)
  * @see io.opentracing.Tracer#extract(Format, Object)
  */
-public interface Binary {
-    /**
-     * Gets the buffer used to store data as part of {@link SpanContext} injection.
-     *
-     * The lenght parameter hints the buffer length required for
-     * {@link SpanContext} injection. The user may use this to allocate a new
-     * ByteBuffer or resize an existing one.
-     *
-     * It is an error to call this method when Binary is used
-     * for {@link SpanContext} extraction.
-     *
-     * @param length The buffer length required for {@link SpanContext} injection.
-     *               It needs to be larger than zero.
-     *
-     * @return The buffer used for {@link SpanContext} injection.
-     */
-    ByteBuffer injectionBuffer(int lenght);
-
-    /**
-     * Gets the buffer containing the data used for {@link SpanContext} extraction.
-     *
-     * It is an error to call this method when Binary is used
-     * for {@link SpanContext} injection.
-     *
-     * @return The buffer used for {@link SpanContext} extraction.
-     */
-    ByteBuffer extractionBuffer();
+public interface Binary extends BinaryInject, BinaryExtract {
 }

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

@@ -27,7 +27,7 @@ private BinaryAdapters() {}
      *
      * @return The new {@link Binary} carrier used for extraction.
      */
-    public static Binary extractionCarrier(ByteBuffer buffer) {
+    public static BinaryExtract extractionCarrier(ByteBuffer buffer) {
         if (buffer == null) {
             throw new NullPointerException();
         }
@@ -38,37 +38,32 @@ public static Binary extractionCarrier(ByteBuffer buffer) {
     /**
      * Creates an outbound {@link Binary} instance used for injection with the
      * specified ByteBuffer as output. ByteBuffer.limit() will be set to the value
-     * of the requested length at {@link Binary#injectionBuffer()} time, and
+     * of the requested length at {@link BinaryInject#injectionBuffer} time, and
      * AssertionError will be thrown if the requested length is larger than
      * the remaining length of ByteBuffer.
      *
      * @param buffer The ByteBuffer used as input.
      *
      * @return The new Binary carrier used for injection.
      */
-    public static Binary injectionCarrier(ByteBuffer buffer) {
+    public static BinaryInject injectionCarrier(ByteBuffer buffer) {
         return new BinaryInjectAdapter(buffer);
     }
 
-    static class BinaryExtractAdapter implements Binary {
+    static class BinaryExtractAdapter implements BinaryExtract {
         ByteBuffer buffer;
 
         public BinaryExtractAdapter(ByteBuffer buffer) {
             this.buffer = buffer;
         }
 
-        @Override
-        public ByteBuffer injectionBuffer(int length) {
-            throw new UnsupportedOperationException();
-        }
-
         @Override
         public ByteBuffer extractionBuffer() {
             return buffer;
         }
     }
 
-    static class BinaryInjectAdapter implements Binary {
+    static class BinaryInjectAdapter implements BinaryInject {
         ByteBuffer buffer;
 
         public BinaryInjectAdapter(ByteBuffer buffer) {
@@ -87,10 +82,5 @@ public ByteBuffer injectionBuffer(int length) {
             buffer.limit(buffer.position() + length);
             return buffer;
         }
-
-        @Override
-        public ByteBuffer extractionBuffer() {
-            throw new UnsupportedOperationException();
-        }
     }
 }

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

@@ -0,0 +1,41 @@
+/*
+ * Copyright 2016-2018 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;
+
+/**
+ * {@link BinaryExtract} is an interface defining the required operations for a binary carrier for
+ * {@link Tracer#extract} only. {@link BinaryExtract} is defined as inbound (extraction).
+ *
+ * When called with {@link Tracer#extract}, {@link #extractionBuffer} will be called to retrieve the {@link ByteBuffer}
+ * containing the data used for {@link SpanContext} extraction.
+ *
+ * @see Format.Builtin#BINARY
+ * @see io.opentracing.Tracer#extract(Format, Object)
+ */
+public interface BinaryExtract {
+
+    /**
+     * Gets the buffer containing the data used for {@link SpanContext} extraction.
+     *
+     * It is an error to call this method when Binary is used
+     * for {@link SpanContext} injection.
+     *
+     * @return The buffer used for {@link SpanContext} extraction.
+     */
+    ByteBuffer extractionBuffer();
+}

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

@@ -0,0 +1,47 @@
+/*
+ * Copyright 2016-2018 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;
+
+/**
+ * {@link BinaryInject} is an interface defining the required operations for a binary carrier for
+ * {@link Tracer#inject} only. {@link BinaryInject} is defined as outbound (injection).
+ *
+ * When called with {@link Tracer#inject}, {@link #injectionBuffer} will be called
+ * to retrieve the actual {@link ByteBuffer} used for the {@link SpanContext} injection.
+ *
+ * @see Format.Builtin#BINARY
+ * @see io.opentracing.Tracer#inject(SpanContext, Format, Object)
+ */
+public interface BinaryInject {
+    /**
+     * Gets the buffer used to store data as part of {@link SpanContext} injection.
+     *
+     * The lenght parameter hints the buffer length required for
+     * {@link SpanContext} injection. The user may use this to allocate a new
+     * ByteBuffer or resize an existing one.
+     *
+     * It is an error to call this method when Binary is used
+     * for {@link SpanContext} extraction.
+     *
+     * @param length The buffer length required for {@link SpanContext} injection.
+     *               It needs to be larger than zero.
+     *
+     * @return The buffer used for {@link SpanContext} injection.
+     */
+    ByteBuffer injectionBuffer(int length);
+}

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

@@ -52,6 +52,22 @@ private Builtin(String name) {
          */
         public final static Format<TextMap> TEXT_MAP = new Builtin<TextMap>("TEXT_MAP");
 
+        /**
+         * Like {@link Builtin#TEXT_MAP} but specific for calling {@link Tracer#inject} with.
+         *
+         * @see io.opentracing.Tracer#inject(SpanContext, Format, Object)
+         * @see Format
+         */
+        public final static Format<TextMapInject> TEXT_MAP_INJECT = new Builtin<TextMapInject>("TEXT_MAP_INJECT");
+
+        /**
+         * Like {@link Builtin#TEXT_MAP} but specific for calling {@link Tracer#extract} with.
+         *
+         * @see io.opentracing.Tracer#extract(Format, Object)
+         * @see Format
+         */
+        public final static Format<TextMapExtract> TEXT_MAP_EXTRACT = new Builtin<TextMapExtract>("TEXT_MAP_EXTRACT");
+
         /**
          * The HTTP_HEADERS format allows for HTTP-header-compatible String-&gt;String map encoding of SpanContext state
          * for Tracer.inject and Tracer.extract.
@@ -76,6 +92,22 @@ private Builtin(String name) {
          */
         public final static Format<Binary> BINARY = new Builtin<Binary>("BINARY");
 
+        /**
+         * Like {@link Builtin#BINARY} but specific for calling {@link Tracer#inject} with.
+         *
+         * @see io.opentracing.Tracer#inject(SpanContext, Format, Object)
+         * @see Format
+         */
+        public final static Format<BinaryInject> BINARY_INJECT = new Builtin<BinaryInject>("BINARY_INJECT");
+
+        /**
+         * Like {@link Builtin#BINARY} but specific for calling {@link Tracer#extract} with.
+         *
+         * @see io.opentracing.Tracer#extract(Format, Object)
+         * @see Format
+         */
+        public final static Format<BinaryExtract> BINARY_EXTRACT = new Builtin<BinaryExtract>("BINARY_EXTRACT");
+
         /**
          * @return Short name for built-in formats as they tend to show up in exception messages.
          */

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

@@ -25,28 +25,5 @@
  * @see io.opentracing.Tracer#inject(SpanContext, Format, Object)
  * @see io.opentracing.Tracer#extract(Format, Object)
  */
-public interface TextMap extends Iterable<Map.Entry<String, String>> {
-    /**
-     * 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>> iterator();
-
-    /**
-     * 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);
+public interface TextMap extends TextMapInject, TextMapExtract {
 }

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

@@ -0,0 +1,35 @@
+/*
+ * Copyright 2016-2018 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.util.Map;
+
+/**
+ * A {@link TextMap} carrier for use with {@link Tracer#inject} and {@link Tracer#extract}.
+ *
+ * @see Tracer#inject(SpanContext, Format, Object)
+ * @see Tracer#extract(Format, Object)
+ */
+public class TextMapAdapter extends TextMapExtractAdapter implements TextMap {
+    public TextMapAdapter(Map<String, String> map) {
+        super(map);
+    }
+
+    @Override
+    public void put(String key, String value) {
+        map.put(key, value);
+    }
+}

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

@@ -0,0 +1,40 @@
+/*
+ * Copyright 2016-2018 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.util.Iterator;
+import java.util.Map;
+
+/**
+ * {@link TextMapExtract} is a built-in carrier for {@link Tracer#extract} only.
+ * {@link TextMapExtract} implementations allows Tracers to write key:value String
+ * pairs to arbitrary underlying sources of data.
+ *
+ * @see io.opentracing.Tracer#extract(Format, Object)
+ */
+public interface TextMapExtract extends Iterable<Map.Entry<String, String>> {
+    /**
+     * 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>> iterator();
+}

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

@@ -26,8 +26,8 @@
  *
  * @see Tracer#extract(Format, Object)
  */
-public final class TextMapExtractAdapter implements TextMap {
-    private final Map<String,String> map;
+public class TextMapExtractAdapter implements TextMapExtract {
+    protected final Map<String,String> map;
 
     public TextMapExtractAdapter(final Map<String,String> map) {
         this.map = map;
@@ -37,9 +37,4 @@ public TextMapExtractAdapter(final Map<String,String> map) {
     public Iterator<Map.Entry<String, String>> iterator() {
         return map.entrySet().iterator();
     }
-
-    @Override
-    public void put(String key, String value) {
-        throw new UnsupportedOperationException("TextMapExtractAdapter should only be used with Tracer.extract()");
-    }
 }