fix: improve information on CancellationException for LROs

gax-java/gax-grpc/src/test/java/com/google/api/gax/grpc/ChannelPoolTest.java

@@ -43,6 +43,7 @@
 import com.google.api.gax.rpc.StreamController;
 import com.google.api.gax.rpc.UnaryCallSettings;
 import com.google.api.gax.rpc.UnaryCallable;
+import com.google.api.gax.util.FakeLogHandler;
 import com.google.common.base.Preconditions;
 import com.google.common.collect.ImmutableList;
 import com.google.common.collect.Lists;
@@ -66,9 +67,6 @@
 import java.util.concurrent.ScheduledFuture;
 import java.util.concurrent.TimeUnit;
 import java.util.concurrent.atomic.AtomicInteger;
-import java.util.logging.Handler;
-import java.util.logging.LogRecord;
-import java.util.stream.Collectors;
 import org.junit.After;
 import org.junit.Assert;
 import org.junit.Test;
@@ -717,23 +715,4 @@ public void testDoubleRelease() throws Exception {
       ChannelPool.LOG.removeHandler(logHandler);
     }
   }
-
-  private static class FakeLogHandler extends Handler {
-    List<LogRecord> records = new ArrayList<>();
-
-    @Override
-    public void publish(LogRecord record) {
-      records.add(record);
-    }
-
-    @Override
-    public void flush() {}
-
-    @Override
-    public void close() throws SecurityException {}
-
-    List<String> getAllMessages() {
-      return records.stream().map(LogRecord::getMessage).collect(Collectors.toList());
-    }
-  }
 }

gax-java/gax/pom.xml

