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.

2 files changed, 59 insertions, 17 deletions

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();
   }