From 2a4b105dcebe0a55d5a5920305aa38e0bf7cba3f Mon Sep 17 00:00:00 2001
From: Marco Ziccardi <marco.ziccard@gmail.com>
Date: Thu, 1 Sep 2016 12:29:59 +0200
Subject: [PATCH 1/3] Remove unnecessary MetricInfo parameter for
 Metric.update(Async)

---
 .../java/com/google/cloud/logging/Metric.java  |  8 ++++----
 .../google/cloud/logging/BaseSystemTest.java   | 10 ++++++----
 .../com/google/cloud/logging/MetricTest.java   | 18 ++++++++++--------
 3 files changed, 20 insertions(+), 16 deletions(-)

diff --git a/google-cloud-logging/src/main/java/com/google/cloud/logging/Metric.java b/google-cloud-logging/src/main/java/com/google/cloud/logging/Metric.java
index 57d6c572de04..fa7913fe7f68 100644
--- a/google-cloud-logging/src/main/java/com/google/cloud/logging/Metric.java
+++ b/google-cloud-logging/src/main/java/com/google/cloud/logging/Metric.java
@@ -164,8 +164,8 @@ public Future<Metric> reloadAsync() {
    * @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);
   }
 
   /**
@@ -175,8 +175,8 @@ public Metric update(MetricInfo metricInfo) {
    *
    * @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 {
diff --git a/google-cloud-logging/src/test/java/com/google/cloud/logging/BaseSystemTest.java b/google-cloud-logging/src/test/java/com/google/cloud/logging/BaseSystemTest.java
index 6ee199731d8e..06169745a83f 100644
--- a/google-cloud-logging/src/test/java/com/google/cloud/logging/BaseSystemTest.java
+++ b/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());
diff --git a/google-cloud-logging/src/test/java/com/google/cloud/logging/MetricTest.java b/google-cloud-logging/src/test/java/com/google/cloud/logging/MetricTest.java
index 31a51b2f35c0..839745ca7283 100644
--- a/google-cloud-logging/src/test/java/com/google/cloud/logging/MetricTest.java
+++ b/google-cloud-logging/src/test/java/com/google/cloud/logging/MetricTest.java
@@ -139,12 +139,13 @@ public void testReloadAsyncNull() throws ExecutionException, InterruptedExceptio
   public void testUpdate() {
     initializeExpectedMetric(2);
     MetricInfo updatedInfo = METRIC_INFO.toBuilder().filter(NEW_FILTER).build();
-    Metric expectedMetric = new Metric(serviceMockReturnsOptions, new MetricInfo.BuilderImpl(updatedInfo));
-    expect(logging.options()).andReturn(mockOptions);
-    expect(logging.update(updatedInfo)).andReturn(expectedMetric);
+    Metric expectedMetric =
+        new Metric(serviceMockReturnsOptions, new MetricInfo.BuilderImpl(updatedInfo));
+    expect(logging.options()).andReturn(mockOptions).times(2);
+    expect(logging.update(expectedMetric)).andReturn(expectedMetric);
     replay(logging);
     initializeMetric();
-    Metric updatedMetric = metric.update(updatedInfo);
+    Metric updatedMetric = metric.toBuilder().filter(NEW_FILTER).build().update();
     compareMetric(expectedMetric, updatedMetric);
   }
 
@@ -152,12 +153,13 @@ public void testUpdate() {
   public void testUpdateAsync() throws ExecutionException, InterruptedException {
     initializeExpectedMetric(2);
     MetricInfo updatedInfo = METRIC_INFO.toBuilder().filter(NEW_FILTER).build();
-    Metric expectedMetric = new Metric(serviceMockReturnsOptions, new MetricInfo.BuilderImpl(updatedInfo));
-    expect(logging.options()).andReturn(mockOptions);
-    expect(logging.updateAsync(updatedInfo)).andReturn(Futures.immediateFuture(expectedMetric));
+    Metric expectedMetric =
+        new Metric(serviceMockReturnsOptions, new MetricInfo.BuilderImpl(updatedInfo));
+    expect(logging.options()).andReturn(mockOptions).times(2);
+    expect(logging.updateAsync(expectedMetric)).andReturn(Futures.immediateFuture(expectedMetric));
     replay(logging);
     initializeMetric();
-    Metric updatedMetric = metric.updateAsync(updatedInfo).get();
+    Metric updatedMetric = metric.toBuilder().filter(NEW_FILTER).build().updateAsync().get();
     compareMetric(expectedMetric, updatedMetric);
   }
 

From baf593666cccac59bff61800786b9718fb700ca7 Mon Sep 17 00:00:00 2001
From: Marco Ziccardi <marco.ziccard@gmail.com>
Date: Thu, 1 Sep 2016 13:06:11 +0200
Subject: [PATCH 2/3] Update snippets script to support final method parameters

---
 utilities/add_snippets_to_file.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/utilities/add_snippets_to_file.py b/utilities/add_snippets_to_file.py
index 94d388c72dfd..1d8f9eaf11ab 100644
--- a/utilities/add_snippets_to_file.py
+++ b/utilities/add_snippets_to_file.py
@@ -93,7 +93,7 @@ def parse_methods(cls, data, class_name):
                             method_name, ', '.join(
                                 [parameter.signature_type for parameter in parameters]))
                         regex = '{}\(\s*{}\)'.format(re.escape(method_name),
-                            ',\s+'.join(['{}\s+{}'.format(
+                            ',\s+'.join(['(final\s+)?{}\s+{}'.format(
                                 re.escape(parameter.complete_type), re.escape(parameter.name))
                             for parameter in parameters]))
                         method = cls(method_name, parameters, signature, regex)

From 1f166098a480227f06eeae7386706637a9383271 Mon Sep 17 00:00:00 2001
From: Marco Ziccardi <marco.ziccard@gmail.com>
Date: Thu, 1 Sep 2016 13:09:01 +0200
Subject: [PATCH 3/3] Add snippets to Metric's javadoc, MetricSnippets class
 and tests

---
 .../logging/snippets/MetricSnippets.java      | 134 ++++++++++++++++++
 .../logging/snippets/ITLoggingSnippets.java   |  18 ++-
 .../logging/snippets/ITMetricSnippets.java    |  77 ++++++++++
 .../java/com/google/cloud/logging/Metric.java |  58 ++++++++
 4 files changed, 282 insertions(+), 5 deletions(-)
 create mode 100644 google-cloud-examples/src/main/java/com/google/cloud/examples/logging/snippets/MetricSnippets.java
 create mode 100644 google-cloud-examples/src/test/java/com/google/cloud/examples/logging/snippets/ITMetricSnippets.java

diff --git a/google-cloud-examples/src/main/java/com/google/cloud/examples/logging/snippets/MetricSnippets.java b/google-cloud-examples/src/main/java/com/google/cloud/examples/logging/snippets/MetricSnippets.java
new file mode 100644
index 000000000000..48c6193c16fb
--- /dev/null
+++ b/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;
+  }
+}
diff --git a/google-cloud-examples/src/test/java/com/google/cloud/examples/logging/snippets/ITLoggingSnippets.java b/google-cloud-examples/src/test/java/com/google/cloud/examples/logging/snippets/ITLoggingSnippets.java
index dea50e532726..7bcd543eb32e 100644
--- a/google-cloud-examples/src/test/java/com/google/cloud/examples/logging/snippets/ITLoggingSnippets.java
+++ b/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");
diff --git a/google-cloud-examples/src/test/java/com/google/cloud/examples/logging/snippets/ITMetricSnippets.java b/google-cloud-examples/src/test/java/com/google/cloud/examples/logging/snippets/ITMetricSnippets.java
new file mode 100644
index 000000000000..847642f80996
--- /dev/null
+++ b/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());
+  }
+}
diff --git a/google-cloud-logging/src/main/java/com/google/cloud/logging/Metric.java b/google-cloud-logging/src/main/java/com/google/cloud/logging/Metric.java
index fa7913fe7f68..c5e3e6e00ff4 100644
--- a/google-cloud-logging/src/main/java/com/google/cloud/logging/Metric.java
+++ b/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,6 +201,14 @@ 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
    */
@@ -173,6 +221,16 @@ public Metric update() {
    * 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() {