Exemplar: Refactor to be under metrics.data. (#1791)

* Exemplar: Refactor to be under common.

* Update all impl and contrib.

* Move Exemplar and AttachmentValue to metrics.data.

* Add a note in CHANGELOG.

10 files changed, 196 insertions, 175 deletions

diff --git a/api/src/main/java/io/opencensus/stats/AttachmentValue.java b/api/src/main/java/io/opencensus/metrics/data/AttachmentValue.java
index 7a7941c1..fd48aa1c 100644
--- a/api/src/main/java/io/opencensus/stats/AttachmentValue.java
+++ b/api/src/main/java/io/opencensus/metrics/data/AttachmentValue.java
@@ -14,10 +14,9 @@
  * limitations under the License.
  */
 
-package io.opencensus.stats;
+package io.opencensus.metrics.data;
 
 import com.google.auto.value.AutoValue;
-import io.opencensus.stats.AggregationData.DistributionData.Exemplar;
 import javax.annotation.concurrent.Immutable;
 
 /**
diff --git a/api/src/main/java/io/opencensus/metrics/data/Exemplar.java b/api/src/main/java/io/opencensus/metrics/data/Exemplar.java
new file mode 100644
index 00000000..39151c19
--- /dev/null
+++ b/api/src/main/java/io/opencensus/metrics/data/Exemplar.java
@@ -0,0 +1,96 @@
+/*
+ * Copyright 2019, OpenCensus 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.opencensus.metrics.data;
+
+import com.google.auto.value.AutoValue;
+import io.opencensus.common.Timestamp;
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.Map;
+import java.util.Map.Entry;
+import javax.annotation.concurrent.Immutable;
+
+/*>>>
+import org.checkerframework.checker.nullness.qual.NonNull;
+*/
+
+/**
+ * An example point that may be used to annotate aggregated distribution values, associated with a
+ * histogram bucket.
+ *
+ * @since 0.20
+ */
+@Immutable
+@AutoValue
+public abstract class Exemplar {
+
+  Exemplar() {}
+
+  /**
+   * Returns value of the {@link Exemplar} point.
+   *
+   * @return value of the {@code Exemplar} point.
+   * @since 0.20
+   */
+  public abstract double getValue();
+
+  /**
+   * Returns the time that this {@link Exemplar}'s value was recorded.
+   *
+   * @return the time that this {@code Exemplar}'s value was recorded.
+   * @since 0.20
+   */
+  public abstract Timestamp getTimestamp();
+
+  /**
+   * Returns the contextual information about the example value.
+   *
+   * @return the contextual information about the example value.
+   * @since 0.20
+   */
+  public abstract Map<String, AttachmentValue> getAttachments();
+
+  /**
+   * Creates an {@link Exemplar}.
+   *
+   * @param value value of the {@link Exemplar} point.
+   * @param timestamp the time that this {@code Exemplar}'s value was recorded.
+   * @param attachments the contextual information about the example value.
+   * @return an {@code Exemplar}.
+   * @since 0.20
+   */
+  public static Exemplar create(
+      double value, Timestamp timestamp, Map<String, AttachmentValue> attachments) {
+    checkNotNull(attachments, "attachments");
+    Map<String, AttachmentValue> attachmentsCopy =
+        Collections.unmodifiableMap(new HashMap<String, AttachmentValue>(attachments));
+    for (Entry<String, AttachmentValue> entry : attachmentsCopy.entrySet()) {
+      checkNotNull(entry.getKey(), "key of attachments");
+      checkNotNull(entry.getValue(), "value of attachments");
+    }
+    return new AutoValue_Exemplar(value, timestamp, attachmentsCopy);
+  }
+
+  // TODO(songy23): shade the internal Utils jar and remove this duplicated method.
+  private static <T /*>>> extends @NonNull Object*/> T checkNotNull(
+      T arg, @javax.annotation.Nullable Object errorMessage) {
+    if (arg == null) {
+      throw new NullPointerException(String.valueOf(errorMessage));
+    }
+    return arg;
+  }
+}
diff --git a/api/src/main/java/io/opencensus/metrics/export/Distribution.java b/api/src/main/java/io/opencensus/metrics/export/Distribution.java
index d55f101c..b08fa3ed 100644
--- a/api/src/main/java/io/opencensus/metrics/export/Distribution.java
+++ b/api/src/main/java/io/opencensus/metrics/export/Distribution.java
@@ -19,14 +19,11 @@ package io.opencensus.metrics.export;
 import com.google.auto.value.AutoValue;
 import io.opencensus.common.ExperimentalApi;
 import io.opencensus.common.Function;
-import io.opencensus.common.Timestamp;
 import io.opencensus.internal.Utils;
+import io.opencensus.metrics.data.Exemplar;
 import java.util.ArrayList;
 import java.util.Collections;
-import java.util.HashMap;
 import java.util.List;
-import java.util.Map;
-import java.util.Map.Entry;
 import javax.annotation.Nullable;
 import javax.annotation.concurrent.Immutable;
 
@@ -284,62 +281,4 @@ public abstract class Distribution {
     @Nullable
     public abstract Exemplar getExemplar();
   }
-
-  /**
-   * An example point that may be used to annotate aggregated distribution values, associated with a
-   * histogram bucket.
-   *
-   * @since 0.17
-   */
-  @Immutable
-  @AutoValue
-  public abstract static class Exemplar {
-
-    Exemplar() {}
-
-    /**
-     * Returns value of the {@link Exemplar} point.
-     *
-     * @return value of the {@code Exemplar} point.
-     * @since 0.17
-     */
-    public abstract double getValue();
-
-    /**
-     * Returns the time that this {@link Exemplar}'s value was recorded.
-     *
-     * @return the time that this {@code Exemplar}'s value was recorded.
-     * @since 0.17
-     */
-    public abstract Timestamp getTimestamp();
-
-    /**
-     * Returns the contextual information about the example value, represented as a string map.
-     *
-     * @return the contextual information about the example value.
-     * @since 0.17
-     */
-    public abstract Map<String, String> getAttachments();
-
-    /**
-     * Creates an {@link Exemplar}.
-     *
-     * @param value value of the {@link Exemplar} point.
-     * @param timestamp the time that this {@code Exemplar}'s value was recorded.
-     * @param attachments the contextual information about the example value.
-     * @return an {@code Exemplar}.
-     * @since 0.17
-     */
-    public static Exemplar create(
-        double value, Timestamp timestamp, Map<String, String> attachments) {
-      Utils.checkNotNull(attachments, "attachments");
-      Map<String, String> attachmentsCopy =
-          Collections.unmodifiableMap(new HashMap<String, String>(attachments));
-      for (Entry<String, String> entry : attachmentsCopy.entrySet()) {
-        Utils.checkNotNull(entry.getKey(), "key of attachments");
-        Utils.checkNotNull(entry.getValue(), "value of attachments");
-      }
-      return new AutoValue_Distribution_Exemplar(value, timestamp, attachmentsCopy);
-    }
-  }
 }
