feat(gax,gapic-generator-java): retry start upload call and rename ResumableUploadCallSettings to ResumableUploadOptions (#14511)

## Summary
- Rename `ResumableUploadCallSettings` to `ResumableUploadOptions` and
make it a per-call option (`chunkSize`, `globalTimeout`) instead of a
method-level setting.
- Use standard `UnaryCallSettings<RequestT, ResponseT>` for resumable
upload RPCs in `gax` and `gapic-generator-java`.
- Wrap `ResumableUploadStartCallable` with `HttpJsonExceptionCallable`
and `Callables.retrying` to retry transient failures on the initial
`start` upload call.
- Regenerate `java-showcase` resumable upload classes and update tests.

Author: blakeli0

.github/workflows/sdk-platform-java-ci.yaml

@@ -280,7 +280,6 @@ jobs:
         with:
           java-version: 8
           distribution: temurin
-          cache: maven
       - run: java -version
       - name: Run tests in Java 8 with the source compiled in Java 11 for gapic-generator-java
         shell: bash

.github/workflows/showcase.yaml

@@ -50,7 +50,6 @@ jobs:
         with:
           java-version: 8
           distribution: temurin
-          cache: maven
       - run: java -version
       - name: Parse showcase version
         working-directory: java-showcase/gapic-showcase
@@ -155,7 +154,6 @@ jobs:
         with:
           java-version: 17
           distribution: temurin
-          cache: maven
       - name: Showcase golden tests
         working-directory: java-showcase
         run: |
@@ -168,7 +166,6 @@ jobs:
         with:
           java-version: ${{ matrix.java }}
           distribution: temurin
-          cache: maven
       - name: Parse showcase version
         working-directory: java-showcase/gapic-showcase
         run: echo "SHOWCASE_VERSION=$(mvn help:evaluate -Dexpression=gapic-showcase.version -q -DforceStdout)" >> "$GITHUB_ENV"

java-showcase/gapic-showcase/src/main/java/com/google/showcase/v1beta1/ResumableUploadServiceClient.java

@@ -25,8 +25,8 @@
 import com.google.api.gax.paging.AbstractPagedListResponse;
 import com.google.api.gax.rpc.ApiExceptions;
 import com.google.api.gax.rpc.PageContext;
-import com.google.api.gax.rpc.ResumableUploadCallSettings;
 import com.google.api.gax.rpc.ResumableUploadCallable;
+import com.google.api.gax.rpc.ResumableUploadOptions;
 import com.google.api.gax.rpc.UnaryCallable;
 import com.google.cloud.location.GetLocationRequest;
 import com.google.cloud.location.ListLocationsRequest;
@@ -85,7 +85,7 @@
  *      <td>
  *      <p>Request object method variants only take one parameter, a request object, which must be constructed before the call.</p>
  *      <ul>
- *           <li><p> uploadMedia(UploadMediaRequest request, InputStream payload, ResumableUploadCallSettings callSettings)
+ *           <li><p> uploadMedia(UploadMediaRequest request, InputStream payload, ResumableUploadOptions options)
  *      </ul>
  *      <p>Callable method variants take no parameters and return an immutable API callable object, which can be used to initiate calls to the service.</p>
  *      <ul>
@@ -283,15 +283,13 @@ public ResumableUploadServiceStub getStub() {
    *
    * @param request The request object containing all of the parameters for the API call.
    * @param payload The payload data stream to upload.
-   * @param callSettings The call settings to apply to this upload, or null to use defaults.
+   * @param options The options to apply to this upload, or null to use defaults.
    * @throws com.google.api.gax.rpc.ApiException if the remote call fails
    */
   public final UploadMediaResponse uploadMedia(
-      UploadMediaRequest request,
-      InputStream payload,
-      @Nullable ResumableUploadCallSettings callSettings) {
+      UploadMediaRequest request, InputStream payload, @Nullable ResumableUploadOptions options) {
     return ApiExceptions.callAndTranslateApiException(
-        uploadMediaCallable().futureCall(request, payload, callSettings));
+        uploadMediaCallable().futureCall(request, payload, options));
   }
 
   // AUTO-GENERATED DOCUMENTATION AND METHOD.

java-showcase/gapic-showcase/src/main/java/com/google/showcase/v1beta1/ResumableUploadServiceSettings.java

@@ -28,7 +28,6 @@
 import com.google.api.gax.rpc.ClientContext;
 import com.google.api.gax.rpc.ClientSettings;
 import com.google.api.gax.rpc.PagedCallSettings;
-import com.google.api.gax.rpc.ResumableUploadCallSettings;
 import com.google.api.gax.rpc.TransportChannelProvider;
 import com.google.api.gax.rpc.UnaryCallSettings;
 import com.google.cloud.location.GetLocationRequest;
@@ -104,7 +103,7 @@
 public class ResumableUploadServiceSettings extends ClientSettings<ResumableUploadServiceSettings> {
 
   /** Returns the object with the settings used for calls to uploadMedia. */
-  public ResumableUploadCallSettings uploadMediaSettings() {
+  public UnaryCallSettings<UploadMediaRequest, UploadMediaResponse> uploadMediaSettings() {
     return ((ResumableUploadServiceStubSettings) getStubSettings()).uploadMediaSettings();
   }
 
@@ -249,7 +248,8 @@ public Builder applyToAllUnaryMethods(
     }
 
     /** Returns the builder for the settings used for calls to uploadMedia. */
-    public ResumableUploadCallSettings.Builder uploadMediaSettings() {
+    public UnaryCallSettings.Builder<UploadMediaRequest, UploadMediaResponse>
+        uploadMediaSettings() {
       return getStubSettingsBuilder().uploadMediaSettings();
     }
 

java-showcase/gapic-showcase/src/main/java/com/google/showcase/v1beta1/stub/ResumableUploadServiceStubSettings.java

@@ -42,7 +42,6 @@
 import com.google.api.gax.rpc.PagedCallSettings;
 import com.google.api.gax.rpc.PagedListDescriptor;
 import com.google.api.gax.rpc.PagedListResponseFactory;
-import com.google.api.gax.rpc.ResumableUploadCallSettings;
 import com.google.api.gax.rpc.StatusCode;
 import com.google.api.gax.rpc.StubSettings;
 import com.google.api.gax.rpc.TransportChannelProvider;
@@ -61,6 +60,8 @@
 import com.google.iam.v1.SetIamPolicyRequest;
 import com.google.iam.v1.TestIamPermissionsRequest;
 import com.google.iam.v1.TestIamPermissionsResponse;
+import com.google.showcase.v1beta1.UploadMediaRequest;
+import com.google.showcase.v1beta1.UploadMediaResponse;
 import java.io.IOException;
 import java.time.Duration;
 import java.util.List;
@@ -129,7 +130,7 @@ public class ResumableUploadServiceStubSettings
   private static final ImmutableList<String> DEFAULT_SERVICE_SCOPES =
       ImmutableList.<String>builder().build();
 
-  private final ResumableUploadCallSettings uploadMediaSettings;
+  private final UnaryCallSettings<UploadMediaRequest, UploadMediaResponse> uploadMediaSettings;
   private final PagedCallSettings<
           ListLocationsRequest, ListLocationsResponse, ListLocationsPagedResponse>
       listLocationsSettings;
@@ -191,7 +192,7 @@ public ApiFuture<ListLocationsPagedResponse> getFuturePagedResponse(
           };
 
   /** Returns the object with the settings used for calls to uploadMedia. */
-  public ResumableUploadCallSettings uploadMediaSettings() {
+  public UnaryCallSettings<UploadMediaRequest, UploadMediaResponse> uploadMediaSettings() {
     return uploadMediaSettings;
   }
 
@@ -348,7 +349,8 @@ protected LibraryMetadata getLibraryMetadata() {
   public static class Builder
       extends StubSettings.Builder<ResumableUploadServiceStubSettings, Builder> {
     private final ImmutableList<UnaryCallSettings.Builder<?, ?>> unaryMethodSettingsBuilders;
-    private final ResumableUploadCallSettings.Builder uploadMediaSettings;
+    private final UnaryCallSettings.Builder<UploadMediaRequest, UploadMediaResponse>
+        uploadMediaSettings;
     private final PagedCallSettings.Builder<
             ListLocationsRequest, ListLocationsResponse, ListLocationsPagedResponse>
         listLocationsSettings;
@@ -391,7 +393,7 @@ protected Builder() {
     protected Builder(@Nullable ClientContext clientContext) {
       super(clientContext);
 
-      uploadMediaSettings = ResumableUploadCallSettings.newBuilder();
+      uploadMediaSettings = UnaryCallSettings.newUnaryCallSettingsBuilder();
       listLocationsSettings = PagedCallSettings.newBuilder(LIST_LOCATIONS_PAGE_STR_FACT);
       getLocationSettings = UnaryCallSettings.newUnaryCallSettingsBuilder();
       setIamPolicySettings = UnaryCallSettings.newUnaryCallSettingsBuilder();
@@ -400,6 +402,7 @@ protected Builder(@Nullable ClientContext clientContext) {
 
       unaryMethodSettingsBuilders =
           ImmutableList.<UnaryCallSettings.Builder<?, ?>>of(
+              uploadMediaSettings,
               listLocationsSettings,
               getLocationSettings,
               setIamPolicySettings,
@@ -420,6 +423,7 @@ protected Builder(ResumableUploadServiceStubSettings settings) {
 
       unaryMethodSettingsBuilders =
           ImmutableList.<UnaryCallSettings.Builder<?, ?>>of(
+              uploadMediaSettings,
               listLocationsSettings,
               getLocationSettings,
               setIamPolicySettings,
@@ -452,7 +456,10 @@ private static Builder createHttpJsonDefault() {
     }
 
     private static Builder initDefaults(Builder builder) {
-      builder.uploadMediaSettings().setGlobalTimeout(Duration.ofMillis(5000L));
+      builder
+          .uploadMediaSettings()
+          .setRetryableCodes(RETRYABLE_CODE_DEFINITIONS.get("no_retry_0_codes"))
+          .setRetrySettings(RETRY_PARAM_DEFINITIONS.get("no_retry_0_params"));
 
       builder
           .listLocationsSettings()
@@ -505,7 +512,8 @@ public Builder applyToAllUnaryMethods(
     }
 
     /** Returns the builder for the settings used for calls to uploadMedia. */
-    public ResumableUploadCallSettings.Builder uploadMediaSettings() {
+    public UnaryCallSettings.Builder<UploadMediaRequest, UploadMediaResponse>
+        uploadMediaSettings() {
       return uploadMediaSettings;
     }
 

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

@@ -18,8 +18,8 @@
 
 import static com.google.common.truth.Truth.assertThat;
 
-import com.google.api.gax.rpc.ResumableUploadCallSettings;
 import com.google.api.gax.rpc.ResumableUploadFuture;
+import com.google.api.gax.rpc.ResumableUploadOptions;
 import com.google.showcase.v1beta1.ResumableUploadServiceClient;
 import com.google.showcase.v1beta1.UploadMediaRequest;
 import com.google.showcase.v1beta1.UploadMediaResponse;
@@ -41,6 +41,8 @@
 class ITResumableUpload {
 
   private static final int SHOWCASE_CHUNK_SIZE = 256 * 1024; // 256KB
+  private static final ResumableUploadOptions DEFAULT_TEST_OPTIONS =
+      ResumableUploadOptions.newBuilder().setChunkSize(SHOWCASE_CHUNK_SIZE).build();
   private static ResumableUploadServiceClient client;
 
   @BeforeAll
@@ -69,7 +71,7 @@ void testGeneratedClient_uploadMedia_synchronousConvenienceMethod(@TempDir Path
         UploadMediaRequest.newBuilder().setName("it-client-sync.txt").build();
 
     try (InputStream stream = Files.newInputStream(file)) {
-      UploadMediaResponse response = client.uploadMedia(request, stream, null);
+      UploadMediaResponse response = client.uploadMedia(request, stream, DEFAULT_TEST_OPTIONS);
       assertThat(response.getName()).isEqualTo("it-client-sync.txt");
       assertThat(response.getSize()).isEqualTo(Files.size(file));
     }
@@ -89,9 +91,7 @@ void testGeneratedClient_uploadMediaCallable_asynchronousFutureCall(@TempDir Pat
 
     try (InputStream stream = Files.newInputStream(file)) {
       ResumableUploadFuture<UploadMediaResponse> future =
-          client
-              .uploadMediaCallable()
-              .futureCall(request, stream, (ResumableUploadCallSettings) null);
+          client.uploadMediaCallable().futureCall(request, stream, (ResumableUploadOptions) null);
 
       UploadMediaResponse response = future.get(10, TimeUnit.SECONDS);
       assertThat(future.isDone()).isTrue();
@@ -112,7 +112,7 @@ void testGeneratedClient_multiChunkUpload(@TempDir Path tempDir) throws Exceptio
         UploadMediaRequest.newBuilder().setName("it-client-multi-chunk.txt").build();
 
     try (InputStream stream = Files.newInputStream(file)) {
-      UploadMediaResponse response = client.uploadMedia(request, stream, null);
+      UploadMediaResponse response = client.uploadMedia(request, stream, DEFAULT_TEST_OPTIONS);
       assertThat(response.getName()).isEqualTo("it-client-multi-chunk.txt");
       assertThat(response.getSize()).isEqualTo(Files.size(file));
     }
@@ -133,7 +133,8 @@ void testGeneratedClient_grpcClientDelegation_uploadMedia(@TempDir Path tempDir)
     try (ResumableUploadServiceClient grpcClient =
         TestClientInitializer.createGrpcResumableUploadClient(SHOWCASE_CHUNK_SIZE)) {
       try (InputStream stream = Files.newInputStream(file)) {
-        UploadMediaResponse response = grpcClient.uploadMedia(request, stream, null);
+        UploadMediaResponse response =
+            grpcClient.uploadMedia(request, stream, DEFAULT_TEST_OPTIONS);
         assertThat(response.getName()).isEqualTo("it-grpc-delegation.txt");
         assertThat(response.getSize()).isEqualTo(Files.size(file));
       }
@@ -142,7 +143,7 @@ void testGeneratedClient_grpcClientDelegation_uploadMedia(@TempDir Path tempDir)
         ResumableUploadFuture<UploadMediaResponse> future =
             grpcClient
                 .uploadMediaCallable()
-                .futureCall(request, stream, (ResumableUploadCallSettings) null);
+                .futureCall(request, stream, (ResumableUploadOptions) null);
         UploadMediaResponse response = future.get(10, TimeUnit.SECONDS);
         assertThat(future.isDone()).isTrue();
         assertThat(future.isCancelled()).isFalse();
@@ -155,18 +156,17 @@ void testGeneratedClient_grpcClientDelegation_uploadMedia(@TempDir Path tempDir)
   }
 
   @Test
-  void testGeneratedClient_uploadMedia_withCustomCallSettings(@TempDir Path tempDir)
-      throws Exception {
+  void testGeneratedClient_uploadMedia_withCustomOptions(@TempDir Path tempDir) throws Exception {
     // 600KB payload with custom per-call 512KB chunk size override (default is 256KB)
     int totalBytes = 600 * 1024;
     Path file = createTempFile(tempDir, "it-client-custom-call-settings.txt", totalBytes);
     UploadMediaRequest request =
         UploadMediaRequest.newBuilder().setName("it-client-custom-call-settings.txt").build();
-    ResumableUploadCallSettings callSettings =
-        ResumableUploadCallSettings.newBuilder().setChunkSize(512 * 1024).build();
+    ResumableUploadOptions options =
+        ResumableUploadOptions.newBuilder().setChunkSize(512 * 1024).build();
 
     try (InputStream stream = Files.newInputStream(file)) {
-      UploadMediaResponse response = client.uploadMedia(request, stream, callSettings);
+      UploadMediaResponse response = client.uploadMedia(request, stream, options);
       assertThat(response.getName()).isEqualTo("it-client-custom-call-settings.txt");
       assertThat(response.getSize()).isEqualTo(Files.size(file));
     }

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

@@ -553,7 +553,6 @@ public static ResumableUploadServiceClient createHttpJsonResumableUploadClient(i
                 .setHttpTransport(new NetHttpTransport.Builder().doNotValidateCertificate().build())
                 .setEndpoint(DEFAULT_HTTPJSON_ENDPOINT)
                 .build());
-    settingsBuilder.uploadMediaSettings().setChunkSize(chunkSize);
     return ResumableUploadServiceClient.create(settingsBuilder.build());
   }
 
@@ -568,7 +567,6 @@ public static ResumableUploadServiceClient createGrpcResumableUploadClient(int c
                     .setChannelConfigurator(ManagedChannelBuilder::usePlaintext)
                     .build())
             .setEndpoint(DEFAULT_HTTPJSON_ENDPOINT);
-    settingsBuilder.uploadMediaSettings().setChunkSize(chunkSize);
     return ResumableUploadServiceClient.create(settingsBuilder.build());
   }
 }

sdk-platform-java/gapic-generator-java/src/main/java/com/google/api/generator/gapic/composer/comment/ServiceClientCommentComposer.java

@@ -46,9 +46,9 @@ public class ServiceClientCommentComposer {
       "The request object containing all of the parameters for the API call.";
   private static final String PAYLOAD_PARAM_NAME = "payload";
   private static final String PAYLOAD_PARAM_DESCRIPTION = "The payload data stream to upload.";
-  private static final String CALL_SETTINGS_PARAM_NAME = "callSettings";
-  private static final String CALL_SETTINGS_PARAM_DESCRIPTION =
-      "The call settings to apply to this upload, or null to use defaults.";
+  private static final String OPTIONS_PARAM_NAME = "options";
+  private static final String OPTIONS_PARAM_DESCRIPTION =
+      "The options to apply to this upload, or null to use defaults.";
 
   // Constants.
   private static final String SERVICE_DESCRIPTION_INTRO_STRING =
@@ -214,7 +214,7 @@ public static List<CommentStatement> createRpcMethodHeaderComment(
 
     if (method.isResumableUpload()) {
       methodJavadocBuilder.addParam(PAYLOAD_PARAM_NAME, PAYLOAD_PARAM_DESCRIPTION);
-      methodJavadocBuilder.addParam(CALL_SETTINGS_PARAM_NAME, CALL_SETTINGS_PARAM_DESCRIPTION);
+      methodJavadocBuilder.addParam(OPTIONS_PARAM_NAME, OPTIONS_PARAM_DESCRIPTION);
     }
 
     methodJavadocBuilder.setThrows(API_EXCEPTION_TYPE_NAME, EXCEPTION_CONDITION);

sdk-platform-java/gapic-generator-java/src/main/java/com/google/api/generator/gapic/composer/comment/SettingsCommentComposer.java

@@ -41,13 +41,19 @@ public class SettingsCommentComposer {
   private static final String CLASS_HEADER_DEFAULT_ADDRESS_PORT_PATTERN =
       "The default service address (%s) and default port (%d) are used.";
   private static final String CLASS_HEADER_SAMPLE_CODE_PATTERN =
-      "For example, to set the [RetrySettings](https://cloud.google.com/java/docs/reference/gax/latest/com.google.api.gax.retrying.RetrySettings) of %s:";
+      "For example, to set the"
+          + " [RetrySettings](https://cloud.google.com/java/docs/reference/gax/latest/com.google.api.gax.retrying.RetrySettings)"
+          + " of %s:";
 
   private static final String CLASS_HEADER_LRO_SAMPLE_CODE_PATTERN =
-      "To configure the RetrySettings of a Long Running Operation method, create an OperationTimedPollAlgorithm object and update the RPC's polling algorithm. For example, to configure the RetrySettings for %s:";
+      "To configure the RetrySettings of a Long Running Operation method, create an"
+          + " OperationTimedPollAlgorithm object and update the RPC's polling algorithm. For"
+          + " example, to configure the RetrySettings for %s:";
 
   private static final String CLASS_HEADER_SAMPLE_CODE_SUFFIX =
-      "Please refer to the [Client Side Retry Guide](https://docs.cloud.google.com/java/docs/client-retries) for additional support in setting retries.";
+      "Please refer to the [Client Side Retry"
+          + " Guide](https://docs.cloud.google.com/java/docs/client-retries) for additional support"
+          + " in setting retries.";
 
   private static final String CLASS_HEADER_BUILDER_DESCRIPTION =
       "The builder of this class is recursive, so contained classes are themselves builders. When"
@@ -134,11 +140,6 @@ public static CommentStatement createCallSettingsGetterComment(
         isMethodInternal);
   }
 
-  public static CommentStatement createResumableUploadCallSettingsGetterComment(
-      String javaMethodName, boolean isMethodDeprecated, boolean isMethodInternal) {
-    return createCallSettingsGetterComment(javaMethodName, isMethodDeprecated, isMethodInternal);
-  }
-
   public static CommentStatement createBuilderClassComment(String outerClassName) {
     return toCommentStatement(String.format(BUILDER_CLASS_DOC_PATTERN, outerClassName));
   }
@@ -149,12 +150,6 @@ public static CommentStatement createCallSettingsBuilderGetterComment(
     return toCommentStatement(methodComment, isMethodDeprecated, isMethodInternal);
   }
 
-  public static CommentStatement createResumableUploadCallSettingsBuilderGetterComment(
-      String javaMethodName, boolean isMethodDeprecated, boolean isMethodInternal) {
-    return createCallSettingsBuilderGetterComment(
-        javaMethodName, isMethodDeprecated, isMethodInternal);
-  }
-
   public static List<CommentStatement> createClassHeaderComments(
       String configuredClassName,
       String defaultHost,