@@ -76,6 +76,7 @@
                 <include>com/google/api/gax/core/**</include>
                 <include>com/google/api/gax/rpc/testing/**</include>
                 <include>com/google/api/gax/rpc/mtls/**</include>
+                <include>com/google/api/gax/util/**</include>
               </includes>
             </configuration>
           </execution>

gax-java/gax/src/main/java/com/google/api/gax/longrunning/OperationTimedPollAlgorithm.java

@@ -35,14 +35,23 @@
 import com.google.api.gax.retrying.ExponentialRetryAlgorithm;
 import com.google.api.gax.retrying.RetrySettings;
 import com.google.api.gax.retrying.TimedAttemptSettings;
+import com.google.common.annotations.VisibleForTesting;
 import java.util.concurrent.CancellationException;
+import java.util.logging.Level;
+import java.util.logging.Logger;
 
 /**
  * Operation timed polling algorithm, which uses exponential backoff factor for determining when the
  * next polling operation should be executed. If the polling exceeds the total timeout this
  * algorithm cancels polling.
  */
 public class OperationTimedPollAlgorithm extends ExponentialRetryAlgorithm {
+
+  public static Logger LOGGER = Logger.getLogger(OperationTimedPollAlgorithm.class.getName());
+
+  public static final String LRO_TROUBLESHOOTING_LINK =
+      "https://github.com/googleapis/google-cloud-java#lro-timeouts";
+
   /**
    * Creates the polling algorithm, using the default {@code NanoClock} for time computations.
    *
@@ -77,6 +86,13 @@ public boolean shouldRetry(TimedAttemptSettings nextAttemptSettings)
     if (super.shouldRetry(nextAttemptSettings)) {
       return true;
     }
+    if (LOGGER.isLoggable(Level.WARNING)) {
+      LOGGER.log(
+          Level.WARNING,
+          "The task has been cancelled. Please refer to "
+              + LRO_TROUBLESHOOTING_LINK
+              + " for more information");
+    }
     throw new CancellationException();
   }
 

gax-java/gax/src/test/java/com/google/api/gax/util/FakeLogHandler.java

@@ -0,0 +1,59 @@
+/*
+ * Copyright 2017 Google LLC
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are
+ * met:
+ *
+ *     * Redistributions of source code must retain the above copyright
+ * notice, this list of conditions and the following disclaimer.
+ *     * Redistributions in binary form must reproduce the above
+ * copyright notice, this list of conditions and the following disclaimer
+ * in the documentation and/or other materials provided with the
+ * distribution.
+ *     * Neither the name of Google LLC nor the names of its
+ * contributors may be used to endorse or promote products derived from
+ * this software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+package com.google.api.gax.util;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.logging.Handler;
+import java.util.logging.LogRecord;
+import java.util.stream.Collectors;
+
+/*
+ * Convenience class that stores the log entries produced by any logger
+ * It can then be inspected - its entries are a list log records
+ */
+public class FakeLogHandler extends Handler {
+  List<LogRecord> records = new ArrayList<>();
+
+  @Override
+  public void publish(LogRecord record) {
+    records.add(record);
+  }
+
+  @Override
+  public void flush() {}
+
+  @Override
+  public void close() throws SecurityException {}
+
+  public List<String> getAllMessages() {
+    return records.stream().map(LogRecord::getMessage).collect(Collectors.toList());
+  }
+}

showcase/gapic-showcase/src/test/java/com/google/showcase/v1beta1/it/ITLongRunningOperation.java

@@ -16,10 +16,13 @@
 package com.google.showcase.v1beta1.it;
 
 import static com.google.common.truth.Truth.assertThat;
+import static org.junit.Assert.assertEquals;
 import static org.junit.Assert.assertThrows;
 
 import com.google.api.gax.longrunning.OperationFuture;
+import com.google.api.gax.longrunning.OperationTimedPollAlgorithm;
 import com.google.api.gax.retrying.RetrySettings;
+import com.google.api.gax.util.FakeLogHandler;
 import com.google.protobuf.Timestamp;
 import com.google.showcase.v1beta1.EchoClient;
 import com.google.showcase.v1beta1.WaitMetadata;
@@ -28,6 +31,7 @@
 import com.google.showcase.v1beta1.it.util.TestClientInitializer;
 import java.util.concurrent.CancellationException;
 import java.util.concurrent.TimeUnit;
+import org.junit.Before;
 import org.junit.Test;
 import org.threeten.bp.Duration;
 import org.threeten.bp.Instant;
@@ -39,6 +43,13 @@
  */
 public class ITLongRunningOperation {
 
+  FakeLogHandler logHandler;
+
+  @Before
+  public void setUp() {
+    logHandler = new FakeLogHandler();
+  }
+
   @Test
   public void testGRPC_LROSuccessfulResponse_doesNotExceedTotalTimeout() throws Exception {
     RetrySettings initialUnaryRetrySettings =
@@ -121,6 +132,7 @@ public void testHttpJson_LROSuccessfulResponse_doesNotExceedTotalTimeout() throw
   @Test
   public void testGRPC_LROUnsuccessfulResponse_exceedsTotalTimeout_throwsDeadlineExceededException()
       throws Exception {
+    OperationTimedPollAlgorithm.LOGGER.addHandler(logHandler);
     RetrySettings initialUnaryRetrySettings =
         RetrySettings.newBuilder()
             .setInitialRpcTimeout(Duration.ofMillis(5000L))
@@ -149,6 +161,9 @@ public void testGRPC_LROUnsuccessfulResponse_exceedsTotalTimeout_throwsDeadlineE
       assertThrows(CancellationException.class, operationFuture::get);
       int attemptCount = operationFuture.getPollingFuture().getAttemptSettings().getAttemptCount();
       assertThat(attemptCount).isGreaterThan(1);
+      assertEquals(1, logHandler.getAllMessages().size());
+      assertThat(logHandler.getAllMessages().get(0))
+          .contains(OperationTimedPollAlgorithm.LRO_TROUBLESHOOTING_LINK);
     } finally {
       grpcClient.close();
       grpcClient.awaitTermination(
@@ -160,6 +175,7 @@ public void testGRPC_LROUnsuccessfulResponse_exceedsTotalTimeout_throwsDeadlineE
   public void
       testHttpJson_LROUnsuccessfulResponse_exceedsTotalTimeout_throwsDeadlineExceededException()
           throws Exception {
+    OperationTimedPollAlgorithm.LOGGER.addHandler(logHandler);
     RetrySettings initialUnaryRetrySettings =
         RetrySettings.newBuilder()
             .setInitialRpcTimeout(Duration.ofMillis(5000L))
@@ -188,6 +204,9 @@ public void testGRPC_LROUnsuccessfulResponse_exceedsTotalTimeout_throwsDeadlineE
       assertThrows(CancellationException.class, operationFuture::get);
       int attemptCount = operationFuture.getPollingFuture().getAttemptSettings().getAttemptCount();
       assertThat(attemptCount).isGreaterThan(1);
+      assertEquals(1, logHandler.getAllMessages().size());
+      assertThat(logHandler.getAllMessages().get(0))
+          .contains(OperationTimedPollAlgorithm.LRO_TROUBLESHOOTING_LINK);
     } finally {
       httpjsonClient.close();
       httpjsonClient.awaitTermination(