diff --git a/api/src/main/java/io/opencensus/stats/AggregationData.java b/api/src/main/java/io/opencensus/stats/AggregationData.java
index 2e68cfd0..23c9af93 100644
--- a/api/src/main/java/io/opencensus/stats/AggregationData.java
+++ b/api/src/main/java/io/opencensus/stats/AggregationData.java
@@ -18,14 +18,11 @@ package io.opencensus.stats;
 
 import com.google.auto.value.AutoValue;
 import io.opencensus.common.Function;
-import io.opencensus.common.Timestamp;
 import io.opencensus.internal.Utils;
+import io.opencensus.metrics.data.Exemplar;
 import java.util.ArrayList;
 import java.util.Collections;
-import java.util.HashMap;
 import java.util.List;
-import java.util.Map;
-import java.util.Map.Entry;
 import javax.annotation.concurrent.Immutable;
 
 /**
@@ -445,65 +442,6 @@ public abstract class AggregationData {
         Function<? super AggregationData, T> defaultFunction) {
       return p3.apply(this);
     }
-
-    /**
-     * An example point that may be used to annotate aggregated distribution values, associated with
-     * a histogram bucket.
-     *
-     * @since 0.16
-     */
-    @Immutable
-    @AutoValue
-    public abstract static class Exemplar {
-
-      Exemplar() {}
-
-      /**
-       * Returns value of the {@link Exemplar} point.
-       *
-       * @return value of the {@code Exemplar} point.
-       * @since 0.16
-       */
-      public abstract double getValue();
-
-      /**
-       * Returns the time that this {@link Exemplar}'s value was recorded.
-       *
-       * @return the time that this {@code Exemplar}'s value was recorded.
-       * @since 0.16
-       */
-      public abstract Timestamp getTimestamp();
-
-      /**
-       * Returns the contextual information about the example value.
-       *
-       * @return the contextual information about the example value.
-       * @since 0.20
-       */
-      public abstract Map<String, AttachmentValue> getAttachments();
-
-      /**
-       * Creates an {@link Exemplar}.
-       *
-       * @param value value of the {@link Exemplar} point.
-       * @param timestamp the time that this {@code Exemplar}'s value was recorded.
-       * @param attachments the contextual information about the example value.
-       * @return an {@code Exemplar}.
-       * @since 0.20
-       */
-      public static Exemplar create(
-          double value, Timestamp timestamp, Map<String, AttachmentValue> attachments) {
-        Utils.checkNotNull(attachments, "attachments");
-        Map<String, AttachmentValue> attachmentsCopy =
-            Collections.unmodifiableMap(new HashMap<String, AttachmentValue>(attachments));
-        for (Entry<String, AttachmentValue> entry : attachmentsCopy.entrySet()) {
-          Utils.checkNotNull(entry.getKey(), "key of attachments");
-          Utils.checkNotNull(entry.getValue(), "value of attachments");
-        }
-        return new AutoValue_AggregationData_DistributionData_Exemplar(
-            value, timestamp, attachmentsCopy);
-      }
-    }
   }
 
   /**
diff --git a/api/src/main/java/io/opencensus/stats/MeasureMap.java b/api/src/main/java/io/opencensus/stats/MeasureMap.java
index 6305eb47..ba79487f 100644
--- a/api/src/main/java/io/opencensus/stats/MeasureMap.java
+++ b/api/src/main/java/io/opencensus/stats/MeasureMap.java
@@ -17,7 +17,8 @@
 package io.opencensus.stats;
 
 import io.opencensus.internal.Utils;
-import io.opencensus.stats.AttachmentValue.AttachmentValueString;
+import io.opencensus.metrics.data.AttachmentValue;
+import io.opencensus.metrics.data.AttachmentValue.AttachmentValueString;
 import io.opencensus.stats.Measure.MeasureDouble;
 import io.opencensus.stats.Measure.MeasureLong;
 import io.opencensus.tags.TagContext;
diff --git a/api/src/test/java/io/opencensus/stats/AttachmentValueTest.java b/api/src/test/java/io/opencensus/metrics/data/AttachmentValueTest.java
index 7f72ca31..9c5efe62 100644
--- a/api/src/test/java/io/opencensus/stats/AttachmentValueTest.java
+++ b/api/src/test/java/io/opencensus/metrics/data/AttachmentValueTest.java
@@ -14,18 +14,18 @@
  * limitations under the License.
  */
 
