Add get/from{Byte} methods on TraceOptions and deprecate get/from{Bytes}. (#1392)

* Add get/from{Byte} methods on TraceOptions and deprecate get/from{Bytes}.

* Update changelog.

9 files changed, 74 insertions, 31 deletions

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6c3eb395..96cbd194 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -11,6 +11,7 @@
 - Allow custom prefix for Stackdriver metrics in `StackdriverStatsConfiguration`.
 - Add support to handle the Tracestate in the SpanContext.
 - Remove global synchronization from the get current stats state.
+- Add get/from{Byte} methods on TraceOptions and deprecate get/from{Bytes}.
 
 ## 0.15.0 - 2018-06-20
 - Expose the factory methods of MonitoredResource.
diff --git a/api/src/main/java/io/opencensus/trace/TraceOptions.java b/api/src/main/java/io/opencensus/trace/TraceOptions.java
index f34ba190..86379f1e 100644
--- a/api/src/main/java/io/opencensus/trace/TraceOptions.java
+++ b/api/src/main/java/io/opencensus/trace/TraceOptions.java
@@ -48,7 +48,7 @@ public final class TraceOptions {
    *
    * @since 0.5
    */
-  public static final TraceOptions DEFAULT = new TraceOptions(DEFAULT_OPTIONS);
+  public static final TraceOptions DEFAULT = fromByte(DEFAULT_OPTIONS);
 
   // The set of enabled features is determined by all the enabled bits.
   private final byte options;
@@ -72,13 +72,15 @@ public final class TraceOptions {
    * @throws NullPointerException if {@code buffer} is null.
    * @throws IllegalArgumentException if {@code buffer.length} is not {@link TraceOptions#SIZE}.
    * @since 0.5
+   * @deprecated use {@link #fromByte(byte)}.
    */
+  @Deprecated
   public static TraceOptions fromBytes(byte[] buffer) {
     Utils.checkNotNull(buffer, "buffer");
     Utils.checkArgument(
         buffer.length == SIZE,
         String.format("Invalid size: expected %s, got %s", SIZE, buffer.length));
-    return new TraceOptions(buffer[0]);
+    return fromByte(buffer[0]);
   }
 
   /**
@@ -93,10 +95,34 @@ public final class TraceOptions {
    * @throws IndexOutOfBoundsException if {@code srcOffset+TraceOptions.SIZE} is greater than {@code
    *     src.length}.
    * @since 0.5
+   * @deprecated use {@link #fromByte(byte)}.
    */
+  @Deprecated
   public static TraceOptions fromBytes(byte[] src, int srcOffset) {
     Utils.checkIndex(srcOffset, src.length);
-    return new TraceOptions(src[srcOffset]);
+    return fromByte(src[srcOffset]);
+  }
+
+  /**
+   * Returns a {@code TraceOptions} whose representation is {@code src}.
+   *
+   * @param src the byte representation of the {@code TraceOptions}.
+   * @return a {@code TraceOptions} whose representation is {@code src}.
+   * @since 0.16
+   */
+  public static TraceOptions fromByte(byte src) {
+    // TODO(bdrutu): OPTIMIZATION: Cache all the 256 possible objects and return from the cache.
+    return new TraceOptions(src);
+  }
+
+  /**
+   * Returns the one byte representation of the {@code TraceOptions}.
+   *
+   * @return the one byte representation of the {@code TraceOptions}.
+   * @since 0.16
+   */
+  public byte getByte() {
+    return options;
   }
 
   /**
@@ -104,7 +130,9 @@ public final class TraceOptions {
    *
    * @return the 1-byte array representation of the {@code TraceOptions}.
    * @since 0.5
+   * @deprecated use {@link #getByte()}.
    */
+  @Deprecated
   public byte[] getBytes() {
     byte[] bytes = new byte[SIZE];
     bytes[0] = options;
@@ -237,7 +265,7 @@ public final class TraceOptions {
      * @since 0.5
      */
     public TraceOptions build() {
-      return new TraceOptions(options);
+      return fromByte(options);
     }
   }
 
diff --git a/api/src/test/java/io/opencensus/trace/TraceOptionsTest.java b/api/src/test/java/io/opencensus/trace/TraceOptionsTest.java
index a892384b..3c46d097 100644
--- a/api/src/test/java/io/opencensus/trace/TraceOptionsTest.java
+++ b/api/src/test/java/io/opencensus/trace/TraceOptionsTest.java
@@ -26,9 +26,9 @@ import org.junit.runners.JUnit4;
 /** Unit tests for {@link TraceOptions}. */
 @RunWith(JUnit4.class)
 public class TraceOptionsTest {
-  private static final byte[] firstBytes = {(byte) 0xff};
-  private static final byte[] secondBytes = {1};
-  private static final byte[] thirdBytes = {6};
+  private static final byte FIRST_BYTE = (byte) 0xff;
+  private static final byte SECOND_BYTE = 1;
+  private static final byte THIRD_BYTE = 6;
 
   @Test
   public void getOptions() {
@@ -37,9 +37,9 @@ public class TraceOptionsTest {
     assertThat(TraceOptions.builder().setIsSampled(true).build().getOptions()).isEqualTo(1);
     assertThat(TraceOptions.builder().setIsSampled(true).setIsSampled(false).build().getOptions())
         .isEqualTo(0);
-    assertThat(TraceOptions.fromBytes(firstBytes).getOptions()).isEqualTo(-1);
-    assertThat(TraceOptions.fromBytes(secondBytes).getOptions()).isEqualTo(1);
-    assertThat(TraceOptions.fromBytes(thirdBytes).getOptions()).isEqualTo(6);
+    assertThat(TraceOptions.fromByte(FIRST_BYTE).getOptions()).isEqualTo(-1);
+    assertThat(TraceOptions.fromByte(SECOND_BYTE).getOptions()).isEqualTo(1);
+    assertThat(TraceOptions.fromByte(THIRD_BYTE).getOptions()).isEqualTo(6);
   }
 
   @Test
@@ -49,16 +49,30 @@ public class TraceOptionsTest {
   }
 
   @Test
-  public void toFromBytes() {
-    assertThat(TraceOptions.fromBytes(firstBytes).getBytes()).isEqualTo(firstBytes);
-    assertThat(TraceOptions.fromBytes(secondBytes).getBytes()).isEqualTo(secondBytes);
-    assertThat(TraceOptions.fromBytes(thirdBytes).getBytes()).isEqualTo(thirdBytes);
+  public void toFromByte() {
+    assertThat(TraceOptions.fromByte(FIRST_BYTE).getByte()).isEqualTo(FIRST_BYTE);
+    assertThat(TraceOptions.fromByte(SECOND_BYTE).getByte()).isEqualTo(SECOND_BYTE);
+    assertThat(TraceOptions.fromByte(THIRD_BYTE).getByte()).isEqualTo(THIRD_BYTE);
+  }
+
+  @Test
+  @SuppressWarnings("deprecation")
+  public void deprecated_fromBytes() {
+    assertThat(TraceOptions.fromBytes(new byte[] {FIRST_BYTE}).getByte()).isEqualTo(FIRST_BYTE);
+    assertThat(TraceOptions.fromBytes(new byte[] {1, FIRST_BYTE}, 1).getByte())
+        .isEqualTo(FIRST_BYTE);
+  }
+
+  @Test
+  @SuppressWarnings("deprecation")
+  public void deprecated_getBytes() {
+    assertThat(TraceOptions.fromByte(FIRST_BYTE).getBytes()).isEqualTo(new byte[] {FIRST_BYTE});
   }
 
   @Test
   public void builder_FromOptions() {
     assertThat(
-            TraceOptions.builder(TraceOptions.fromBytes(thirdBytes))
+            TraceOptions.builder(TraceOptions.fromByte(THIRD_BYTE))
                 .setIsSampled(true)
                 .build()
                 .getOptions())
@@ -70,8 +84,8 @@ public class TraceOptionsTest {
     EqualsTester tester = new EqualsTester();
     tester.addEqualityGroup(TraceOptions.DEFAULT);
     tester.addEqualityGroup(
-        TraceOptions.fromBytes(secondBytes), TraceOptions.builder().setIsSampled(true).build());
-    tester.addEqualityGroup(TraceOptions.fromBytes(firstBytes));
+        TraceOptions.fromByte(SECOND_BYTE), TraceOptions.builder().setIsSampled(true).build());
+    tester.addEqualityGroup(TraceOptions.fromByte(FIRST_BYTE));
     tester.testEquals();
   }
 
diff --git a/benchmarks/src/jmh/java/io/opencensus/benchmarks/trace/propagation/BinaryPropagationImplBenchmark.java b/benchmarks/src/jmh/java/io/opencensus/benchmarks/trace/propagation/BinaryPropagationImplBenchmark.java
index c4fc0ff1..b572bbef 100644
--- a/benchmarks/src/jmh/java/io/opencensus/benchmarks/trace/propagation/BinaryPropagationImplBenchmark.java
+++ b/benchmarks/src/jmh/java/io/opencensus/benchmarks/trace/propagation/BinaryPropagationImplBenchmark.java
@@ -40,8 +40,8 @@ public class BinaryPropagationImplBenchmark {
   private static final TraceId traceId = TraceId.fromBytes(traceIdBytes);
   private static final byte[] spanIdBytes = new byte[] {(byte) 0xFF, 0, 0, 0, 0, 0, 0, 0};
   private static final SpanId spanId = SpanId.fromBytes(spanIdBytes);
-  private static final byte[] traceOptionsBytes = new byte[] {1};
-  private static final TraceOptions traceOptions = TraceOptions.fromBytes(traceOptionsBytes);
+  private static final byte TRACE_OPTIONS_BYTE = 1;
+  private static final TraceOptions traceOptions = TraceOptions.fromByte(TRACE_OPTIONS_BYTE);
   private static final SpanContext spanContext =
       SpanContext.create(traceId, spanId, traceOptions, Tracestate.builder().build());
   private static final BinaryFormat binaryFormat =
diff --git a/exporters/trace/instana/src/test/java/io/opencensus/exporter/trace/instana/InstanaExporterHandlerTest.java b/exporters/trace/instana/src/test/java/io/opencensus/exporter/trace/instana/InstanaExporterHandlerTest.java
index 12915e41..3b5e119e 100644
--- a/exporters/trace/instana/src/test/java/io/opencensus/exporter/trace/instana/InstanaExporterHandlerTest.java
+++ b/exporters/trace/instana/src/test/java/io/opencensus/exporter/trace/instana/InstanaExporterHandlerTest.java
@@ -69,7 +69,7 @@ public class InstanaExporterHandlerTest {
             SpanContext.create(
                 TraceId.fromLowerBase16(TRACE_ID),
                 SpanId.fromLowerBase16(SPAN_ID),
-                TraceOptions.fromBytes(new byte[] {1} /* sampled */)),
+                TraceOptions.builder().setIsSampled(true).build()),
             SpanId.fromLowerBase16(PARENT_SPAN_ID),
             true, /* hasRemoteParent */
             "SpanName", /* name */
@@ -107,7 +107,7 @@ public class InstanaExporterHandlerTest {
             SpanContext.create(
                 TraceId.fromLowerBase16(TRACE_ID),
                 SpanId.fromLowerBase16(SPAN_ID),
-                TraceOptions.fromBytes(new byte[] {1} /* sampled */)),
+                TraceOptions.builder().setIsSampled(true).build()),
             SpanId.fromLowerBase16(PARENT_SPAN_ID),
             true, /* hasRemoteParent */
             "SpanName", /* name */
@@ -145,7 +145,7 @@ public class InstanaExporterHandlerTest {
             SpanContext.create(
                 TraceId.fromLowerBase16(TRACE_ID),
                 SpanId.fromLowerBase16(SPAN_ID),
-                TraceOptions.fromBytes(new byte[] {1} /* sampled */)),
+                TraceOptions.builder().setIsSampled(true).build()),
             SpanId.fromLowerBase16(PARENT_SPAN_ID),
             true, /* hasRemoteParent */
             "SpanName", /* name */
diff --git a/exporters/trace/zipkin/src/test/java/io/opencensus/exporter/trace/zipkin/ZipkinExporterHandlerTest.java b/exporters/trace/zipkin/src/test/java/io/opencensus/exporter/trace/zipkin/ZipkinExporterHandlerTest.java
index 5de247a4..7e293003 100644
--- a/exporters/trace/zipkin/src/test/java/io/opencensus/exporter/trace/zipkin/ZipkinExporterHandlerTest.java
+++ b/exporters/trace/zipkin/src/test/java/io/opencensus/exporter/trace/zipkin/ZipkinExporterHandlerTest.java
@@ -72,7 +72,7 @@ public class ZipkinExporterHandlerTest {
             SpanContext.create(
                 TraceId.fromLowerBase16(TRACE_ID),
                 SpanId.fromLowerBase16(SPAN_ID),
-                TraceOptions.fromBytes(new byte[] {1} /* sampled */)),
+                TraceOptions.builder().setIsSampled(true).build()),
             // TODO SpanId.fromLowerBase16
             SpanId.fromLowerBase16(PARENT_SPAN_ID),
             true, /* hasRemoteParent */
@@ -113,7 +113,7 @@ public class ZipkinExporterHandlerTest {
             SpanContext.create(
                 TraceId.fromLowerBase16(TRACE_ID),
                 SpanId.fromLowerBase16(SPAN_ID),
-                TraceOptions.fromBytes(new byte[] {1} /* sampled */)),
+                TraceOptions.builder().setIsSampled(true).build()),
             // TODO SpanId.fromLowerBase16
             SpanId.fromLowerBase16(PARENT_SPAN_ID),
             true, /* hasRemoteParent */
@@ -154,7 +154,7 @@ public class ZipkinExporterHandlerTest {
             SpanContext.create(
                 TraceId.fromLowerBase16(TRACE_ID),
                 SpanId.fromLowerBase16(SPAN_ID),
-                TraceOptions.fromBytes(new byte[] {1} /* sampled */)),
+                TraceOptions.builder().setIsSampled(true).build()),
             // TODO SpanId.fromLowerBase16
             SpanId.fromLowerBase16(PARENT_SPAN_ID),
             true, /* hasRemoteParent */
@@ -199,7 +199,7 @@ public class ZipkinExporterHandlerTest {
             SpanContext.create(
                 TraceId.fromLowerBase16(TRACE_ID),
                 SpanId.fromLowerBase16(SPAN_ID),
-                TraceOptions.fromBytes(new byte[] {1} /* sampled */)),
+                TraceOptions.builder().setIsSampled(true).build()),
             // TODO SpanId.fromLowerBase16
             SpanId.fromLowerBase16(PARENT_SPAN_ID),
             true, /* hasRemoteParent */
diff --git a/impl_core/src/main/java/io/opencensus/implcore/trace/propagation/BinaryFormatImpl.java b/impl_core/src/main/java/io/opencensus/implcore/trace/propagation/BinaryFormatImpl.java
index 1af24854..233fbd31 100644
--- a/impl_core/src/main/java/io/opencensus/implcore/trace/propagation/BinaryFormatImpl.java
+++ b/impl_core/src/main/java/io/opencensus/implcore/trace/propagation/BinaryFormatImpl.java
@@ -141,7 +141,7 @@ final class BinaryFormatImpl extends BinaryFormat {
       if (bytes.length < ALL_FORMAT_LENGTH) {
         throw new SpanContextParseException("Invalid input: truncated");
       }
-      traceOptions = TraceOptions.fromBytes(bytes, pos + ID_SIZE);
+      traceOptions = TraceOptions.fromByte(bytes[pos + ID_SIZE]);
     }
     return SpanContext.create(traceId, spanId, traceOptions, TRACESTATE_DEFAULT);
   }
diff --git a/impl_core/src/test/java/io/opencensus/implcore/trace/propagation/B3FormatTest.java b/impl_core/src/test/java/io/opencensus/implcore/trace/propagation/B3FormatTest.java
index 45514d06..29553f3f 100644
--- a/impl_core/src/test/java/io/opencensus/implcore/trace/propagation/B3FormatTest.java
+++ b/impl_core/src/test/java/io/opencensus/implcore/trace/propagation/B3FormatTest.java
@@ -49,8 +49,8 @@ public class B3FormatTest {
       TraceId.fromLowerBase16("0000000000000000" + TRACE_ID_BASE16_EIGHT_BYTES);
   private static final String SPAN_ID_BASE16 = "ff00000000000041";
   private static final SpanId SPAN_ID = SpanId.fromLowerBase16(SPAN_ID_BASE16);
-  private static final byte[] TRACE_OPTIONS_BYTES = new byte[] {1};
-  private static final TraceOptions TRACE_OPTIONS = TraceOptions.fromBytes(TRACE_OPTIONS_BYTES);
+  private static final byte TRACE_OPTIONS_BYTE = 1;
+  private static final TraceOptions TRACE_OPTIONS = TraceOptions.fromByte(TRACE_OPTIONS_BYTE);
   private final B3Format b3Format = new B3Format();
   @Rule public ExpectedException thrown = ExpectedException.none();
   private final Setter<Map<String, String>> setter =
diff --git a/impl_core/src/test/java/io/opencensus/implcore/trace/propagation/BinaryFormatImplTest.java b/impl_core/src/test/java/io/opencensus/implcore/trace/propagation/BinaryFormatImplTest.java
index 398b18a3..f43be479 100644
--- a/impl_core/src/test/java/io/opencensus/implcore/trace/propagation/BinaryFormatImplTest.java
+++ b/impl_core/src/test/java/io/opencensus/implcore/trace/propagation/BinaryFormatImplTest.java
@@ -39,8 +39,8 @@ public class BinaryFormatImplTest {
   private static final TraceId TRACE_ID = TraceId.fromBytes(TRACE_ID_BYTES);
   private static final byte[] SPAN_ID_BYTES = new byte[] {97, 98, 99, 100, 101, 102, 103, 104};
   private static final SpanId SPAN_ID = SpanId.fromBytes(SPAN_ID_BYTES);
-  private static final byte[] TRACE_OPTIONS_BYTES = new byte[] {1};
-  private static final TraceOptions TRACE_OPTIONS = TraceOptions.fromBytes(TRACE_OPTIONS_BYTES);
+  private static final byte TRACE_OPTIONS_BYTES = 1;
+  private static final TraceOptions TRACE_OPTIONS = TraceOptions.fromByte(TRACE_OPTIONS_BYTES);
   private static final byte[] EXAMPLE_BYTES =
       new byte[] {
         0, 0, 64, 65, 66, 67, 68, 69, 70, 71, 72, 73, 74, 75, 76, 77, 78, 79, 1, 97, 98, 99, 100,