Metrics: Add LabelKey and LabelValue. (#1261)

* Include opencensus-metrics in settings.gradle.

* Add LabelKey and LabelValue.

* Improve unit tests.

* Use Nullable string value for LabelValue. Null value indicates unset.

* Remove hasValue().

5 files changed, 281 insertions, 4 deletions

diff --git a/metrics/src/main/java/io/opencensus/metrics/LabelKey.java b/metrics/src/main/java/io/opencensus/metrics/LabelKey.java
new file mode 100644
index 00000000..01ef0b55
--- /dev/null
+++ b/metrics/src/main/java/io/opencensus/metrics/LabelKey.java
@@ -0,0 +1,62 @@
+/*
+ * Copyright 2018, 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;
+
+import com.google.auto.value.AutoValue;
+import io.opencensus.common.ExperimentalApi;
+import javax.annotation.concurrent.Immutable;
+
+/**
+ * The key of a {@code Label} associated with a {@code MetricDescriptor}.
+ *
+ * @since 0.15
+ */
+@ExperimentalApi
+@Immutable
+@AutoValue
+public abstract class LabelKey {
+
+  LabelKey() {}
+
+  /**
+   * Creates a {@link LabelKey}.
+   *
+   * @param key the key of a {@code Label}.
+   * @param description a human-readable description of what this label key represents.
+   * @return a {@code LabelKey}.
+   * @since 0.15
+   */
+  public static LabelKey create(String key, String description) {
+    return new AutoValue_LabelKey(key, description);
+  }
+
+  /**
+   * Returns the key of this {@link LabelKey}.
+   *
+   * @return the key.
+   * @since 0.15
+   */
+  public abstract String getKey();
+
+  /**
+   * Returns the description of this {@link LabelKey}.
+   *
+   * @return the description.
+   * @since 0.15
+   */
+  public abstract String getDescription();
+}
diff --git a/metrics/src/main/java/io/opencensus/metrics/LabelValue.java b/metrics/src/main/java/io/opencensus/metrics/LabelValue.java
new file mode 100644
index 00000000..e81b63d2
--- /dev/null
+++ b/metrics/src/main/java/io/opencensus/metrics/LabelValue.java
@@ -0,0 +1,57 @@
+/*
+ * Copyright 2018, 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;
+
+import com.google.auto.value.AutoValue;
+import io.opencensus.common.ExperimentalApi;
+import javax.annotation.Nullable;
+import javax.annotation.concurrent.Immutable;
+
+/**
+ * The value of a {@code Label} associated with a {@code TimeSeries}.
+ *
+ * @since 0.15
+ */
+@ExperimentalApi
+@Immutable
+@AutoValue
+public abstract class LabelValue {
+
+  LabelValue() {}
+
+  /**
+   * Creates a {@link LabelValue}.
+   *
+   * @param value the value of a {@code Label}. {@code null} value indicates an unset {@code
+   *     LabelValue}.
+   * @return a {@code LabelValue}.
+   * @since 0.15
+   */
+  public static LabelValue create(@Nullable String value) {
+    return new AutoValue_LabelValue(value);
+  }
+
+  /**
+   * Returns the value of this {@link LabelValue}. Returns {@code null} if the value is unset and
+   * supposed to be ignored.
+   *
+   * @return the value.
+   * @since 0.15
+   */
+  @Nullable
+  public abstract String getValue();
+}
diff --git a/metrics/src/test/java/io/opencensus/metrics/LabelKeyTest.java b/metrics/src/test/java/io/opencensus/metrics/LabelKeyTest.java
new file mode 100644
index 00000000..83f2b59a
--- /dev/null
+++ b/metrics/src/test/java/io/opencensus/metrics/LabelKeyTest.java
@@ -0,0 +1,86 @@
+/*
+ * Copyright 2018, 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;
+
+import static com.google.common.truth.Truth.assertThat;
+
+import com.google.common.testing.EqualsTester;
+import java.util.Arrays;
+import org.junit.Test;
+import org.junit.runner.RunWith;
+import org.junit.runners.JUnit4;
+
+/** Unit tests for {@link LabelKey}. */
+@RunWith(JUnit4.class)
+public class LabelKeyTest {
+
+  private static final LabelKey KEY = LabelKey.create("key", "description");
+
+  @Test
+  public void testGetKey() {
+    assertThat(KEY.getKey()).isEqualTo("key");
+  }
+
+  @Test
+  public void testGetDescription() {
+    assertThat(KEY.getDescription()).isEqualTo("description");
+  }
+
+  @Test
+  public void create_NoLengthConstraint() {
+    // We have a length constraint of 256-characters for TagKey. That constraint doesn't apply to
+    // LabelKey.
+    char[] chars = new char[300];
+    Arrays.fill(chars, 'k');
+    String key = new String(chars);
+    assertThat(LabelKey.create(key, "").getKey()).isEqualTo(key);
+  }
+
+  @Test
+  public void create_WithUnprintableChars() {
+    String key = "\2ab\3cd";
+    String description = "\4ef\5gh";
+    LabelKey labelKey = LabelKey.create(key, description);
+    assertThat(labelKey.getKey()).isEqualTo(key);
+    assertThat(labelKey.getDescription()).isEqualTo(description);
+  }
+
+  @Test
+  public void create_WithNonAsciiChars() {
+    String key = "键";
+    String description = "测试用键";
+    LabelKey nonAsciiKey = LabelKey.create(key, description);
+    assertThat(nonAsciiKey.getKey()).isEqualTo(key);
+    assertThat(nonAsciiKey.getDescription()).isEqualTo(description);
+  }
+
+  @Test
+  public void create_Empty() {
+    LabelKey emptyKey = LabelKey.create("", "");
+    assertThat(emptyKey.getKey()).isEmpty();
+    assertThat(emptyKey.getDescription()).isEmpty();
+  }
+
+  @Test
+  public void testLabelKeyEquals() {
+    new EqualsTester()
+        .addEqualityGroup(LabelKey.create("foo", ""), LabelKey.create("foo", ""))
+        .addEqualityGroup(LabelKey.create("foo", "description"))
+        .addEqualityGroup(LabelKey.create("bar", ""))
+        .testEquals();
+  }
+}
diff --git a/metrics/src/test/java/io/opencensus/metrics/LabelValueTest.java b/metrics/src/test/java/io/opencensus/metrics/LabelValueTest.java
new file mode 100644
index 00000000..e5526b2f
--- /dev/null
+++ b/metrics/src/test/java/io/opencensus/metrics/LabelValueTest.java
@@ -0,0 +1,74 @@
+/*
+ * Copyright 2018, 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;
+
+import static com.google.common.truth.Truth.assertThat;
+
+import com.google.common.testing.EqualsTester;
+import java.util.Arrays;
+import org.junit.Test;
+import org.junit.runner.RunWith;
+import org.junit.runners.JUnit4;
+
+/** Unit tests for {@link LabelValue}. */
+@RunWith(JUnit4.class)
+public class LabelValueTest {
+
+  private static final LabelValue VALUE = LabelValue.create("value");
+  private static final LabelValue UNSET = LabelValue.create(null);
+  private static final LabelValue EMPTY = LabelValue.create("");
+
+  @Test
+  public void testGetValue() {
+    assertThat(VALUE.getValue()).isEqualTo("value");
+    assertThat(UNSET.getValue()).isNull();
+    assertThat(EMPTY.getValue()).isEmpty();
+  }
+
+  @Test
+  public void create_NoLengthConstraint() {
+    // We have a length constraint of 256-characters for TagValue. That constraint doesn't apply to
+    // LabelValue.
+    char[] chars = new char[300];
+    Arrays.fill(chars, 'v');
+    String value = new String(chars);
+    assertThat(LabelValue.create(value).getValue()).isEqualTo(value);
+  }
+
+  @Test
+  public void create_WithUnprintableChars() {
+    String value = "\2ab\3cd";
+    assertThat(LabelValue.create(value).getValue()).isEqualTo(value);
+  }
+
+  @Test
+  public void create_WithNonAsciiChars() {
+    String value = "值";
+    LabelValue nonAsciiValue = LabelValue.create(value);
+    assertThat(nonAsciiValue.getValue()).isEqualTo(value);
+  }
+
+  @Test
+  public void testLabelValueEquals() {
+    new EqualsTester()
+        .addEqualityGroup(LabelValue.create("foo"), LabelValue.create("foo"))
+        .addEqualityGroup(UNSET)
+        .addEqualityGroup(EMPTY)
+        .addEqualityGroup(LabelValue.create("bar"))
+        .testEquals();
+  }
+}
diff --git a/settings.gradle b/settings.gradle
index b8128f71..67131598 100644
--- a/settings.gradle
+++ b/settings.gradle
@@ -20,8 +20,7 @@ include ":opencensus-contrib-grpc-util"
 include ":opencensus-contrib-http-util"
 include ":opencensus-contrib-log-correlation-stackdriver"
 include ":opencensus-contrib-monitored-resource-util"
-// TODO(songya): uncomment this once classes were added to Metrics library.
-//include ":opencensus-metrics"
+include ":opencensus-metrics"
 
 project(':opencensus-api').projectDir = "$rootDir/api" as File
 project(':opencensus-impl-core').projectDir = "$rootDir/impl_core" as File
@@ -49,8 +48,7 @@ project(':opencensus-exporter-trace-jaeger').projectDir = "$rootDir/exporters/tr
 project(':opencensus-exporter-stats-signalfx').projectDir = "$rootDir/exporters/stats/signalfx" as File
 project(':opencensus-exporter-stats-stackdriver').projectDir = "$rootDir/exporters/stats/stackdriver" as File
 project(':opencensus-exporter-stats-prometheus').projectDir = "$rootDir/exporters/stats/prometheus" as File
-// TODO(songya): uncomment this once classes were added to Metrics library.
-//project(':opencensus-metrics').projectDir = "$rootDir/metrics" as File
+project(':opencensus-metrics').projectDir = "$rootDir/metrics" as File
 
 
 // Java8 projects only