From fbd8c4960b371794b8ada8d34cb19b00a73365ef Mon Sep 17 00:00:00 2001
From: Marco Ziccardi <marco.ziccard@gmail.com>
Date: Thu, 1 Sep 2016 14:29:18 +0200
Subject: [PATCH] Add snippets to Sink's javadoc, SinkSnippets class and tests

---
 .../logging/snippets/SinkSnippets.java        | 134 ++++++++++++++++++
 .../logging/snippets/ITSinkSnippets.java      |  78 ++++++++++
 .../java/com/google/cloud/logging/Sink.java   |  58 ++++++++
 3 files changed, 270 insertions(+)
 create mode 100644 google-cloud-examples/src/main/java/com/google/cloud/examples/logging/snippets/SinkSnippets.java
 create mode 100644 google-cloud-examples/src/test/java/com/google/cloud/examples/logging/snippets/ITSinkSnippets.java

diff --git a/google-cloud-examples/src/main/java/com/google/cloud/examples/logging/snippets/SinkSnippets.java b/google-cloud-examples/src/main/java/com/google/cloud/examples/logging/snippets/SinkSnippets.java
new file mode 100644
index 000000000000..4383d07b4f62
--- /dev/null
+++ b/google-cloud-examples/src/main/java/com/google/cloud/examples/logging/snippets/SinkSnippets.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 Sink's javadoc. Any change to this file should be reflected in Sink's
+ * javadoc.
+ */
+
+package com.google.cloud.examples.logging.snippets;
+
+import com.google.cloud.logging.Sink;
+
+import java.util.concurrent.ExecutionException;
+import java.util.concurrent.Future;
+
+/**
+ * This class contains a number of snippets for the {@link Sink} class.
+ */
+public class SinkSnippets {
+
+  private final Sink sink;
+
+  public SinkSnippets(Sink sink) {
+    this.sink = sink;
+  }
+
+  /**
+   * Example of getting the sink's latest information.
+   */
+  // [TARGET reload()]
+  public Sink reload() {
+    // [START reload]
+    Sink latestSink = sink.reload();
+    if (latestSink == null) {
+      // the sink was not found
+    }
+    // [END reload]
+    return latestSink;
+  }
+
+  /**
+   * Example of asynchronously getting the sink's latest information.
+   */
+  // [TARGET reloadAsync()]
+  public Sink reloadAsync() throws ExecutionException, InterruptedException {
+    // [START reloadAsync]
+    Future<Sink> future = sink.reloadAsync();
+    // ...
+    Sink latestSink = future.get();
+    if (latestSink == null) {
+      // the sink was not found
+    }
+    // [END reloadAsync]
+    return latestSink;
+  }
+
+  /**
+   * Example of updating the sink's information.
+   */
+  // [TARGET update()]
+  public Sink update() {
+    // [START update]
+    Sink updatedSink = sink.toBuilder()
+        .filter("severity<=ERROR")
+        .build()
+        .update();
+    // [END update]
+    return updatedSink;
+  }
+
+  /**
+   * Example of asynchronously updating the sink's information.
+   */
+  // [TARGET updateAsync()]
+  public Sink updateAsync() throws ExecutionException, InterruptedException {
+    // [START updateAsync]
+    Future<Sink> future = sink.toBuilder()
+        .filter("severity<=ERROR")
+        .build()
+        .updateAsync();
+    // ...
+    Sink updatedSink = future.get();
+    // [END updateAsync]
+    return updatedSink;
+  }
+
+  /**
+   * Example of deleting the sink.
+   */
+  // [TARGET delete()]
+  public boolean delete() {
+    // [START delete]
+    boolean deleted = sink.delete();
+    if (deleted) {
+      // the sink was deleted
+    } else {
+      // the sink was not found
+    }
+    // [END delete]
+    return deleted;
+  }
+
+  /**
+   * Example of asynchronously deleting the sink.
+   */
+  // [TARGET deleteAsync()]
+  public boolean deleteAsync() throws ExecutionException, InterruptedException {
+    // [START deleteAsync]
+    Future<Boolean> future = sink.deleteAsync();
+    // ...
+    boolean deleted = future.get();
+    if (deleted) {
+      // the sink was deleted
+    } else {
+      // the sink was not found
+    }
+    // [END deleteAsync]
+    return deleted;
+  }
+}
diff --git a/google-cloud-examples/src/test/java/com/google/cloud/examples/logging/snippets/ITSinkSnippets.java b/google-cloud-examples/src/test/java/com/google/cloud/examples/logging/snippets/ITSinkSnippets.java
new file mode 100644
index 000000000000..c390941fc8ba
--- /dev/null
+++ b/google-cloud-examples/src/test/java/com/google/cloud/examples/logging/snippets/ITSinkSnippets.java
@@ -0,0 +1,78 @@
+/*
+ * 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.Sink;
+import com.google.cloud.logging.SinkInfo;
+import com.google.cloud.logging.SinkInfo.Destination;
+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 ITSinkSnippets {
+
+  private static final String SINK_NAME = RemoteLoggingHelper.formatForTest("it_sink_snippets");
+  private static final String SINK_FILTER = "severity>=ERROR";
+  private static final String UPDATED_SINK_FILTER = "severity<=ERROR";
+  private static final String DESTINATION = "dataset";
+
+  private static Logging logging;
+  private static SinkSnippets sinkSnippets;
+
+  @BeforeClass
+  public static void beforeClass() {
+    RemoteLoggingHelper helper = RemoteLoggingHelper.create();
+    logging = helper.options().service();
+    SinkInfo sinkInfo = SinkInfo.builder(SINK_NAME, Destination.DatasetDestination.of(DESTINATION))
+        .filter(SINK_FILTER)
+        .build();
+    sinkSnippets = new SinkSnippets(logging.create(sinkInfo));
+  }
+
+  @AfterClass
+  public static void afterClass() throws Exception {
+    if (logging != null) {
+      logging.close();
+    }
+  }
+
+  @Test
+  public void testSink() throws InterruptedException, ExecutionException {
+    Sink sink = sinkSnippets.reload();
+    assertNotNull(sink);
+    Sink updatedSink = sinkSnippets.update();
+    assertEquals(UPDATED_SINK_FILTER, updatedSink.filter());
+    updatedSink = sinkSnippets.reloadAsync();
+    assertNotNull(updatedSink);
+    assertEquals(UPDATED_SINK_FILTER, updatedSink.filter());
+    sink.update();
+    updatedSink = sinkSnippets.updateAsync();
+    assertEquals(UPDATED_SINK_FILTER, updatedSink.filter());
+    assertTrue(sinkSnippets.delete());
+    assertFalse(sinkSnippets.deleteAsync());
+  }
+}
diff --git a/google-cloud-logging/src/main/java/com/google/cloud/logging/Sink.java b/google-cloud-logging/src/main/java/com/google/cloud/logging/Sink.java
index 78615ce0028d..4a2aede6b62a 100644
--- a/google-cloud-logging/src/main/java/com/google/cloud/logging/Sink.java
+++ b/google-cloud-logging/src/main/java/com/google/cloud/logging/Sink.java
@@ -131,6 +131,16 @@ public Logging logging() {
   /**
    * Deletes this sink.
    *
+   * <p>Example of deleting the sink.
+   * <pre> {@code
+   * boolean deleted = sink.delete();
+   * if (deleted) {
+   *   // the sink was deleted
+   * } else {
+   *   // the sink was not found
+   * }
+   * }</pre>
+   *
    * @return {@code true} if the sink was deleted, {@code false} if it was not found
    * @throws LoggingException upon failure
    */
