Fix Metric.update and add snippets for Metric class

google-cloud-examples/src/main/java/com/google/cloud/examples/logging/snippets/MetricSnippets.java

@@ -0,0 +1,134 @@
+/*
+ * Copyright 2016 Google Inc. All Rights Reserved.
+ *
+ * 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.
+ */
+
+/*
+ * EDITING INSTRUCTIONS
+ * This file is referenced in Metric's javadoc. Any change to this file should be reflected in
+ * Metric's javadoc.
+ */
+
+package com.google.cloud.examples.logging.snippets;
+
+import com.google.cloud.logging.Metric;
+
+import java.util.concurrent.ExecutionException;
+import java.util.concurrent.Future;
+
+/**
+ * This class contains a number of snippets for the {@link Metric} class.
+ */
+public class MetricSnippets {
+
+  private final Metric metric;
+
+  public MetricSnippets(Metric metric) {
+    this.metric = metric;
+  }
+
+  /**
+   * Example of getting the metric's latest information.
+   */
+  // [TARGET reload()]
+  public Metric reload() {
+    // [START reload]
+    Metric latestMetric = metric.reload();
+    if (latestMetric == null) {
+      // the metric was not found
+    }
+    // [END reload]
+    return latestMetric;
+  }
+
+  /**
+   * Example of asynchronously getting the metric's latest information.
+   */
+  // [TARGET reloadAsync()]
+  public Metric reloadAsync() throws ExecutionException, InterruptedException {
+    // [START reloadAsync]
+    Future<Metric> future = metric.reloadAsync();
+    // ...
+    Metric latestMetric = future.get();
+    if (latestMetric == null) {
+      // the metric was not found
+    }
+    // [END reloadAsync]
+    return latestMetric;
+  }
+
+  /**
+   * Example of updating the metric's information.
+   */
+  // [TARGET update()]
+  public Metric update() {
+    // [START update]
+    Metric updatedMetric = metric.toBuilder()
+        .description("A more detailed description")
+        .build()
+        .update();
+    // [END update]
+    return updatedMetric;
+  }
+
+  /**
+   * Example of asynchronously updating the metric's information.
+   */
+  // [TARGET updateAsync()]
+  public Metric updateAsync() throws ExecutionException, InterruptedException {
+    // [START updateAsync]
+    Future<Metric> future = metric.toBuilder()
+        .description("A more detailed description")
+        .build()
+        .updateAsync();
+    // ...
+    Metric updatedMetric = future.get();
+    // [END updateAsync]
+    return updatedMetric;
+  }
+
+  /**
+   * Example of deleting the metric.
+   */
+  // [TARGET delete()]
+  public boolean delete() {
+    // [START delete]
+    boolean deleted = metric.delete();
+    if (deleted) {
+      // the metric was deleted
+    } else {
+      // the metric was not found
+    }
+    // [END delete]
+    return deleted;
+  }
+
+  /**
+   * Example of asynchronously deleting the metric.
+   */
+  // [TARGET deleteAsync()]
+  public boolean deleteAsync() throws ExecutionException, InterruptedException {
+    // [START deleteAsync]
+    Future<Boolean> future = metric.deleteAsync();
+    // ...
+    boolean deleted = future.get();
+    if (deleted) {
+      // the metric was deleted
+    } else {
+      // the metric was not found
+    }
+    // [END deleteAsync]
+    return deleted;
+  }
+}

google-cloud-examples/src/test/java/com/google/cloud/examples/logging/snippets/ITLoggingSnippets.java

@@ -29,6 +29,7 @@
 import com.google.common.collect.Iterators;
 import com.google.common.collect.Sets;
 
+import org.junit.AfterClass;
 import org.junit.BeforeClass;
 import org.junit.Rule;
 import org.junit.Test;
@@ -45,11 +46,11 @@ public class ITLoggingSnippets {
   private static final String DATASET = "dataset";
   private static final Set<String> DESCRIPTOR_TYPES = ImmutableSet.of("gce_instance", "gae_app",
       "cloudsql_database", "api", "gcs_bucket", "global", "dataflow_step", "build",
-      "app_script_function", "dataproc_cluster", "ml_job", "bigquery_resource",
-      "crm_iam_policy_check", "container", "gke_cluster", "cloud_debugger_resource",
-      "http_load_balancer", "aws_ec2_instance", "client_auth_config_brand",
-      "client_auth_config_client", "logging_log", "logging_sink", "metric", "project",
-      "testservice_matrix", "service_account", "deployment", "dns_managed_zone");
+      "app_script_function", "dataproc_cluster", "ml_job", "bigquery_resource", "container",
+      "gke_cluster", "cloud_debugger_resource", "http_load_balancer", "aws_ec2_instance",
+      "client_auth_config_brand", "client_auth_config_client", "logging_log", "logging_sink",
+      "metric", "project", "testservice_matrix", "service_account", "deployment",
+      "dns_managed_zone");
 
   private static Logging logging;
   private static LoggingSnippets loggingSnippets;
