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

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

@@ -33,13 +33,19 @@
 import java.util.Optional;
 import java.util.stream.Collectors;
 import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
 
 @NullMarked
 public class ServiceClientCommentComposer {
   // Tokens.
   private static final String EMPTY_STRING = "";
   private static final String API_EXCEPTION_TYPE_NAME = "com.google.api.gax.rpc.ApiException";
   private static final String EXCEPTION_CONDITION = "if the remote call fails";
+  private static final String REQUEST_PARAM_NAME = "request";
+  private static final String REQUEST_PARAM_DESCRIPTION =
+      "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.";
 
   // Constants.
   private static final String SERVICE_DESCRIPTION_INTRO_STRING =
@@ -93,6 +99,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(
@@ -105,9 +116,9 @@ public static List<CommentStatement> createClassHeaderComments(
       String classMethodSampleCode,
       String credentialsSampleCode,
       String endpointSampleCode,
-      String transportSampleCode,
-      String primaryTransport,
-      String secondaryTransport) {
+      @Nullable String transportSampleCode,
+      @Nullable String primaryTransport,
+      @Nullable String secondaryTransport) {
     JavaDocComment.Builder classHeaderJavadocBuilder = JavaDocComment.builder();
     if (service.hasDescription()) {
       String descriptionComment =
@@ -187,14 +198,17 @@ public static List<CommentStatement> createRpcMethodHeaderComment(
       methodJavadocBuilder = methodJavadocBuilder.addUnescapedComment(descriptionComment);
     }
 
-    if (sampleCodeOpt.isPresent()) {
+    if (method.isResumableUpload()) {
+      methodJavadocBuilder.addParagraph(RESUMABLE_UPLOAD_CALL_CONTEXT_WARNING);
+    }
+
+    if (sampleCodeOpt.isPresent() && !method.isResumableUpload()) {
       methodJavadocBuilder.addParagraph(METHOD_DESCRIPTION_SAMPLE_CODE_SUMMARY_STRING);
       methodJavadocBuilder.addSampleCode(sampleCodeOpt.get());
     }
 
     if (methodArguments.isEmpty()) {
-      methodJavadocBuilder.addParam(
-          "request", "The request object containing all of the parameters for the API call.");
+      methodJavadocBuilder.addParam(REQUEST_PARAM_NAME, REQUEST_PARAM_DESCRIPTION);
     } else {
       for (MethodArgument argument : methodArguments) {
         // TODO(miraleung): Remove the newline replacement when we support CommonMark.
@@ -204,6 +218,10 @@ public static List<CommentStatement> createRpcMethodHeaderComment(
       }
     }
 
+    if (method.isResumableUpload()) {
+      methodJavadocBuilder.addParam(PAYLOAD_PARAM_NAME, PAYLOAD_PARAM_DESCRIPTION);
+    }
+
     methodJavadocBuilder.setThrows(API_EXCEPTION_TYPE_NAME, EXCEPTION_CONDITION);
 
     if (method.isDeprecated()) {
@@ -233,13 +251,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 +370,12 @@ public static List<CommentStatement> createRpcCallableMethodHeaderComment(
       methodJavadocBuilder = methodJavadocBuilder.addUnescapedComment(descriptionComment);
     }
 
-    methodJavadocBuilder.addParagraph(METHOD_DESCRIPTION_SAMPLE_CODE_SUMMARY_STRING);
-    if (sampleCodeOpt.isPresent()) {
+    if (method.isResumableUpload()) {
+      methodJavadocBuilder.addParagraph(RESUMABLE_UPLOAD_CALL_CONTEXT_WARNING);
+    }
+
+    if (sampleCodeOpt.isPresent() && !method.isResumableUpload()) {
+      methodJavadocBuilder.addParagraph(METHOD_DESCRIPTION_SAMPLE_CODE_SUMMARY_STRING);
       methodJavadocBuilder.addSampleCode(sampleCodeOpt.get());
     }
 

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

@@ -136,21 +136,14 @@ public static CommentStatement createCallSettingsGetterComment(
         isMethodInternal);
   }
 
+  private static final String RESUMABLE_UPLOAD_CALL_SETTINGS_DOC_NOTE =
+      "Note that custom retry settings and headers configured via ApiCallContext"
+          + " apply strictly to the initial session initiation request.";
+
   public static CommentStatement createResumableUploadCallSettingsGetterComment(
       String javaMethodName, boolean isMethodDeprecated, boolean isMethodInternal) {
-    JavaDocComment.Builder docBuilder =
-        JavaDocComment.builder()
-            .addComment(String.format(CALL_SETTINGS_METHOD_DOC_PATTERN, javaMethodName))
-            .addParagraph(
-                "Note that custom retry settings and headers configured via ApiCallContext"
-                    + " apply strictly to the initial session initiation request.");
-    if (isMethodDeprecated) {
-      docBuilder.setDeprecated(CommentComposer.DEPRECATED_METHOD_STRING);
-    }
-    if (isMethodInternal) {
-      docBuilder.setInternalOnly(CommentComposer.INTERNAL_ONLY_METHOD_STRING);
-    }
-    return CommentStatement.withComment(docBuilder.build());
+    return createResumableUploadCallSettingsComment(
+        CALL_SETTINGS_METHOD_DOC_PATTERN, javaMethodName, isMethodDeprecated, isMethodInternal);
   }
 
   public static CommentStatement createBuilderClassComment(String outerClassName) {
@@ -165,12 +158,19 @@ public static CommentStatement createCallSettingsBuilderGetterComment(
 
   public static CommentStatement createResumableUploadCallSettingsBuilderGetterComment(
       String javaMethodName, boolean isMethodDeprecated, boolean isMethodInternal) {
+    return createResumableUploadCallSettingsComment(
+        CALL_SETTINGS_BUILDER_METHOD_DOC_PATTERN,
+        javaMethodName,
+        isMethodDeprecated,
+        isMethodInternal);
+  }
+
+  private static CommentStatement createResumableUploadCallSettingsComment(
+      String pattern, String javaMethodName, boolean isMethodDeprecated, boolean isMethodInternal) {
     JavaDocComment.Builder docBuilder =
         JavaDocComment.builder()
-            .addComment(String.format(CALL_SETTINGS_BUILDER_METHOD_DOC_PATTERN, javaMethodName))
-            .addParagraph(
-                "Note that custom retry settings and headers configured via ApiCallContext"
-                    + " apply strictly to the initial session initiation request.");
+            .addComment(String.format(pattern, javaMethodName))
+            .addParagraph(RESUMABLE_UPLOAD_CALL_SETTINGS_DOC_NOTE);
     if (isMethodDeprecated) {
       docBuilder.setDeprecated(CommentComposer.DEPRECATED_METHOD_STRING);
     }