Gauge API : Add DoubleGauge Support (Part2) (#1496)

* Gauge API : Add DoubleGauge Support (Part2)

* Fix review comments

3 files changed, 306 insertions, 3 deletions

diff --git a/api/src/main/java/io/opencensus/metrics/DoubleGauge.java b/api/src/main/java/io/opencensus/metrics/DoubleGauge.java
new file mode 100644
index 00000000..91e131ec
--- /dev/null
+++ b/api/src/main/java/io/opencensus/metrics/DoubleGauge.java
@@ -0,0 +1,214 @@
+/*
+ * 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 io.opencensus.internal.Utils;
+import java.util.List;
+import javax.annotation.concurrent.ThreadSafe;
+
+/**
+ * Double Gauge metric, to report instantaneous measurement of a double value. Gauges can go both up
+ * and down. The gauges values can be negative.
+ *
+ * <p>Example 1: Create a Gauge with default labels.
+ *
+ * <pre>{@code
+ * class YourClass {
+ *
+ *   private static final MetricRegistry metricRegistry = Metrics.getMetricRegistry();
+ *
+ *   List<LabelKey> labelKeys = Arrays.asList(LabelKey.create("Name", "desc"));
+ *   // TODO(mayurkale): Plugs-in the DoubleGauge into the registry.
+ *   DoubleGauge gauge = metricRegistry.addDoubleGauge("queue_size",
+ *                       "Pending jobs", "1", labelKeys);
+ *
+ *   // It is recommended to keep a reference of a point for manual operations.
+ *   DoublePoint defaultPoint = gauge.getDefaultTimeSeries();
+ *
+ *   void doWork() {
+ *      // Your code here.
+ *      defaultPoint.add(10);
+ *   }
+ *
+ * }
+ * }</pre>
+ *
+ * <p>Example 2: You can also use labels(keys and values) to track different types of metric.
+ *
+ * <pre>{@code
+ * class YourClass {
+ *
+ *   private static final MetricRegistry metricRegistry = Metrics.getMetricRegistry();
+ *
+ *   List<LabelKey> labelKeys = Arrays.asList(LabelKey.create("Name", "desc"));
+ *   List<LabelValue> labelValues = Arrays.asList(LabelValue.create("Inbound"));
+ *
+ *   // TODO(mayurkale): Plugs-in the DoubleGauge into the registry.
+ *   DoubleGauge gauge = metricRegistry.addDoubleGauge("queue_size",
+ *                       "Pending jobs", "1", labelKeys);
+ *
+ *   // It is recommended to keep a reference of a point for manual operations.
+ *   DoublePoint inboundPoint = gauge.getOrCreateTimeSeries(labelValues);
+ *
+ *   void doSomeWork() {
+ *      // Your code here.
+ *      inboundPoint.set(15);
+ *   }
+ *
+ * }
+ * }</pre>
+ *
+ * @since 0.17
+ */
+@ThreadSafe
+public abstract class DoubleGauge {
+
+  /**
+   * Creates a {@code TimeSeries} and returns a {@code DoublePoint} if the specified {@code
+   * labelValues} is not already associated with this gauge, else returns an existing {@code
+   * DoublePoint}.
+   *
+   * <p>It is recommended to keep a reference to the DoublePoint instead of always calling this
+   * method for manual operations.
+   *
+   * @param labelValues the list of label values. The number of label values must be the same to
+   *     that of the label keys passed to {@link MetricRegistry#addDoubleGauge}.
+   * @return a {@code DoublePoint} the value of single gauge.
+   * @throws NullPointerException if {@code labelValues} is null OR any element of {@code
+   *     labelValues} is null.
+   * @throws IllegalArgumentException if number of {@code labelValues}s are not equal to the label
+   *     keys passed to {@link MetricRegistry#addDoubleGauge}.
+   * @since 0.17
+   */
+  public abstract DoublePoint getOrCreateTimeSeries(List<LabelValue> labelValues);
+
+  /**
+   * Returns a {@code DoublePoint} for a gauge with all labels not set, or default labels.
+   *
+   * @return a {@code DoublePoint} for a gauge with all labels not set, or default labels.
+   * @since 0.17
+   */
+  public abstract DoublePoint getDefaultTimeSeries();
+
+  /**
+   * Removes the {@code TimeSeries} from the gauge metric, if it is present. i.e. references to
+   * previous {@code DoublePoint} objects are invalid (not part of the metric).
+   *
+   * @param labelValues the list of label values.
+   * @throws NullPointerException if {@code labelValues} is null or any element of {@code
+   *     labelValues} is null.
+   * @since 0.17
+   */
+  public abstract void removeTimeSeries(List<LabelValue> labelValues);
+
+  /**
+   * Removes all {@code TimeSeries} from the gauge metric. i.e. references to all previous {@code
+   * DoublePoint} objects are invalid (not part of the metric).
+   *
+   * @since 0.17
+   */
+  public abstract void clear();
+
+  /**
+   * Returns the no-op implementation of the {@code DoubleGauge}.
+   *
+   * @return the no-op implementation of the {@code DoubleGauge}.
+   * @since 0.17
+   */
+  static DoubleGauge newNoopDoubleGauge(
+      String name, String description, String unit, List<LabelKey> labelKeys) {
+    return NoopDoubleGauge.create(name, description, unit, labelKeys);
+  }
+
+  /**
+   * The value of a single point in the Gauge.TimeSeries.
+   *
+   * @since 0.17
+   */
+  public abstract static class DoublePoint {
+
+    /**
+     * Adds the given value to the current value. The values can be negative.
+     *
+     * @param amt the value to add
+     * @since 0.17
+     */
+    public abstract void add(double amt);
+
+    /**
+     * Sets the given value.
+     *
+     * @param val the new value.
+     * @since 0.17
+     */
+    public abstract void set(double val);
+  }
+
+  /** No-op implementations of DoubleGauge class. */
+  private static final class NoopDoubleGauge extends DoubleGauge {
+    private final int labelKeysSize;
+
+    static NoopDoubleGauge create(
+        String name, String description, String unit, List<LabelKey> labelKeys) {
+      return new NoopDoubleGauge(name, description, unit, labelKeys);
+    }
+
+    /** Creates a new {@code NoopDoublePoint}. */
+    NoopDoubleGauge(String name, String description, String unit, List<LabelKey> labelKeys) {
+      Utils.checkNotNull(name, "name");
+      Utils.checkNotNull(description, "description");
+      Utils.checkNotNull(unit, "unit");
+      Utils.checkNotNull(labelKeys, "labelKeys should not be null.");
+      Utils.checkListElementNotNull(labelKeys, "labelKeys element should not be null.");
+      labelKeysSize = labelKeys.size();
+    }
+
+    @Override
+    public NoopDoublePoint getOrCreateTimeSeries(List<LabelValue> labelValues) {
+      Utils.checkNotNull(labelValues, "labelValues should not be null.");
+      Utils.checkListElementNotNull(labelValues, "labelValues element should not be null.");
+      Utils.checkArgument(labelKeysSize == labelValues.size(), "Incorrect number of labels.");
+      return NoopDoublePoint.INSTANCE;
+    }
+
+    @Override
+    public NoopDoublePoint getDefaultTimeSeries() {
+      return NoopDoublePoint.INSTANCE;
+    }
+
+    @Override
+    public void removeTimeSeries(List<LabelValue> labelValues) {
+      Utils.checkNotNull(labelValues, "labelValues should not be null.");
+    }
+
+    @Override
+    public void clear() {}
+
+    /** No-op implementations of DoublePoint class. */
+    private static final class NoopDoublePoint extends DoublePoint {
+      private static final NoopDoublePoint INSTANCE = new NoopDoublePoint();
+
+      private NoopDoublePoint() {}
+
+      @Override
+      public void add(double amt) {}
+
+      @Override
+      public void set(double val) {}
+    }
+  }
+}
diff --git a/api/src/main/java/io/opencensus/metrics/LongGauge.java b/api/src/main/java/io/opencensus/metrics/LongGauge.java
index 2294f0cf..42951d50 100644
--- a/api/src/main/java/io/opencensus/metrics/LongGauge.java
+++ b/api/src/main/java/io/opencensus/metrics/LongGauge.java
@@ -77,7 +77,7 @@ public abstract class LongGauge {
 
   /**
    * Creates a {@code TimeSeries} and returns a {@code LongPoint} if the specified {@code
-   * labelValues} is not already associated with this gauge, else returns a existing {@code
+   * labelValues} is not already associated with this gauge, else returns an existing {@code
    * LongPoint}.
    *
    * <p>It is recommended to keep a reference to the LongPoint instead of always calling this method
@@ -97,7 +97,7 @@ public abstract class LongGauge {
   /**
    * Returns a {@code LongPoint} for a gauge with all labels not set, or default labels.
    *
-   * @return a {@code LongPoint} the value of default gauge.
+   * @return a {@code LongPoint} for a gauge with all labels not set, or default labels.
    * @since 0.17
    */
   public abstract LongPoint getDefaultTimeSeries();
@@ -114,7 +114,8 @@ public abstract class LongGauge {
   public abstract void removeTimeSeries(List<LabelValue> labelValues);
 
   /**
-   * References to all previous {@code LongPoint} objects are invalid (not part of the metric).
+   * Removes all {@code TimeSeries} from the gauge metric. i.e. references to all previous {@code
+   * LongPoint} objects are invalid (not part of the metric).
    *
    * @since 0.17
    */
diff --git a/api/src/test/java/io/opencensus/metrics/DoubleGaugeTest.java b/api/src/test/java/io/opencensus/metrics/DoubleGaugeTest.java
new file mode 100644
index 00000000..5690bd44
--- /dev/null
+++ b/api/src/test/java/io/opencensus/metrics/DoubleGaugeTest.java
@@ -0,0 +1,88 @@
+/*
+ * 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 java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+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 DoubleGauge}. */
+@RunWith(JUnit4.class)
+public class DoubleGaugeTest {
+  @Rule public ExpectedException thrown = ExpectedException.none();
+
+  private static final String NAME = "name";
+  private static final String DESCRIPTION = "description";
+  private static final String UNIT = "1";
+  private static final List<LabelKey> LABEL_KEY =
+      Collections.singletonList(LabelKey.create("key", "key description"));
+  private static final List<LabelValue> LABEL_VALUES =
+      Collections.singletonList(LabelValue.create("value"));
+  private static final List<LabelKey> EMPTY_LABEL_KEYS = new ArrayList<LabelKey>();
+  private static final List<LabelValue> EMPTY_LABEL_VALUES = new ArrayList<LabelValue>();
+
+  // TODO(mayurkale): Add more tests, once DoubleGauge plugs-in into the registry.
+
+  @Test
+  public void noopGetOrCreateTimeSeries_WithNullLabelValues() {
+    DoubleGauge doubleGauge =
+        DoubleGauge.newNoopDoubleGauge(NAME, DESCRIPTION, UNIT, EMPTY_LABEL_KEYS);
+    thrown.expect(NullPointerException.class);
+    thrown.expectMessage("labelValues should not be null.");
+    doubleGauge.getOrCreateTimeSeries(null);
+  }
+
+  @Test
+  public void noopGetOrCreateTimeSeries_WithNullElement() {
+    List<LabelValue> labelValues = Collections.singletonList(null);
+    DoubleGauge doubleGauge = DoubleGauge.newNoopDoubleGauge(NAME, DESCRIPTION, UNIT, LABEL_KEY);
+    thrown.expect(NullPointerException.class);
+    thrown.expectMessage("labelValues element should not be null.");
+    doubleGauge.getOrCreateTimeSeries(labelValues);
+  }
+
+  @Test
+  public void noopGetOrCreateTimeSeries_WithInvalidLabelSize() {
+    DoubleGauge doubleGauge = DoubleGauge.newNoopDoubleGauge(NAME, DESCRIPTION, UNIT, LABEL_KEY);
+    thrown.expect(IllegalArgumentException.class);
+    thrown.expectMessage("Incorrect number of labels.");
+    doubleGauge.getOrCreateTimeSeries(EMPTY_LABEL_VALUES);
+  }
+
+  @Test
+  public void noopRemoveTimeSeries_WithNullLabelValues() {
+    DoubleGauge doubleGauge = DoubleGauge.newNoopDoubleGauge(NAME, DESCRIPTION, UNIT, LABEL_KEY);
+    thrown.expect(NullPointerException.class);
+    thrown.expectMessage("labelValues should not be null.");
+    doubleGauge.removeTimeSeries(null);
+  }
+
+  @Test
+  public void noopSameAs() {
+    DoubleGauge doubleGauge = DoubleGauge.newNoopDoubleGauge(NAME, DESCRIPTION, UNIT, LABEL_KEY);
+    assertThat(doubleGauge.getDefaultTimeSeries()).isSameAs(doubleGauge.getDefaultTimeSeries());
+    assertThat(doubleGauge.getDefaultTimeSeries())
+        .isSameAs(doubleGauge.getOrCreateTimeSeries(LABEL_VALUES));
+  }
+}