@@ -67,6 +68,13 @@ public static void beforeClass() {
     loggingSnippets = new LoggingSnippets(logging);
   }
 
+  @AfterClass
+  public static void afterClass() throws Exception {
+    if (logging != null) {
+      logging.close();
+    }
+  }
+
   @Test
   public void testSink() throws ExecutionException, InterruptedException {
     String sinkName1 = RemoteLoggingHelper.formatForTest("sink_name1");

google-cloud-examples/src/test/java/com/google/cloud/examples/logging/snippets/ITMetricSnippets.java

@@ -0,0 +1,77 @@
+/*
+ * Copyright 2016 Google Inc. All Rights Reserved.
+ *
+ * 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 com.google.cloud.examples.logging.snippets;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertNotNull;
+import static org.junit.Assert.assertTrue;
+
+import com.google.cloud.logging.Logging;
+import com.google.cloud.logging.Metric;
+import com.google.cloud.logging.MetricInfo;
+import com.google.cloud.logging.testing.RemoteLoggingHelper;
+
+import org.junit.AfterClass;
+import org.junit.BeforeClass;
+import org.junit.Test;
+
+import java.util.concurrent.ExecutionException;
+
+public class ITMetricSnippets {
+
+  private static final String METRIC_NAME = RemoteLoggingHelper.formatForTest("it_metric_snippets");
+  private static final String METRIC_FILTER = "severity>=ERROR";
+  private static final String DESCRIPTION = "description";
+  private static final String UPDATED_DESCRIPTION = "A more detailed description";
+
+  private static Logging logging;
+  private static MetricSnippets metricSnippets;
+
+  @BeforeClass
+  public static void beforeClass() {
+    RemoteLoggingHelper helper = RemoteLoggingHelper.create();
+    logging = helper.options().service();
+    MetricInfo metricInfo = MetricInfo.builder(METRIC_NAME, METRIC_FILTER)
+        .description(DESCRIPTION)
+        .build();
+    metricSnippets = new MetricSnippets(logging.create(metricInfo));
+  }
+
+  @AfterClass
+  public static void afterClass() throws Exception {
+    if (logging != null) {
+      logging.close();
+    }
+  }
+
+  @Test
+  public void testMetric() throws InterruptedException, ExecutionException {
+    Metric metric = metricSnippets.reload();
+    assertNotNull(metric);
+    Metric updatedMetric = metricSnippets.update();
+    assertEquals(UPDATED_DESCRIPTION, updatedMetric.description());
+    updatedMetric = metricSnippets.reloadAsync();
+    assertNotNull(updatedMetric);
+    assertEquals(UPDATED_DESCRIPTION, updatedMetric.description());
+    metric.update();
+    updatedMetric = metricSnippets.updateAsync();
+    assertEquals(UPDATED_DESCRIPTION, updatedMetric.description());
+    assertTrue(metricSnippets.delete());
+    assertFalse(metricSnippets.deleteAsync());
+  }
+}

google-cloud-logging/src/main/java/com/google/cloud/logging/Metric.java

@@ -119,6 +119,16 @@ public Logging logging() {
   /**
    * Deletes this metric.
    *
+   * <p>Example of deleting the metric.
+   * <pre> {@code
+   * boolean deleted = metric.delete();
+   * if (deleted) {
+   *   // the metric was deleted
+   * } else {
+   *   // the metric was not found
+   * }
+   * }</pre>
+   *
    * @return {@code true} if the metric was deleted, {@code false} if it was not found
    * @throws LoggingException upon failure
    */
@@ -131,6 +141,18 @@ public boolean delete() {
    * consume the result. {@link Future#get()} returns {@code true} if the metric was deleted,
    * {@code false} if it was not found.
    *
+   * <p>Example of asynchronously deleting the metric.
+   * <pre> {@code
+   * Future<Boolean> future = metric.deleteAsync();
+   * // ...
+   * boolean deleted = future.get();
+   * if (deleted) {
+   *   // the metric was deleted
+   * } else {
+   *   // the metric was not found
+   * }
+   * }</pre>
+   *
    * @throws LoggingException upon failure
    */
   public Future<Boolean> deleteAsync() {
@@ -140,6 +162,14 @@ public Future<Boolean> deleteAsync() {
   /**
    * Fetches current metric's latest information. Returns {@code null} if the metric does not exist.
    *
+   * <p>Example of getting the metric's latest information.
+   * <pre> {@code
+   * Metric latestMetric = metric.reload();
+   * if (latestMetric == null) {
+   *   // the metric was not found
+   * }
+   * }</pre>
+   *
    * @return a {@code Metric} object with latest information or {@code null} if not found
    * @throws LoggingException upon failure
    */
@@ -152,6 +182,16 @@ public Metric reload() {
    * {@code Future} object to consume the result. {@link Future#get()} returns a {@code Metric}
    * object with latest information or {@code null} if not found.
    *
+   * <p>Example of asynchronously getting the metric's latest information.
+   * <pre> {@code
+   * Future<Metric> future = metric.reloadAsync();
+   * // ...
+   * Metric latestMetric = future.get();
+   * if (latestMetric == null) {
+   *   // the metric was not found
+   * }
+   * }</pre>
+   *
    * @throws LoggingException upon failure
    */
   public Future<Metric> reloadAsync() {
@@ -161,22 +201,40 @@ public Future<Metric> reloadAsync() {
   /**
    * Updates current metric. If the metric does not exist, it is created.
    *
+   * <p>Example of updating the metric's information.
+   * <pre> {@code
+   * Metric updatedMetric = metric.toBuilder()
+   *     .description("A more detailed description")
+   *     .build()
+   *     .update();
+   * }</pre>
+   *
    * @return a {@code Metric} object with updated information
    * @throws LoggingException upon failure
    */
-  public Metric update(MetricInfo metricInfo) {
-    return logging.update(metricInfo);
+  public Metric update() {
+    return logging.update(this);
   }
 
   /**
    * Sends a request to update current metric. If the metric does not exist, it is created. This
    * method returns a {@code Future} object to consume the result. {@link Future#get()} returns a
    * {@code Metric} object with updated information.
    *
+   * <p>Example of asynchronously updating the metric's information.
+   * <pre> {@code
+   * Future<Metric> future = metric.toBuilder()
+   *     .description("A more detailed description")
+   *     .build()
+   *     .updateAsync();
+   * // ...
+   * Metric updatedMetric = future.get();
+   * }</pre>
+   *
    * @throws LoggingException upon failure
    */
-  public Future<Metric> updateAsync(MetricInfo metricInfo) {
-    return logging.updateAsync(metricInfo);
+  public Future<Metric> updateAsync() {
+    return logging.updateAsync(this);
   }
 
   private void readObject(ObjectInputStream input) throws IOException, ClassNotFoundException {

google-cloud-logging/src/test/java/com/google/cloud/logging/BaseSystemTest.java

@@ -245,10 +245,11 @@ public void testCreateGetUpdateAndDeleteMetric() {
     assertEquals("severity>=ERROR", metric.filter());
     assertEquals("description", metric.description());
     assertEquals(metric, logging().getMetric(name));
-    metric = metric.update(metric.toBuilder()
+    metric = metric.toBuilder()
         .description("newDescription")
         .filter("severity>=WARNING")
-        .build());
+        .build()
+        .update();
     assertEquals(name, metric.name());
     assertEquals("severity>=WARNING", metric.filter());
     assertEquals("newDescription", metric.description());
@@ -267,10 +268,11 @@ public void testCreateGetUpdateAndDeleteMetricAsync()
     assertEquals("severity>=ERROR", metric.filter());
     assertEquals("description", metric.description());
     assertEquals(metric, logging().getMetricAsync(name).get());
-    metric = metric.updateAsync(metric.toBuilder()
+    metric = metric.toBuilder()
         .description("newDescription")
         .filter("severity>=WARNING")
-        .build()).get();
+        .build()
+        .updateAsync().get();
     assertEquals(name, metric.name());
     assertEquals("severity>=WARNING", metric.filter());
     assertEquals("newDescription", metric.description());