@@ -143,6 +153,18 @@ public boolean delete() {
    * the result. {@link Future#get()} returns {@code true} if the sink was deleted, {@code false}
    * if it was not found.
    *
+   * <p>Example of asynchronously deleting the sink.
+   * <pre> {@code
+   * Future<Boolean> future = sink.deleteAsync();
+   * // ...
+   * boolean deleted = future.get();
+   * if (deleted) {
+   *   // the sink was deleted
+   * } else {
+   *   // the sink was not found
+   * }
+   * }</pre>
+   *
    * @throws LoggingException upon failure
    */
   public Future<Boolean> deleteAsync() {
@@ -152,6 +174,14 @@ public Future<Boolean> deleteAsync() {
   /**
    * Fetches current sink's latest information. Returns {@code null} if the sink does not exist.
    *
+   * <p>Example of getting the sink's latest information.
+   * <pre> {@code
+   * Sink latestSink = sink.reload();
+   * if (latestSink == null) {
+   *   // the sink was not found
+   * }
+   * }</pre>
+   *
    * @return a {@code Sink} object with latest information or {@code null} if not found
    * @throws LoggingException upon failure
    */
@@ -164,6 +194,16 @@ public Sink reload() {
    * {@code Future} object to consume the result. {@link Future#get()} returns a {@code Sink} object
    * with latest information or {@code null} if not found.
    *
+   * <p>Example of asynchronously getting the sink's latest information.
+   * <pre> {@code
+   * Future<Sink> future = sink.reloadAsync();
+   * // ...
+   * Sink latestSink = future.get();
+   * if (latestSink == null) {
+   *   // the sink was not found
+   * }
+   * }</pre>
+   *
    * @throws LoggingException upon failure
    */
   public Future<Sink> reloadAsync() {
@@ -173,6 +213,14 @@ public Future<Sink> reloadAsync() {
   /**
    * Updates current sink. If the sink does not exist, it is created.
    *
+   * <p>Example of updating the sink's information.
+   * <pre> {@code
+   * Sink updatedSink = sink.toBuilder()
+   *     .filter("severity<=ERROR")
+   *     .build()
+   *     .update();
+   * }</pre>
+   *
    * @return a {@code Sink} object with updated information
    * @throws LoggingException upon failure
    */
@@ -185,6 +233,16 @@ public Sink update() {
    * returns a {@code Future} object to consume the result. {@link Future#get()} returns a
    * {@code Sink} object with updated information.
    *
+   * <p>Example of asynchronously updating the sink's information.
+   * <pre> {@code
+   * Future<Sink> future = sink.toBuilder()
+   *     .filter("severity<=ERROR")
+   *     .build()
+   *     .updateAsync();
+   * // ...
+   * Sink updatedSink = future.get();
+   * }</pre>
+   *
    * @throws LoggingException upon failure
    */
   public Future<Sink> updateAsync() {