-package io.opencensus.stats;
+package io.opencensus.metrics.data;
 
 import static com.google.common.truth.Truth.assertThat;
 
-import io.opencensus.stats.AttachmentValue.AttachmentValueString;
+import io.opencensus.metrics.data.AttachmentValue.AttachmentValueString;
 import org.junit.Rule;
 import org.junit.Test;
 import org.junit.rules.ExpectedException;
 import org.junit.runner.RunWith;
 import org.junit.runners.JUnit4;
 
-/** Unit tests for {@link AttachmentValue}. */
+/** Unit tests for {@link io.opencensus.metrics.data.AttachmentValue}. */
 @RunWith(JUnit4.class)
 public class AttachmentValueTest {
 
diff --git a/api/src/test/java/io/opencensus/metrics/data/ExemplarTest.java b/api/src/test/java/io/opencensus/metrics/data/ExemplarTest.java
new file mode 100644
index 00000000..3735f927
--- /dev/null
+++ b/api/src/test/java/io/opencensus/metrics/data/ExemplarTest.java
@@ -0,0 +1,79 @@
+/*
+ * Copyright 2019, OpenCensus 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.opencensus.metrics.data;
+
+import static com.google.common.truth.Truth.assertThat;
+
+import io.opencensus.common.Timestamp;
+import io.opencensus.metrics.data.AttachmentValue.AttachmentValueString;
+import java.util.Collections;
+import java.util.Map;
+import org.junit.Rule;
+import org.junit.Test;
+import org.junit.rules.ExpectedException;
+import org.junit.runner.RunWith;
+import org.junit.runners.JUnit4;
+
+/** Unit tests for {@link io.opencensus.metrics.data.Exemplar}. */
+@RunWith(JUnit4.class)
+public class ExemplarTest {
+
+  private static final double TOLERANCE = 1e-6;
+  private static final Timestamp TIMESTAMP_1 = Timestamp.create(1, 0);
+  private static final AttachmentValue ATTACHMENT_VALUE = AttachmentValueString.create("value");
+  private static final Map<String, AttachmentValue> ATTACHMENTS =
+      Collections.singletonMap("key", ATTACHMENT_VALUE);
+
+  @Rule public ExpectedException thrown = ExpectedException.none();
+
+  @Test
+  public void testExemplar() {
+    Exemplar exemplar = Exemplar.create(15.0, TIMESTAMP_1, ATTACHMENTS);
+    assertThat(exemplar.getValue()).isWithin(TOLERANCE).of(15.0);
+    assertThat(exemplar.getTimestamp()).isEqualTo(TIMESTAMP_1);
+    assertThat(exemplar.getAttachments()).isEqualTo(ATTACHMENTS);
+  }
+
+  @Test
+  public void testExemplar_PreventNullTimestamp() {
+    thrown.expect(NullPointerException.class);
+    Exemplar.create(15, null, ATTACHMENTS);
+  }
+
+  @Test
+  public void testExemplar_PreventNullAttachments() {
+    thrown.expect(NullPointerException.class);
+    thrown.expectMessage("attachments");
+    Exemplar.create(15, TIMESTAMP_1, null);
+  }
+
+  @Test
+  public void testExemplar_PreventNullAttachmentKey() {
+    Map<String, AttachmentValue> attachments = Collections.singletonMap(null, ATTACHMENT_VALUE);
+    thrown.expect(NullPointerException.class);
+    thrown.expectMessage("key of attachment");
+    Exemplar.create(15, TIMESTAMP_1, attachments);
+  }
+
+  @Test
+  public void testExemplar_PreventNullAttachmentValue() {
+    Map<String, AttachmentValue> attachments = Collections.singletonMap("key", null);
+    thrown.expect(NullPointerException.class);
+    thrown.expectMessage("value of attachment");
+    Exemplar.create(15, TIMESTAMP_1, attachments);
+  }
+}
diff --git a/api/src/test/java/io/opencensus/metrics/export/DistributionTest.java b/api/src/test/java/io/opencensus/metrics/export/DistributionTest.java
index 85b31498..07dc01e0 100644
--- a/api/src/test/java/io/opencensus/metrics/export/DistributionTest.java
+++ b/api/src/test/java/io/opencensus/metrics/export/DistributionTest.java
@@ -22,10 +22,12 @@ import com.google.common.testing.EqualsTester;
 import io.opencensus.common.Function;
 import io.opencensus.common.Functions;
 import io.opencensus.common.Timestamp;
+import io.opencensus.metrics.data.AttachmentValue;
+import io.opencensus.metrics.data.AttachmentValue.AttachmentValueString;
+import io.opencensus.metrics.data.Exemplar;
 import io.opencensus.metrics.export.Distribution.Bucket;
 import io.opencensus.metrics.export.Distribution.BucketOptions;
 import io.opencensus.metrics.export.Distribution.BucketOptions.ExplicitOptions;
-import io.opencensus.metrics.export.Distribution.Exemplar;
 import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.Collections;
@@ -44,7 +46,9 @@ public class DistributionTest {
   @Rule public final ExpectedException thrown = ExpectedException.none();
 
   private static final Timestamp TIMESTAMP = Timestamp.create(1, 0);
-  private static final Map<String, String> ATTACHMENTS = Collections.singletonMap("key", "value");
+  private static final AttachmentValue VALUE = AttachmentValueString.create("value");
+  private static final Map<String, AttachmentValue> ATTACHMENTS =
+      Collections.<String, AttachmentValue>singletonMap("key", VALUE);
   private static final double TOLERANCE = 1e-6;
 
   @Test
@@ -190,7 +194,7 @@ public class DistributionTest {
 
   @Test
   public void createExemplar_PreventNullAttachmentKey() {
-    Map<String, String> attachments = Collections.singletonMap(null, "value");
+    Map<String, AttachmentValue> attachments = Collections.singletonMap(null, VALUE);
     thrown.expect(NullPointerException.class);
     thrown.expectMessage("key of attachment");
     Exemplar.create(15, TIMESTAMP, attachments);
@@ -198,7 +202,7 @@ public class DistributionTest {
 
   @Test
   public void createExemplar_PreventNullAttachmentValue() {
-    Map<String, String> attachments = Collections.singletonMap("key", null);
+    Map<String, AttachmentValue> attachments = Collections.singletonMap("key", null);
     thrown.expect(NullPointerException.class);
     thrown.expectMessage("value of attachment");
     Exemplar.create(15, TIMESTAMP, attachments);
diff --git a/api/src/test/java/io/opencensus/stats/AggregationDataTest.java b/api/src/test/java/io/opencensus/stats/AggregationDataTest.java
index 529a23b4..cfdb8977 100644
--- a/api/src/test/java/io/opencensus/stats/AggregationDataTest.java
+++ b/api/src/test/java/io/opencensus/stats/AggregationDataTest.java
@@ -22,15 +22,16 @@ import com.google.common.testing.EqualsTester;
 import io.opencensus.common.Function;
 import io.opencensus.common.Functions;
 import io.opencensus.common.Timestamp;
+import io.opencensus.metrics.data.AttachmentValue;
+import io.opencensus.metrics.data.AttachmentValue.AttachmentValueString;
+import io.opencensus.metrics.data.Exemplar;
 import io.opencensus.stats.AggregationData.CountData;
 import io.opencensus.stats.AggregationData.DistributionData;
-import io.opencensus.stats.AggregationData.DistributionData.Exemplar;
 import io.opencensus.stats.AggregationData.LastValueDataDouble;
 import io.opencensus.stats.AggregationData.LastValueDataLong;
 import io.opencensus.stats.AggregationData.MeanData;
 import io.opencensus.stats.AggregationData.SumDataDouble;
 import io.opencensus.stats.AggregationData.SumDataLong;
-import io.opencensus.stats.AttachmentValue.AttachmentValueString;
 import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.Collections;
@@ -76,43 +77,6 @@ public class AggregationDataTest {
   }
 
   @Test
-  public void testExemplar() {
-    Exemplar exemplar = Exemplar.create(15.0, TIMESTAMP_1, ATTACHMENTS);
-    assertThat(exemplar.getValue()).isWithin(TOLERANCE).of(15.0);
-    assertThat(exemplar.getTimestamp()).isEqualTo(TIMESTAMP_1);
-    assertThat(exemplar.getAttachments()).isEqualTo(ATTACHMENTS);
-  }
-
-  @Test
-  public void testExemplar_PreventNullTimestamp() {
-    thrown.expect(NullPointerException.class);
-    Exemplar.create(15, null, ATTACHMENTS);
-  }
-
-  @Test
-  public void testExemplar_PreventNullAttachments() {
-    thrown.expect(NullPointerException.class);
-    thrown.expectMessage("attachments");
-    Exemplar.create(15, TIMESTAMP_1, null);
-  }
-
-  @Test
-  public void testExemplar_PreventNullAttachmentKey() {
-    Map<String, AttachmentValue> attachments = Collections.singletonMap(null, ATTACHMENT_VALUE);
-    thrown.expect(NullPointerException.class);
-    thrown.expectMessage("key of attachment");
-    Exemplar.create(15, TIMESTAMP_1, attachments);
-  }
-
-  @Test
-  public void testExemplar_PreventNullAttachmentValue() {
-    Map<String, AttachmentValue> attachments = Collections.singletonMap("key", null);
-    thrown.expect(NullPointerException.class);
-    thrown.expectMessage("value of attachment");
-    Exemplar.create(15, TIMESTAMP_1, attachments);
-  }
-
-  @Test
   public void preventNullBucketCountList() {
     thrown.expect(NullPointerException.class);
     thrown.expectMessage("bucketCounts");
diff --git a/api/src/test/java/io/opencensus/stats/NoopStatsTest.java b/api/src/test/java/io/opencensus/stats/NoopStatsTest.java
index 2e2f1e03..5a74ea30 100644
--- a/api/src/test/java/io/opencensus/stats/NoopStatsTest.java
+++ b/api/src/test/java/io/opencensus/stats/NoopStatsTest.java
@@ -18,7 +18,8 @@ package io.opencensus.stats;
 
 import static com.google.common.truth.Truth.assertThat;
 
-import io.opencensus.stats.AttachmentValue.AttachmentValueString;
+import io.opencensus.metrics.data.AttachmentValue;
+import io.opencensus.metrics.data.AttachmentValue.AttachmentValueString;
 import io.opencensus.stats.Measure.MeasureDouble;
 import io.opencensus.tags.Tag;
 import io.opencensus.tags.TagContext;