feat(generator): emit callable getter and convenience method for resumable upload RPCs

- In AbstractServiceStubClassComposer: emit public ResumableUploadCallable<RequestT, ResponseT> [method]Callable() throwing UnsupportedOperationException
- In AbstractServiceClientClassComposer: emit public ResumableUploadCallable<RequestT, ResponseT> [method]Callable() delegating to stub
- In AbstractServiceClientClassComposer: emit synchronous convenience method [method](RequestT request, InputStream payload) calling ApiExceptions.callAndTranslateApiException
- Suppress method variants (flattened methods) for resumable upload RPCs
- In ServiceClientCommentComposer: emit Javadoc call context override warning on both callable method and synchronous convenience method
- Add unit test ResumableUploadServiceClientComposerTest verifying generated stub and client methods

Author: whowes

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

@@ -93,6 +93,11 @@ public class ServiceClientCommentComposer {
           + " that it is easy to make a subclass, but otherwise, the static factory methods"
           + " should be preferred.";
 
+  private static final String RESUMABLE_UPLOAD_CALL_CONTEXT_WARNING =
+      "Call context overrides (such as withTimeout, withRetrySettings, or credentials) apply"
+          + " strictly to the start request (session initiation). Per-chunk PUT calls rely on"
+          + " the configured timeout and retry settings from ResumableUploadCallSettings.";
+
   // Comments.
   public static final CommentStatement GET_OPERATIONS_CLIENT_METHOD_COMMENT =
       toSimpleComment(
@@ -233,13 +238,17 @@ private static MethodAndVariants createMethodAndVariants(
 
   private static String createTableOfMethods(List<MethodAndVariants> methodAndVariantsList) {
     String FLATTENED_METHODS =
-        "<p>\"Flattened\" method variants have converted the fields of the request object into function parameters to enable multiple ways to call the same method.</p>\n";
+        "<p>\"Flattened\" method variants have converted the fields of the request object into"
+            + " function parameters to enable multiple ways to call the same method.</p>\n";
     String REQUEST_OBJECT_METHODS =
-        "<p>Request object method variants only take one parameter, a request object, which must be constructed before the call.</p>\n";
+        "<p>Request object method variants only take one parameter, a request object, which must be"
+            + " constructed before the call.</p>\n";
     String CALLABLE_METHODS =
-        "<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>\n";
+        "<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>\n";
     String ASYNC_METHODS =
-        "<p>Methods that return long-running operations have \"Async\" method variants that return `OperationFuture`, which is used to track polling of the service.</p>\n";
+        "<p>Methods that return long-running operations have \"Async\" method variants that return"
+            + " `OperationFuture`, which is used to track polling of the service.</p>\n";
 
     StringBuilder tableBuilder = new StringBuilder();
     tableBuilder
@@ -348,8 +357,12 @@ public static List<CommentStatement> createRpcCallableMethodHeaderComment(
       methodJavadocBuilder = methodJavadocBuilder.addUnescapedComment(descriptionComment);
     }
 
-    methodJavadocBuilder.addParagraph(METHOD_DESCRIPTION_SAMPLE_CODE_SUMMARY_STRING);
+    if (method.isResumableUpload()) {
+      methodJavadocBuilder.addParagraph(RESUMABLE_UPLOAD_CALL_CONTEXT_WARNING);
+    }
+
     if (sampleCodeOpt.isPresent()) {
+      methodJavadocBuilder.addParagraph(METHOD_DESCRIPTION_SAMPLE_CODE_SUMMARY_STRING);
       methodJavadocBuilder.addSampleCode(sampleCodeOpt.get());
     }
 
@@ -366,6 +379,40 @@ public static List<CommentStatement> createRpcCallableMethodHeaderComment(
         CommentStatement.withComment(methodJavadocBuilder.build()));
   }
 
+  public static List<CommentStatement> createResumableUploadRpcMethodHeaderComment(Method method) {
+    JavaDocComment.Builder methodJavadocBuilder = JavaDocComment.builder();
+
+    if (method.hasDescription()) {
+      String descriptionComment =
+          CommentFormatter.formatAsJavaDocComment(method.description(), null);
+      methodJavadocBuilder = methodJavadocBuilder.addUnescapedComment(descriptionComment);
+    }
+
+    methodJavadocBuilder.addParagraph(RESUMABLE_UPLOAD_CALL_CONTEXT_WARNING);
+
+    methodJavadocBuilder.addParam(
+        "request", "The request object containing all of the parameters for the API call.");
+    methodJavadocBuilder.addParam("payload", "The payload data stream to upload.");
+
+    methodJavadocBuilder.setThrows(API_EXCEPTION_TYPE_NAME, EXCEPTION_CONDITION);
+
+    if (method.isDeprecated()) {
+      methodJavadocBuilder.setDeprecated(CommentComposer.DEPRECATED_METHOD_STRING);
+    }
+
+    if (method.isInternalApi()) {
+      methodJavadocBuilder.setInternalOnly(CommentComposer.INTERNAL_ONLY_METHOD_STRING);
+    }
+
+    List<CommentStatement> comments = new ArrayList<>();
+    comments.add(CommentComposer.AUTO_GENERATED_METHOD_COMMENT);
+    if (!methodJavadocBuilder.emptyComments()) {
+      comments.add(CommentStatement.withComment(methodJavadocBuilder.build()));
+    }
+
+    return comments;
+  }
+
   private static CommentStatement toSimpleComment(String comment) {
     return CommentStatement.withComment(JavaDocComment.withComment(comment));
   }

sdk-platform-java/gapic-generator-java/src/main/java/com/google/api/generator/gapic/composer/common/AbstractServiceClientClassComposer.java

@@ -24,10 +24,12 @@
 import com.google.api.gax.paging.AbstractFixedSizeCollection;
 import com.google.api.gax.paging.AbstractPage;
 import com.google.api.gax.paging.AbstractPagedListResponse;
+import com.google.api.gax.rpc.ApiExceptions;
 import com.google.api.gax.rpc.BidiStreamingCallable;
 import com.google.api.gax.rpc.ClientStreamingCallable;
 import com.google.api.gax.rpc.OperationCallable;
 import com.google.api.gax.rpc.PageContext;
+import com.google.api.gax.rpc.ResumableUploadCallable;
 import com.google.api.gax.rpc.ServerStreamingCallable;
 import com.google.api.gax.rpc.UnaryCallable;
 import com.google.api.generator.engine.ast.AnnotationNode;
@@ -88,6 +90,7 @@
 import com.google.longrunning.Operation;
 import com.google.rpc.Status;
 import java.io.IOException;
+import java.io.InputStream;
 import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.Collections;
@@ -650,42 +653,46 @@ private static List<MethodDefinition> createServiceMethods(
         methodVariantsForClientHeader.put(method.name(), new ArrayList<>());
       }
       if (method.stream().equals(Stream.NONE)) {
-        List<MethodDefinition> generatedMethods =
-            createMethodVariants(
-                method,
-                ClassNames.getServiceClientClassName(service),
-                messageTypes,
-                typeStore,
-                resourceNames,
-                samples,
-                service);
-
-        // Collect data for gapic_metadata.json.
-        grpcRpcToJavaMethodMetadata
-            .get(method.name())
-            .addAll(
-                generatedMethods.stream()
-                    .map(m -> javaMethodNameFn.apply(m))
-                    .collect(Collectors.toList()));
-
-        // Collect data for Client header
-        methodVariantsForClientHeader
-            .get(method.name())
-            .addAll(
-                generatedMethods.stream()
-                    .map(AbstractServiceClientClassComposer::getJavaMethod)
-                    .collect(Collectors.toList()));
-        javaMethods.addAll(generatedMethods);
+        if (!method.isResumableUpload()) {
+          List<MethodDefinition> generatedMethods =
+              createMethodVariants(
+                  method,
+                  ClassNames.getServiceClientClassName(service),
+                  messageTypes,
+                  typeStore,
+                  resourceNames,
+                  samples,
+                  service);
+
+          // Collect data for gapic_metadata.json.
+          grpcRpcToJavaMethodMetadata
+              .get(method.name())
+              .addAll(
+                  generatedMethods.stream()
+                      .map(m -> javaMethodNameFn.apply(m))
+                      .collect(Collectors.toList()));
+
+          // Collect data for Client header
+          methodVariantsForClientHeader
+              .get(method.name())
+              .addAll(
+                  generatedMethods.stream()
+                      .map(AbstractServiceClientClassComposer::getJavaMethod)
+                      .collect(Collectors.toList()));
+          javaMethods.addAll(generatedMethods);
+        }
 
         MethodDefinition generatedMethod =
-            createMethodDefaultMethod(
-                method,
-                ClassNames.getServiceClientClassName(service),
-                messageTypes,
-                typeStore,
-                resourceNames,
-                samples,
-                service);
+            method.isResumableUpload()
+                ? createResumableUploadDefaultMethod(method, typeStore)
+                : createMethodDefaultMethod(
+                    method,
+                    ClassNames.getServiceClientClassName(service),
+                    messageTypes,
+                    typeStore,
+                    resourceNames,
+                    samples,
+                    service);
 
         // Collect data for gapic_metadata.json and client header.
         grpcRpcToJavaMethodMetadata.get(method.name()).add(javaMethodNameFn.apply(generatedMethod));
@@ -928,6 +935,68 @@ private static MethodDefinition createMethodDefaultMethod(
     return methodBuilder.build();
   }
 
+  private static MethodDefinition createResumableUploadDefaultMethod(
+      Method method, TypeStore typeStore) {
+    String methodName = JavaStyle.toLowerCamelCase(method.name());
+    TypeNode methodInputType = method.inputType();
+    TypeNode methodOutputType = method.outputType();
+
+    VariableExpr requestArgVarExpr =
+        VariableExpr.builder()
+            .setVariable(Variable.builder().setName("request").setType(methodInputType).build())
+            .setIsDecl(true)
+            .build();
+    VariableExpr payloadArgVarExpr =
+        VariableExpr.builder()
+            .setVariable(
+                Variable.builder().setName("payload").setType(typeStore.get("InputStream")).build())
+            .setIsDecl(true)
+            .build();
+
+    String callableMethodName = String.format(CALLABLE_NAME_PATTERN, methodName);
+    MethodInvocationExpr callableMethodExpr =
+        MethodInvocationExpr.builder().setMethodName(callableMethodName).build();
+    MethodInvocationExpr futureCallExpr =
+        MethodInvocationExpr.builder()
+            .setExprReferenceExpr(callableMethodExpr)
+            .setMethodName("futureCall")
+            .setArguments(
+                Arrays.asList(
+                    requestArgVarExpr.toBuilder().setIsDecl(false).build(),
+                    payloadArgVarExpr.toBuilder().setIsDecl(false).build()))
+            .build();
+
+    MethodInvocationExpr callAndTranslateExpr =
+        MethodInvocationExpr.builder()
+            .setStaticReferenceType(typeStore.get("ApiExceptions"))
+            .setMethodName("callAndTranslateApiException")
+            .setArguments(Arrays.asList(futureCallExpr))
+            .setReturnType(methodOutputType)
+            .build();
+
+    MethodDefinition.Builder methodBuilder =
+        MethodDefinition.builder()
+            .setHeaderCommentStatements(
+                ServiceClientCommentComposer.createResumableUploadRpcMethodHeaderComment(method))
+            .setScope(ScopeNode.PUBLIC)
+            .setIsFinal(true)
+            .setName(methodName)
+            .setArguments(Arrays.asList(requestArgVarExpr, payloadArgVarExpr));
+
+    if (isProtoEmptyType(methodOutputType)) {
+      methodBuilder =
+          methodBuilder
+              .setBody(Arrays.asList(ExprStatement.withExpr(callAndTranslateExpr)))
+              .setReturnType(TypeNode.VOID);
+    } else {
+      methodBuilder =
+          methodBuilder.setReturnExpr(callAndTranslateExpr).setReturnType(methodOutputType);
+    }
+
+    methodBuilder.setAnnotations(createMethodAnnotations(method, typeStore));
+    return methodBuilder.build();
+  }
+
   private static MethodDefinition createLroCallableMethod(
       Service service,
       Method method,
@@ -992,7 +1061,9 @@ private static MethodDefinition createCallableMethod(
         case NONE:
         // Fall through.
         default:
-          rawCallableReturnType = typeStore.get("UnaryCallable");
+          rawCallableReturnType =
+              typeStore.get(
+                  method.isResumableUpload() ? "ResumableUploadCallable" : "UnaryCallable");
       }
     }
 
@@ -1036,7 +1107,9 @@ private static MethodDefinition createCallableMethod(
                   messageTypes,
                   service));
     } else if (callableMethodKind.equals(CallableMethodKind.REGULAR)) {
-      if (method.stream().equals(Stream.NONE)) {
+      if (method.isResumableUpload()) {
+        sampleCode = Optional.empty();
+      } else if (method.stream().equals(Stream.NONE)) {
         sampleCode =
             Optional.of(
                 ServiceClientCallableMethodSampleComposer.composeRegularCallableMethod(
@@ -1797,6 +1870,7 @@ private static TypeStore createTypes(Service service, Map<String, Message> messa
     List<Class<?>> concreteClazzes =
         Arrays.asList(
             AbstractPagedListResponse.class,
+            ApiExceptions.class,
             ApiFunction.class,
             ApiFuture.class,
             ApiFutures.class,
@@ -1806,6 +1880,7 @@ private static TypeStore createTypes(Service service, Map<String, Message> messa
             BidiStreamingCallable.class,
             ClientStreamingCallable.class,
             Generated.class,
+            InputStream.class,
             InterruptedException.class,
             IOException.class,
             MoreExecutors.class,
@@ -1814,6 +1889,7 @@ private static TypeStore createTypes(Service service, Map<String, Message> messa
             Operation.class,
             OperationFuture.class,
             OperationCallable.class,
+            ResumableUploadCallable.class,
             ServerStreamingCallable.class,
             Status.class,
             Strings.class,

sdk-platform-java/gapic-generator-java/src/main/java/com/google/api/generator/gapic/composer/common/AbstractServiceClientTestClassComposer.java

@@ -237,6 +237,10 @@ private List<MethodDefinition> createTestMethods(
         javaMethods.add(createUnsupportedTestMethod(method));
         continue;
       }
+      if (method.isResumableUpload()) {
+        javaMethods.add(createResumableUploadTestMethod(method));
+        continue;
+      }
       Service matchingService = service;
       if (method.isMixin()) {
         int dotIndex = method.mixedInApiName().lastIndexOf(".");
@@ -786,6 +790,29 @@ protected MethodDefinition createUnsupportedTestMethod(Method method) {
         .build();
   }
 
+  protected MethodDefinition createResumableUploadTestMethod(Method method) {
+    String javaMethodName = JavaStyle.toLowerCamelCase(method.name());
+    String testMethodName = String.format("%sTest", javaMethodName);
+
+    List<Statement> methodBody =
+        Collections.singletonList(
+            CommentStatement.withComment(
+                LineComment.withComment(
+                    "The "
+                        + javaMethodName
+                        + "() method requires a live HTTP/REST server supporting the resumable"
+                        + " upload protocol and is tested in integration tests.")));
+
+    return MethodDefinition.builder()
+        .setAnnotations(Arrays.asList(TEST_ANNOTATION))
+        .setScope(ScopeNode.PUBLIC)
+        .setReturnType(TypeNode.VOID)
+        .setName(testMethodName)
+        .setThrowsExceptions(Arrays.asList(TypeNode.withExceptionClazz(Exception.class)))
+        .setBody(methodBody)
+        .build();
+  }
+
   protected List<Statement> createRpcExceptionTestStatements(
       Method method,
       List<MethodArgument> methodSignature,